Skip to content

Swaps for AI agents

An AI agent that holds its own wallet key can swap through the Swap API with no website, no approval link and no person in the loop. The API builds and checks every swap; the agent signs on its own machine. Nothing is custodied: the API never sees or holds a key.

Start here: GET /api/instructions

One unauthenticated call returns everything an agent needs for the net it is talking to, generated from the live configuration:

  • every route /api/prepare supports, with how it signs (rfq+permit, permit2, evm-txs, sol-tx), how it is sent, and whether the agent pays gas
  • the contracts and chain ids to check payloads against
  • the steps, the error table with each code's action, the rules and the safety checks
  • how to sign the /api/orders request

Treat this response as the source of truth. This page explains the flow; it does not copy routes or addresses, because those can change per net. Confirm contract addresses against a second source, such as DEPLOYMENTS.md.

curl -s .../api/instructions

No login. The request carries the wallet address, and the signatures prove the agent holds it. /api/prepare, /api/status and /api/orders accept a partner x-api-key like the other protected routes; enforcement is in soft launch, so a missing key is logged, not refused. See Authentication.

The flow

  1. Learn. GET /api/instructions.
  2. Prepare. POST /api/prepare with the swap. The API reads the chain, builds the swap, checks it, and returns exactly what to sign.
  3. Prerequisites. If prerequisites is not empty, send each one first (for example a one-time Permit2 approval), wait for the receipt, then prepare again.
  4. Sign. Sign every entry in sign, in order. Check the token, amount and recipient before signing.
  5. Submit. If submit.type is post, POST submit.body to submit.path after filling the fields named in submit.fill. If it is broadcast, send the signed transaction yourself on submit.chain, one at a time, waiting for each receipt.
  6. Track. Poll track.path until terminal is true. Never submit the same swap twice.
  7. Recover. After a crash, GET /api/orders with a wallet signature lists the orders you prepared.

POST /api/prepare

curl -s -X POST .../api/prepare \
  -H 'content-type: application/json' \
  -d '{
    "user": "0xYourAgentWallet",
    "inSym": "SBC", "fromChain": "base",
    "outSym": "cfUSD", "toChain": "base",
    "uiAmount": "5",
    "idempotencyKey": "a-uuid-you-keep"
  }'
FieldRequiredMeaning
userYesThe wallet that signs and pays. EVM address or Solana base58
inSym, fromChainYesInput token and chain (base, solana, radius)
outSym, toChainYesOutput token and chain
uiAmountYesHuman amount, as a string
recipientBetween Base or Radius and SolanaWho receives the output on toChain: a Solana address for Base → Solana, an EVM address for Solana → Base. On same-chain and EVM-to-EVM swaps the output goes to user, so omit it
idempotencyKeyNoSend the same key again and you get the same order back, not a second one. Refused once that order has expired

The response (shortened):

{
  "prepareId": "prep_…",
  "net": "testnet",
  "route": { "inSym": "SBC", "fromChain": "base", "outSym": "cfUSD", "toChain": "base" },
  "amounts": { "inBase": "5000000", "outBase": "5000000", "minOutBase": "5000000", "inDecimals": 6, "outDecimals": 6 },
  "recipient": "0xYourAgentWallet",
  "expiresAt": 1794935999,
  "gasNeeded": false,
  "prerequisites": [],
  "sign": [
    { "id": "order",  "kind": "eip712", "payload": { "domain": {}, "types": {}, "primaryType": "RfqOrder", "message": {} } },
    { "id": "permit", "kind": "eip712", "payload": { "domain": {}, "types": {}, "primaryType": "Permit", "message": {} } }
  ],
  "submit": { "type": "post", "path": "/api/base/swap", "body": {}, "fill": { "orderSig": "order", "v": "permit.v", "r": "permit.r", "s": "permit.s" } },
  "track": { "statusId": "prep_…", "path": "/api/status/prep_…" }
}

Amounts ending in Base are integers in the token's smallest units. Check them against inDecimals and outDecimals: decimals differ by chain and by net.

