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/preparesupports, 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/ordersrequest
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/instructionsNo 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
- Learn.
GET /api/instructions. - Prepare.
POST /api/preparewith the swap. The API reads the chain, builds the swap, checks it, and returns exactly what to sign. - Prerequisites. If
prerequisitesis not empty, send each one first (for example a one-time Permit2 approval), wait for the receipt, then prepare again. - Sign. Sign every entry in
sign, in order. Check the token, amount and recipient before signing. - Submit. If
submit.typeispost, POSTsubmit.bodytosubmit.pathafter filling the fields named insubmit.fill. If it isbroadcast, send the signed transaction yourself onsubmit.chain, one at a time, waiting for each receipt. - Track. Poll
track.pathuntilterminalistrue. Never submit the same swap twice. - Recover. After a crash,
GET /api/orderswith 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"
}'| Field | Required | Meaning |
|---|---|---|
user | Yes | The wallet that signs and pays. EVM address or Solana base58 |
inSym, fromChain | Yes | Input token and chain (base, solana, radius) |
outSym, toChain | Yes | Output token and chain |
uiAmount | Yes | Human amount, as a string |
recipient | Between Base or Radius and Solana | Who 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 |
idempotencyKey | No | Send 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
kind | How to sign |
|---|---|
eip712 | account.signTypedData(payload) (viem). viem and ethers add the EIP712Domain type themselves |
evm-tx | walletClient.sendTransaction(payload). Wait for the receipt before the next one |
sol-tx | VersionedTransaction.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 }status | Terminal | Meaning |
|---|---|---|
prepared | No | Built, not seen on chain yet |
pending | No | Sent, waiting to land or to be delivered |
attention | No | Taking longer than usual. Keep polling (every 30 s) |
unknown | No | Not readable right now. Keep polling; this says nothing about funds |
confirmed | Yes | Same-chain swap landed |
claimed | Yes | Cross-chain swap delivered and settled. deliverRef is the delivery transaction |
refunded | Yes | Cross-chain order expired and the input went back |
expired | Yes | Never sent, and can no longer land. Prepare again |
failed | Yes | The transaction reverted |
check_balance | Yes | Can'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 domainSBC Swap API, version1. The exact template is underordersAuthin/api/instructions. - Solana wallets sign the message bytes from
ordersAuth.solana.messagewith 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:
action | Do this |
|---|---|
fix_request | Change the request, then send it again |
re_prepare | Call /api/prepare again |
re_sign | Sign the same payload again |
wait_retry | Wait retryAfterMs, then retry |
poll_status | Check status first. Don't sign anything new until you know what happened |
apply_for_access | The wallet isn't approved on this net |
stop | Stop 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 routesminOutputAmountis 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
- Overview: par pricing, errors, access
- Same-chain swaps and Cross-chain swaps: what each route does under the hood
- SBC CLI: the same swaps from a terminal, signed locally