Same-chain swap flow

A same-chain swap is four steps. Only steps 1, 2, and 4 hit the API; signing happens in your own wallet. All token amounts are base units(wei / lamports / token decimals) unless you pass amount with amountUnit: "human".

1. POST /swap/quote — aggregated routes from 1inch, 0x, Jupiter, and indexed pools
2. EVM only: GET /swap/allowance → approve the router if allowance is too low
3. POST /swap/build — unsigned EVM calldata or base64 Solana transaction
4. Sign locally and broadcast (EVM via your RPC, Solana via POST /swap/submit-solana)
5. POST /swap/record — report the result for analytics and attribution

1. Quote

POST /api/swap/quote
Content-Type: application/json

{
  "chainKey": "ethereum",
  "tokenIn":  "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",  // WETH
  "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",  // USDC
  "amountIn": "1000000000000000000",                          // 1 WETH (base units)
  "slippageBps": 50,                                          // 0.50%
  "taker": "0xYourWalletAddress"
}

The response contains a ranked list of routes plus the best route. Each route includes amountOut, the venue/dexId, the platform fee, an estimated gas figure, and the spender address the wallet must approve (EVM).

{
  "best": { "dexId": "1inch-ethereum", "amountOut": "3187420000", "spender": "0x1111...", "route": { ... } },
  "quotes": [ { "dexId": "...", "amountOut": "...", "route": { ... } }, ... ],
  "feeBps": 30
}

Human-readable amounts

Instead of base-unit amountIn, pass amount + amountUnit: "human" when the token is in the catalog and the API will scale by decimals for you:

{ "chainKey": "bsc", "tokenIn": "...", "tokenOut": "...", "amount": "1.5", "amountUnit": "human", "taker": "0x..." }

2. Allowance & approval (EVM only)

Before a router can move an ERC-20, the wallet must approve it. Read the current allowance, and if it is below amountIn, send a standard ERC-20 approve() to the spender returned by the quote. Solana has no separate approval step.

GET /api/swap/allowance?chainKey=ethereum&token=0xA0b8...&owner=0xYou&spender=0x1111...
→ { "allowance": "0", "token": "...", "owner": "...", "spender": "...", "chainKey": "ethereum" }

Prefer an exact allowance over an unlimited one — see token approvals.

3. Build

Pass the chosen route (the best object or a row from quotes[]) and a minAmountOut derived from your slippage tolerance. The build is simulated server-side before it is returned.

POST /api/swap/build
{
  "request": { "chainKey": "ethereum", "tokenIn": "...", "tokenOut": "...", "amountIn": "...", "taker": "0x..." },
  "route": { ...the chosen quote route... },
  "minAmountOut": "3171000000"
}

EVM responses return { to, data, value, gas } calldata; Solana returns a base64 solanaTransaction.

4. Sign, send & record

• EVM: sendTransaction with the returned calldata via your wallet/RPC.
• Solana: sign the transaction bytes, then POST /swap/submit-solana.

POST /api/swap/record
{ "chainKey": "ethereum", "dexId": "1inch-ethereum", "tokenIn": "...", "tokenOut": "...",
  "amountIn": "1000000000000000000", "amountOut": "3187420000", "protocolFee": "...",
  "feeBps": 30, "txHash": "0x...", "address": "0xYou", "status": "confirmed",
  "source": "agent", "clientId": "my-bot-v1" }

Errors

Errors return a non-2xx status and { "error": { "message", "code" } }. Common codes:

• SAME_TOKEN — tokenIn equals tokenOut
• MISSING_PARAMS — a required field is absent
• NO_ROUTE — no executable route for this pair/amount
• HTTP 429 — rate limit hit; back off and retry

Always honour minAmountOut / slippageBps so trades revert rather than executing at a bad price, and re-quote if more than ~60s pass before signing.