Swap

Execute same-chain EVM token swaps without the AI agent. Get a quote first, then execute.

Quote

POST /wallet/swap-quote

Request Body

Field	Type	Required	Description
fromChain	string	Yes	Source chain — one of base, mainnet (Ethereum), polygon, unichain, arbitrum, bnb, worldchain, robinhood
fromToken	string	Yes	Sell token address (EVM address)
toChain	string	Yes	Must match fromChain (cross-chain not yet supported)
toToken	string	Yes	Buy token address (EVM address)
amount	string	Yes	Human-readable sell amount (e.g. "0.5")

Robinhood tokenized stocks

Swaps involving tokenized stocks on robinhood require a passed location check; without one the endpoint returns 403 with instructions to verify at the Bankr console.

Native gas tokens

For native ETH / POL / BNB, pass the native sentinel address 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee (the zero address works too) as fromToken / toToken — it's normalized automatically.

Response (200 OK)

from.amount mirrors the human-readable input (identical to from.formattedAmount), while to.amount is the quoted buy amount in raw base units.

{
  "from": {
    "chain": "base",
    "token": "0x4200000000000000000000000000000000000006",
    "amount": "0.5",
    "formattedAmount": "0.5",
    "symbol": "WETH",
    "decimals": 18,
    "usdValue": "1622.50"
  },
  "to": {
    "chain": "base",
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1622500000",
    "formattedAmount": "1622.50",
    "symbol": "USDC",
    "decimals": 6,
    "usdValue": "1622.50"
  },
  "minBuyAmount": "1622.50"
}

Errors

Status	Cause
400	Invalid body, unsupported chain, or fromChain !== toChain
401	Missing or invalid authentication
500	No quote available from the DEX aggregator

Execute

POST /wallet/swap

Request Body

All five quote fields, plus minBuyAmount:

Field	Type	Required	Description
fromChain	string	Yes	Source chain (see quote table above)
fromToken	string	Yes	Sell token address
toChain	string	Yes	Must match fromChain
toToken	string	Yes	Buy token address
amount	string	Yes	Human-readable sell amount
minBuyAmount	string	Yes	Minimum acceptable buy amount (from the quote response)

Response (200 OK)

{
  "success": true,
  "hash": "0xabc123...",
  "amountSold": 0.5,
  "amountReceived": 1622.5,
  "amountSoldRaw": "500000000000000000",
  "amountReceivedRaw": "1622500000"
}

Field	Type	Description
success	boolean	Whether the swap executed
hash	string	On-chain transaction hash
amountSold	number	Human-readable sell amount
amountReceived	number	Human-readable buy amount
amountSoldRaw	string	Sell amount in base units (bigint as string)
amountReceivedRaw	string	Buy amount in base units (bigint as string)

Errors

Status	Cause
400	Invalid body, unsupported chain, or swap validation failure
401	Missing or invalid authentication
403	Read-only API key, wallet paused, or a Bankr Terminal spend limit would be exceeded
500	Signer error, swap execution error, or DEX failure

Access Control

• Authentication: API key (X-API-Key) or Privy JWT
• Wallet API (walletApiEnabled): required for both endpoints
• Read-only keys: allowed for quotes, rejected for execution
• Allowed recipients: not enforced — swap output always returns to the caller's wallet
• Spend limits: enforced on execution — the sell-side USD value is priced and checked against your Bankr Terminal per-transaction and daily limits, and a successful swap counts toward your rolling 24h spend total

Constraints

• Same-chain only — fromChain and toChain must match; cross-chain swaps are not yet supported via this endpoint (use the Agent API for cross-chain)
• EVM chains only — Solana is not supported on this endpoint

Migration from Legacy Endpoints

POST /leaderboard/swap-quote and POST /leaderboard/swap are deprecated aliases that forward to these endpoints. They now return Deprecation and Sunset headers. Migrate to /wallet/swap-quote and /wallet/swap.

Examples

curl

# 1. Get a quote
curl -X POST https://api.bankr.bot/wallet/swap-quote \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "fromChain": "base",
    "fromToken": "0x4200000000000000000000000000000000000006",
    "toChain": "base",
    "toToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "0.5"
  }'

# 2. Execute the swap (use minBuyAmount from quote response)
curl -X POST https://api.bankr.bot/wallet/swap \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "fromChain": "base",
    "fromToken": "0x4200000000000000000000000000000000000006",
    "toChain": "base",
    "toToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "0.5",
    "minBuyAmount": "1622.50"
  }'