fia-risk-aware-swapper

Pre-swap risk gate for autonomous trading agents on Base.

Screens one or more EVM token addresses via the Fia Signals /token-safety/batch endpoint before handing off to a swap router. Payment is handled via the x402 protocol — bring your own funded wallet on Base USDC, pay 0.10 USDC per batch call.

Truth label: reference buyer agent for the Fia Signals x402 endpoint. Bring your own wallet — you pay per call.

---

What it does

1. Accepts --chain and --tokens (comma-separated EVM addresses).
2. Probes /token-safety/batch via x402 — gate returns safe, risky, or blocked per token.
3. Routes to one of three exits:
   • PROCEED — all tokens safe → calls the swap stub (replace with your router).
   • CAUTION — one or more risky → prints warnings, exits 2.
   • REJECT — one or more blocked → prints reasons, exits 1.
4. Logs every call to run.jsonl (timestamp, tokens, verdict, settle status).

Default mode is dry-run (no payment). Spend requires WALLET_PRIVATE_KEY env + --allow-spend flag.

---

Quick start — dry-run (no wallet needed)

Node requirement: Node.js ≥ 22 is required for --experimental-strip-types (runs TypeScript directly without a compile step). Run node --version to confirm before proceeding.

# TypeScript — recommended path (Node ≥22 required)
npm install
node --experimental-strip-types ts/risk-aware-swap.ts \
  --chain base \
  --tokens 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913,0x4200000000000000000000000000000000000006

# Python — dry-run only (see caveat below)
pip install -r py/requirements.txt
python3 py/risk_aware_swap.py \
  --chain base \
  --tokens 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913,0x4200000000000000000000000000000000000006

Dry-run prints the 402 challenge and decoded payment terms without spending anything.

---

Paid mode

TypeScript is the recommended paid path. It uses @x402/fetch + ExactEvmScheme, which handles EIP-712 signing, nonce generation, and facilitator encoding correctly. It has been validated against the live Fia Signals 402 challenge in dry-run mode. Run a small paid canary with your own funded wallet before relying on it in production.

cp examples/example.env .env
# Edit .env: set WALLET_PRIVATE_KEY=0x<your-key>
# (wallet must hold ≥0.10 USDC on Base mainnet)

node --experimental-strip-types ts/risk-aware-swap.ts \
  --chain base \
  --tokens 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --allow-spend

Python paid mode — not yet validated. py/risk_aware_swap.py includes a hand-rolled EIP-3009 TransferWithAuthorization signing path (make_x402_payment_header). Dry-run works against the live endpoint. The paid path (--allow-spend) has not been tested against the live CDP facilitator and may require adjustments to nonce encoding or signature format. Use the TypeScript path for paid calls until Python paid mode is explicitly validated.

See docs/wallet-setup.md for wallet funding instructions.

---

Payment details

Field	Value
Endpoint	https://x402.fiasignals.com/token-safety/batch
Price	0.10 USDC per call (up to 5 tokens)
Network	Base mainnet (eip155:8453)
Asset	USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Pay-to	0x8D32c6a3EE3fB8a8b4c5378F7C5a26CC320a853F
Protocol	x402 — ExactEvmScheme / EIP-3009

---

Structure

ts/risk-aware-swap.ts   main TypeScript entry point
ts/types.ts             Verdict, BatchResult type definitions
ts/swap-stub.ts         MOCK swap stub (replace with your router)
py/risk_aware_swap.py   Python equivalent
py/requirements.txt     httpx, eth-account
docs/wallet-setup.md    wallet funding and configuration guide
examples/example.env    env var template
examples/base-bluechips.json  example token list for dry-run

---

License

MIT