sign entry kinds
kindHow to sign
eip712account.signTypedData(payload) (viem). viem and ethers add the EIP712Domain type themselves
evm-txwalletClient.sendTransaction(payload). Wait for the receipt before the next one
sol-txVersionedTransaction.deserialize(base64), tx.sign([keypair]), then send. Keep the solver's existing signature. Send straight away: it expires with its blockhash in about 60 seconds

submit.fill maps a body field to a sign id. A plain id means the whole signature; id.v, id.r and id.s mean its parts.

Who pays gas. On Base same-chain and Base → Solana (Permit2), the solver sends the transaction and pays the gas; Permit2 needs one approval the first time. On routes the agent broadcasts itself, it needs a little native gas. gasNeeded and each route's agentGas in /api/instructions say which.

Gas top-ups (buying ETH or SOL with a stable) are not offered through /api/prepare. /api/instructions lists them under notSupportedByPrepare; use the web app or the SBC CLI.

GET /api/status/{id}

Pass track.statusId from prepare, an order id, or a transaction hash. The answer is read from the chain, not from our records.

{ "id": "prep_…", "idKind": "order", "status": "confirmed", "terminal": true, "nextPollMs": 0, "deliverRef": null, "reason": null, "action": null }
statusTerminalMeaning
preparedNoBuilt, not seen on chain yet
pendingNoSent, waiting to land or to be delivered
attentionNoTaking longer than usual. Keep polling (every 30 s)
unknownNoNot readable right now. Keep polling; this says nothing about funds
confirmedYesSame-chain swap landed
claimedYesCross-chain swap delivered and settled. deliverRef is the delivery transaction
refundedYesCross-chain order expired and the input went back
expiredYesNever sent, and can no longer land. Prepare again
failedYesThe transaction reverted
check_balanceYesCan't be decided from the chain. Check the wallet before doing anything else

Poll every nextPollMs. Do not resubmit while a swap is not terminal: a resend can start a second swap.

GET /api/orders

Lists the orders a wallet prepared, each with its live status, so an agent that lost its state can find them again.

curl -s ".../api/orders?owner=0xYourAgentWallet" \
  -H "x-sbc-owner-signature: 0x…" \
  -H "x-sbc-owner-expires: 1794935999"

x-sbc-owner-expires is a unix time at most 300 seconds ahead. The signature proves the caller holds the wallet:

  • EVM wallets sign EIP-712 typed data OrdersAuth { owner, net, chainId, expiresAt } in the domain SBC Swap API, version 1. The exact template is under ordersAuth in /api/instructions.
  • Solana wallets sign the message bytes from ordersAuth.solana.message with ed25519 and send the signature in base58.

A signature is bound to one net, so a testnet signature is refused on mainnet. The list holds only orders made through /api/prepare, not swaps from the web app, MCP or CLI, so an empty list does not prove nothing is in flight. Smart-contract wallets (ERC-1271) can't sign it.

Errors

Every error tells the agent what to do next. See Errors for the fields and codes. The action is the part to branch on:

actionDo this
fix_requestChange the request, then send it again
re_prepareCall /api/prepare again
re_signSign the same payload again
wait_retryWait retryAfterMs, then retry
poll_statusCheck status first. Don't sign anything new until you know what happened
apply_for_accessThe wallet isn't approved on this net
stopStop and report

OUTCOME_UNKNOWN matters most: a transaction may have been sent. Check status with any id you hold, otherwise the wallet's balance. Never retry it blindly.

Rules and safety

  • Use a dedicated wallet holding only what the agent may spend. Nothing on the API limits what a key can sign.
  • Check every payload before signing: token, amount, recipient, and that each contract and spender is one listed in /api/instructions. On par routes minOutputAmount is never 0.
  • The Permit2 approval is unlimited, matching the web app. Any later Permit2 signature from that wallet can pull that token's full balance.
  • Never call settle or refund. They are operator routes; refunds after expiry are automatic.
  • Poll, don't resubmit. Run one same-chain Base swap per wallet at a time: the router nonce is sequential.
  • Send Radius transactions through a Radius RPC you hold, not the API's proxy, so you see the outcome directly.

Next steps