# AgentOS Aggregator — token swaps for autonomous agents An HTTP API in front of 0x Swap API v2. You GET a URL; you get JSON back with a price, or with unsigned transaction calldata your wallet can sign and broadcast. Limit orders go through KyberSwap's order book instead — see "Limit orders". NON-CUSTODIAL BY CONSTRUCTION. This service holds no private key: it never signs and never broadcasts. Reading this API cannot move funds. A swap happens only when YOUR signer signs the calldata below and sends it to an RPC. No API key. No auth header. Every swap endpoint is a plain GET over HTTPS; only the limit-order writes are POST with a JSON body. Every response is JSON except this file (text/plain). ## Base URL Every path here is relative to the origin that served this file. If you fetched `https://agg.example/llms.txt`, then `/v1/quote` means `https://agg.example/v1/quote`. ## Chains chainId key name native wrapped native (WETH) 8453 base Base ETH (18 decimals) 0x4200000000000000000000000000000000000006 4663 robinhood Robinhood Chain ETH (18 decimals) 0x0bd7d308f8e1639fab988df18a8011f41eacad73 `chain=base` and `chain=8453` are the same thing; both forms are accepted everywhere. Anything else is `UNSUPPORTED_CHAIN`. `GET /v1/chains` is the live list — an operator can disable a chain, and then it disappears from there. READ THIS BEFORE PLANNING ANYTHING ON CHAIN 4663. The 29 tokenised-stock tokens on Robinhood Chain (AAPL, TSLA, NVDA, MSFT, SPY, QQQ, …) CANNOT BE TRADED, in either direction, at any size, at any time of day. 0x refuses them for legal reasons. Asking for one is `400 TOKEN_NOT_TRADEABLE`. The one way round it is the Uniswap source, and only where `GET /v1/chains` lists `uniswap` for the chain: then repeat the request with `source=uniswap`. Otherwise there is none. ETH, WETH and USDG on 4663 trade normally. Full detail in the "Robinhood Chain (4663)" section below. ## Endpoints GET /health liveness; answers even when the service is misconfigured GET /llms.txt this file GET /openapi.json OpenAPI 3.1 description of the same API GET /v1/chains supported chains GET /v1/tokens the symbol list for one chain GET /v1/price indicative price, no wallet needed, cached ~5s GET /v1/quote executable quote + unsigned calldata, taker required POST /v1/limit-orders/sign-message build a limit order to sign (EIP-712) POST /v1/limit-orders submit the signed order GET /v1/limit-orders a maker's orders POST /v1/limit-orders/cancel-sign gasless cancel: typed data to sign POST /v1/limit-orders/cancel gasless cancel: submit signature POST /v1/limit-orders/hard-cancel on-chain cancel: unsigned calldata ## The flow, in order 1. GET /v1/tokens?chain=base find symbols, and check BOTH sides are "tradeable": true 2. GET /v1/price?chain=...&sell=...&buy=... (optional) check the rate 3. GET /v1/quote?...&taker=0xYourWallet the real thing 4. if approval != null -> sign+send approval.transaction FIRST, wait for it to be mined 5. sign+send transaction {to, data, value, gas, gasPrice} 6. if more than ~30s have passed (see expiresAt), discard and re-quote. Never sign stale calldata. Step 1 is optional on Base, where every listed token is tradeable. It is NOT optional on chain 4663, where 29 of 34 listed tokens cannot be traded at all. Step 4 before step 5, always. The swap contract cannot pull your ERC-20 without the allowance; sending the swap first just burns gas on a revert. Selling the native coin (ETH) needs no approval — `approval` is `null` there and `transaction.value` carries the ETH instead. ## Shared request parameters (/v1/price and /v1/quote) chain required `base` | `robinhood` | `8453` | `4663` sell required symbol from /v1/tokens, a 0x… contract address, or `ETH` for the native coin buy required same forms as `sell`; must differ from `sell` sellAmount one of human units, e.g. `0.25` (needs known decimals) sellAmountRaw these two base units, e.g. `250000000000000000` slippageBps optional integer 1..500. Default 50 (= 0.5%) lang optional `en` (default) or `vi`. Changes `explanation` only source optional `0x` (default) or `uniswap`. Which liquidity API answers. See "The Uniswap source" below Rules that bite: - Exactly one of `sellAmount` / `sellAmountRaw`. Sending both is `INVALID_REQUEST`; sending neither is too. There is no `buyAmount` parameter — this API only sells an exact input. - Symbols are resolved ONLY against the bundled per-chain list. An unlisted symbol is `UNKNOWN_TOKEN` and is never guessed by name or by liquidity. Any other ERC-20 still works — pass its contract address instead of a symbol. - Being ON the list is not a promise either. A token whose `/v1/tokens` entry says `"tradeable": false` is refused by the liquidity venue for legal reasons, on BOTH sides of a swap, and both endpoints answer `TOKEN_NOT_TRADEABLE` before 0x is even called. Passing its contract address instead of its symbol does not help. Pick a different token, or use `source=uniswap` where the chain offers it; do not retry unchanged. - `ETH` and `WETH` are different tokens. Swapping one for the other is a legal request (wrap/unwrap). `sell` resolving to the same token as `buy` is `INVALID_REQUEST`. - Addresses may be checksummed, lowercase or mixed; they are compared lowercased. The zero address is rejected everywhere. ### /v1/quote only taker required the wallet that will sign and send. The calldata is built FOR that wallet, and `approval` / `issues.balance` are facts ABOUT that wallet. recipient optional where the bought token is delivered. Defaults to `taker`. Setting it sends the ENTIRE buy side to a different address — it is echoed back in `recipient` and called out in `explanation`. `taker` on `/v1/price` is ignored on purpose (the price answer is cached and shared, so it must not depend on any one wallet), and `/v1/price` returns no `issues` field at all. NEVER USE /v1/price AS AN ALLOWANCE CHECK. Measured 2026-09-17: when 0x is asked for a price with no `taker`, it does NOT leave allowance and balance empty — it substitutes a DEFAULT taker and reports that stranger's real on-chain numbers (`allowance.actual "0"`, `balance.actual "8077211012861035"`, identical on both recorded taker-less bodies and on a third independent probe, versus "906633330112741" on both bodies that did pass a real taker). This service drops that block rather than forwarding it. Allowance and balance facts come only from `/v1/quote`, with your `taker`. (Earlier drafts of this file claimed 0x "cannot report allowance or balance problems" without a taker. It can; the numbers are just someone else's.) ## Response: /v1/price { "chainId": 8453, "sellToken": { "address": "0x…", "symbol": "WETH", "decimals": 18 }, "buyToken": { "address": "0x…", "symbol": "USDC", "decimals": 6 }, "sellAmount": { "raw": "1000000000000000000", "formatted": "1" }, "buyAmount": { "raw": "2994210448", "formatted": "2994.210448" }, "minBuyAmount": { "raw": "2979239395", "formatted": "2979.239395" }, "price": "2994.210448", "fee": { "bps": 20, "token": "WETH", "amount": { "raw": "2000000000000000", "formatted": "0.002" } }, "gas": { "estimate": "288079", "gasPriceWei": "5040000", "estimatedCostNative": "0.00000145" }, "route": [ { "source": "Uniswap_V4", "proportionBps": 10000 } ], "path": [ { "from": "WETH", "to": "USDC", "source": "Uniswap_V4", "proportionBps": 10000 } ], "slippageBps": 50, "liquidityAvailable": true, "cached": false, "explanation": "Sell 1 WETH for about 2994.210448 USDC on Base via …" } - `raw` is authoritative, always a base-unit integer string. `formatted` is for reading aloud to a human. `formatted` is `null` (never a copy of `raw`) when the token's decimals could not be read. - `price` is buy-per-1-sell, computed here, and is NET of both the 20 bps AgentOS fee and 0x's own fee — `buyAmount` is already net of both. - `gas.estimatedCostNative` comes from 0x's `totalNetworkFee`, so it includes the L1 data cost. Do not recompute it as gas × gasPrice; both chains are L2s and that multiplication understates the real cost. - `route` lists first-hop fills only, folded per source. It describes how the order was split, not the full path. - `path` lists every hop in routing order, intermediate tokens included. Read it to see which pools a swap touches: ETH -> VIRTUAL -> CAP shows only the first leg's sources in `route` and all legs here. `from`/`to` are symbols, or a lowercase address when no symbol is known. Shares are per token pair and do not sum to 10000 across the list. - `explanation` is a plain-language summary in `lang`. Read it to the user. Response headers: `X-Cache: HIT|MISS`, `x-request-id`. A HIT is the same body with `"cached": true`. Cached for about 5 seconds; identical concurrent requests are NOT collapsed. ## Response: /v1/quote Everything `/v1/price` returns, plus: "recipient": "0xabcdef0123456789abcdef0123456789abcdef01", "approval": { "required": true, "token": "0x4200000000000000000000000000000000000006", "spender": "0x0000000000001ff3684f28c67538d4d072c22734", "currentAllowance": "0", "amountNeeded": "1000000000000000000", "transaction": { "to": "0x4200…0006", "data": "0x095ea7b3…", "value": "0" }, "explanation": "…" }, "transaction": { "to": "0x0000000000001ff3684f28c67538d4d072c22734", "data": "0x2213bc0b…", "value": "0", "gas": "288079", "gasPrice": "5040000" }, "expiresAt": "2026-09-17T12:34:56.000Z", "issues": { "balance": null, "simulationIncomplete": false } - `approval` is `null` when the existing allowance already covers this swap, and when selling the native coin. When present, send it first. It approves EXACTLY `amountNeeded` — never unlimited — so it must be re-sent for the next swap. It carries no gas field; let the wallet estimate. - `transaction.value` is wei of the native coin to attach. `"0"` for ERC-20 sells; the full sell amount when selling ETH. - `gas` / `gasPrice` are decimal strings. Convert to hex if your RPC wants hex (`288079` -> `0x4654f`, `5040000` -> `0x4ce780`). Never broadcast without a gas limit. - `expiresAt` is `now + 30s`, generated HERE. 0x publishes no expiry of any kind, so treat it as a deadline, not a guarantee: past it, re-quote. - `issues.balance` non-null means the taker cannot pay yet (`{token, actual, expected}`, base units). The response is still 200 and the calldata is still valid — it will simply revert until the wallet is funded. - `transaction` can be `null` in rare upstream cases. Check before signing. - `/v1/quote` is never cached (`Cache-Control: no-store`) and never returns `X-Cache`. ## No liquidity `liquidityAvailable: false` is HTTP **200**, not an error. `buyAmount`, `minBuyAmount`, `price`, `fee`, `approval` and `transaction` are all `null`, `route` and `path` are `[]`, and `explanation` says so. Do not retry in a loop; try a different pair, a smaller size, or come back later. Do not confuse this with `TOKEN_NOT_TRADEABLE`. `liquidityAvailable: false` means "no route right now" — retrying or resizing is reasonable. `400 TOKEN_NOT_TRADEABLE` means "this token can never be routed here" — retrying is pointless. ## Execution: which contract you approve and call Every /v1/price and /v1/quote body carries "execution": { "mode": "direct" | "contract", "source": "0x" | "uniswap" | "uniswap-native", "router": "0x…" | null } - `direct` — `transaction.to` and `approval.spender` are 0x's entry point, and the fee is inside 0x's calldata. Everything below under "Fees" describes this mode. - `contract` — `transaction.to` and `approval.spender` are the AgentOS Router (`execution.router`). The Router takes the fee on-chain, in the SELL token, exactly floor(sellAmount * bps / 10000), then runs the swap. The approval is for the full `sellAmount`. Selling ETH: `transaction.value` is the full `sellAmount`. ETH <-> WETH is free: it is always `direct`, a one-for-one WETH9 deposit/withdraw with `fee: null`, and never goes through the Router. The operator switches a chain to `contract`, and a single quote on such a chain may still come back `direct`. You do not choose and you must not assume: sign exactly the `approval.transaction` and `transaction` the response gives you. An allowance granted to one spender does not carry over to the other. ## Fees A 20 bps (0.2%) integrator fee is attached to every swap, charged in ONE of the two traded tokens, reported in `fee` and already deducted from `buyAmount`. You cannot choose which token, and there is no separate charge: if the swap is never broadcast, no fee is ever paid. Which side it lands on is decided per chain by a fixed preference order. The first entry that is one of {sell, buy} wins: base (8453) ETH (native) -> WETH -> USDC -> USDT -> DAI robinhood (4663) ETH (native) -> WETH -> USDG If neither traded token is on that list, the fee falls back to the SELL token. The fee CAN be taken in native ETH, and on this deployment native ETH is the first preference on both chains — so any swap with ETH on either side is charged in ETH. (This was gated off until 2026-09-17, when a live probe confirmed 0x accepts the native sentinel as the fee token: HTTP 200, integrator fee "20000000000000" on a sell of "10000000000000000" — exactly 20 bps, paid in ETH. The gate existed because if 0x had refused it, every native-side swap would have failed; it is now settled and switched on.) Worked examples: base: WETH -> USDC fee in WETH base: ETH -> USDC fee in ETH base: USDC -> ETH fee in ETH base: USDC -> DEGEN fee in USDC base: DEGEN -> BRETT fee in DEGEN (neither preferred -> sell token) robinhood: ETH -> USDG fee in ETH robinhood: USDG -> WETH fee in WETH Read `fee.bps` and `fee.token` back off the response rather than assuming: the operator can change the rate, the preference order has changed before, and the response always reports what was actually applied. `fee` is `null` when there is no liquidity, or when 0x reported no integrator fee at all. ## Errors Every failure, from every endpoint, is this one envelope: { "error": { "code": "UNKNOWN_TOKEN", "message": "human-readable, safe to show a user", "retryAfterSeconds": 60, // optional; see the note below "details": { "chain": "base" } // optional, code-specific } } code HTTP meaning / what to do INVALID_REQUEST 400 malformed params. `details.param` names the offending one. Fix and retry. UNKNOWN_TOKEN 400 symbol not in this chain's list. Use the contract address, or GET /v1/tokens. A real but blocked token is never this code. TOKEN_NOT_TRADEABLE 400 the token is real and its address is correct, but 0x refuses to route it for LEGAL reasons, as the sell side and as the buy side alike. Today: the 29 tokenised stocks on chain 4663, every one marked `"tradeable": false` by GET /v1/tokens, rejected here before 0x is called. Also raised when 0x itself answers BUY_TOKEN_NOT_AUTHORIZED_FOR_TRADE or SELL_TOKEN_NOT_AUTHORIZED_FOR_TRADE for a token this list has not caught up with. DO NOT RETRY and do not swap the symbol for its contract address — same refusal. If GET /v1/chains lists `uniswap` for the chain, repeat with `source=uniswap` (the message says so when it applies). Otherwise name a different token, or tell the user this venue will not trade that asset. `details` carries `chain`, `param` ("sell"/"buy"), `symbol` and `address` when caught locally, and `reason` when it came back from 0x. UNSUPPORTED_CHAIN 400 `details.supported` lists the keys that work. SLIPPAGE_OUT_OF_RANGE 400 `details.min`/`details.max` (1..500). DECIMALS_UNKNOWN 400 an unlisted token's decimals could not be read, so a human `sellAmount` cannot be scaled. Resend with `sellAmountRaw`. RATE_LIMITED 429 our limiter. Wait `retryAfterSeconds`. UPSTREAM_REJECTED 400 0x refused the swap (`details.reason`) for a reason that is NOT a legal refusal of the token — those are TOKEN_NOT_TRADEABLE. Usually the pair, the size or the taker. TAKER_NOT_AUTHORIZED_FOR_TRADE is about the WALLET, not the token. UPSTREAM_RATE_LIMITED 503 0x is limiting this service — the shared upstream budget is 15 requests/second for every caller combined (measured, see "Rate limits"). `retryAfterSeconds` is derived from 0x's own `Retry-After` header, which is delta-seconds and has been observed as 1; it falls back to 2 and is capped at 300. Honour it; do not hammer. UPSTREAM_ERROR 502 0x is down or answered nonsense. Retry later. UPSTREAM_GEO_BLOCKED 451 limit orders only: KyberSwap refuses calls from the country the request came from. Retrying from the same place will not help. Swaps are unaffected. SOURCE_UNAVAILABLE 503 you asked for `source=uniswap` and it cannot serve this request: not switched on for the chain, or the Router it runs through is paused or unreadable (`details.reason`: `not_enabled`, `router_unavailable`, `wallet_unreadable`). Nothing is wrong with the request. Retry later, or drop `source`. MISCONFIGURED 503 this service's own deployment is broken. Nothing the caller changes will help. INTERNAL_ERROR 500 a bug here. Report the `x-request-id`. A 404 is the same envelope with `INVALID_REQUEST`. `retryAfterSeconds` appears on RATE_LIMITED and UPSTREAM_RATE_LIMITED, and also on DECIMALS_UNKNOWN when the decimals RPC was the thing rate-limiting us — so do not treat it as a 429/503-only field. Whenever it is present it is also sent as the `Retry-After` response header; read either one. `x-request-id` is on every response — quote it in bug reports. This service does not retry, queue or back off for you. ## Rate limits /v1/price 60 requests / minute per IP /v1/quote 120 requests / minute per IP /v1/quote 30 requests / minute per (taker, IP) pair /v1/limit-orders* 60 requests / minute per IP, all six routes together Over the limit is `429 RATE_LIMITED` with `retryAfterSeconds: 60`, and `error.details.scope` says which limiter fired (`"IP"` or `"taker address"`). Limits are per data centre and approximate. On `/v1/quote` both limiters apply and either one trips the request. Behind those, there is ONE upstream budget shared by every caller of this service: 15 requests per second, in total. That figure is measured, not quoted from a vendor page — every 0x response recorded on 2026-09-17 carried `RateLimit-Limit: 15` and `X-RateLimit-Limit-Second: 15`, and a deliberately provoked 429 carried `RateLimit-Remaining: 0` alongside the same limit and `Retry-After: 1`. (Earlier planning notes here said "~5 RPS", quoted from docs. That was wrong by 3x; 15 is the observed number.) One `/v1/price` cache miss or one `/v1/quote` spends one upstream request. `/v1/quote` is never cached, so it always spends one. A `TOKEN_NOT_TRADEABLE` rejection spends none — that is why the check is done locally. DO NOT POLL. The `/v1/price` cache does not collapse concurrent requests, so N identical in-flight calls are N calls to 0x against that 15/second budget, and a loop will trip `RATE_LIMITED` and then `UPSTREAM_RATE_LIMITED` for everybody. Ask once, reuse the answer for its few seconds of life, and call `/v1/quote` only when you actually intend to sign. ## Robinhood Chain (4663): read this before trading there - There is NO real USDC, USDT or DAI on chain 4663. Every on-chain token by those names is an impostor, including an 18-decimal "Circle USD" sitting in a pool that advertises eight-figure TVL. `sell=USDC&chain=robinhood` returns `UNKNOWN_TOKEN` deliberately. Do not "fix" it by passing an address you found elsewhere. - The stablecoin there is USDG (`0x5fc5360d0400a0fd4f2af552add042d716f1d168`), and it has 6 decimals while every other token on that chain has 18. Do not assume uniform decimals; use each token's own `decimals` field. THE STOCK TOKENS ON 4663 CANNOT BE TRADED THROUGH THE DEFAULT SOURCE (0x). Everything in this block is about 0x. Where `GET /v1/chains` lists `uniswap` for chain 4663, the same tokens trade with `source=uniswap` — see "The Uniswap source". Where it does not, what follows is the whole story. 29 of the 34 tokens listed on chain 4663 are Robinhood tokenised stocks and index wrappers — AAPL MSFT NVDA META GOOGL AMZN TSLA MSTR COIN PLTR AMD INTC MU COST LLY HIMS RBLX SNAP GME AMC DJT CRCL GLXY SPCX SPY QQQ GLD USO SGOV — and 0x refuses every one of them. `/v1/price` and `/v1/quote` answer `400 TOKEN_NOT_TRADEABLE` for any pair naming one, and never call 0x at all. GET /v1/price?chain=robinhood&sell=USDG&buy=TSLA&sellAmount=100 -> 400 { "error": { "code": "TOKEN_NOT_TRADEABLE", "message": "TSLA (0x322f0929c4625ed5bad873c95208d54e1c003b2d) is a real token on Robinhood Chain and that address is correct, but the upstream liquidity API refuses to trade it for legal reasons …", "details": { "chain": "robinhood", "param": "buy", "symbol": "TSLA", "address": "0x322f0929c4625ed5bad873c95208d54e1c003b2d" } } } THIS IS A LEGAL RESTRICTION IMPOSED BY 0x. It is not a bug in this service, not a gap in the token list, and not a liquidity problem. So: - Do not retry. Waiting does not help; a smaller size does not help; market hours do not help. - Do not pass the contract address instead of the symbol. It reaches the identical refusal. The row is kept in `/v1/tokens` with `"tradeable": false` precisely so you are not told "unknown token" and sent hunting for an address. - Do not report it to a user as a failed trade. The venue will not trade that asset, full stop. Say that, and do not substitute a different asset yourself. Measured on 2026-09-17, during US market hours: all 29 probed against USDG in BOTH directions, 58 requests, 58 refusals, zero exceptions. `USDG -> stock` is HTTP 422 `BUY_TOKEN_NOT_AUTHORIZED_FOR_TRADE`; `stock -> USDG` is HTTP 422 `SELL_TOKEN_NOT_AUTHORIZED_FOR_TRADE`; both say "… is not authorized for trade due to legal restrictions". The block is on the token contract, not on the pair or the direction — TSLA also fails against WETH, against native ETH and against another stock token. WHAT DOES WORK ON 4663: ETH, WETH and USDG, which trade normally (plus PONS and AGENTOS, which are thin). A sound pair on that chain is ETH/USDG or WETH/USDG. `GET /v1/tokens?chain=robinhood` marks all five `"tradeable": true`. ## The Uniswap source (`source=uniswap`) `/v1/price` and `/v1/quote` are answered by 0x unless you say otherwise. Add `source=uniswap` and the same two endpoints are answered by the Uniswap Trading API instead. Same parameters, same response shape, same flow. GET /v1/chains -> [{ "key": "robinhood", …, "sources": ["0x", "uniswap"] }] CHECK `sources` FIRST. A chain offers Uniswap only when `uniswap` is in that array. Asking for it anywhere else is `503 SOURCE_UNAVAILABLE`. What is different about a Uniswap answer: - It is always executed through the AgentOS Router: `execution.mode` is `"contract"`, `approval.spender` and `transaction.to` are the Router, and the fee is taken on-chain from the sell token. `execution.source` is `"uniswap"` for an ERC-20 sell and `"uniswap-native"` for a native (ETH) sell. - There is no fallback. If the Router is paused or the chain cannot be read, the answer is `503 SOURCE_UNAVAILABLE`, not a quote from somewhere else. Retry later, or repeat the request without `source`. - It is not bound by 0x's refusals. THE STOCK TOKENS ON 4663 CAN BE TRADED THIS WAY: `"tradeable": false` on `/v1/tokens` describes 0x only. GET /v1/quote?chain=robinhood&sell=USDG&buy=NVDA&sellAmount=100 &taker=0xYourWallet&source=uniswap - `ETH` <-> `WETH` is refused with `INVALID_REQUEST` (`details.param` is `"source"`): that pair is a free wrap, not a swap. Send it without `source`. - A token that takes a tax on plain transfers is not detected up front on this source; such a swap reverts on-chain instead of settling short. Simulate before sending, as always. - No route is still a 200 with `liquidityAvailable: false`. The two sources are never mixed and never compared for you. To pick the better price, ask both and compare `buyAmount.raw`. ## Limit orders (KyberSwap) 0x has no limit orders, so these go to KyberSwap's Limit Order API. Same rule as swaps: this service never signs and stores nothing. Orders live in KyberSwap's off-chain book; a taker fills yours on-chain once your price is worth filling. Creating and gasless-cancelling cost no gas. No fee is charged by this service on limit orders. KyberSwap takes its own fee (0.01%–1% depending on the token) out of the buy side when an order fills. ERC-20 on both sides: ETH is rejected with `INVALID_REQUEST` and `details.use` = the WETH address. Wrap first if you want to sell ETH. Step 1 — POST /v1/limit-orders/sign-message with JSON: { "chain": "base", "sell": "WETH", "buy": "USDC", "sellAmount": "1", "buyAmount": "4000", "maker": "0xYourWallet", "expiresInSeconds": 604800 } (optional; default 7 days) A limit order fixes BOTH amounts: sell exactly `sellAmount`, receive at least `buyAmount`. The limit price is buy/sell (here 4000 USDC per WETH). Use `sellAmountRaw` / `buyAmountRaw` for base units. `receiver` is optional (defaults to the maker). Answer: { "sell": {...}, "buy": {...}, "price": "4000", "expiresAt": "...", "typedData": { domain, types, primaryType: "Order", message }, "order": { chainId, makerAsset, takerAsset, maker, receiver, allowedSenders, makingAmount, takingAmount, expiredAt, salt }, "approval": { token, spender, minimumAmountRaw, note }, ... } The typed data is checked against your request before it is returned; if KyberSwap's answer does not match, you get `502 UPSTREAM_ERROR` and nothing to sign. Step 2 — sign `typedData` as the maker with eth_signTypedData_v4. Step 3 — POST /v1/limit-orders with `order` UNCHANGED plus `signature`: { ...order, "signature": "0x…" } -> 201 { "orderId": 123, "status": "active" } Step 4 — approve `approval.spender` for the sell token, from the maker. Without it the order sits in the book and never fills. KyberSwap checks the allowance against the SUM of all your active orders selling that token. Check orders: GET /v1/limit-orders?chain=base&maker=0x…[&status=active|open| partially_filled|filled|cancelled|expired] -> `orders[]` with `orderId`, `status`, `sell`/`buy` (amounts and `filled` amounts), `price`, `filledPercent`, `expiresAt`. Cancel, free but not instant (can still fill for ~90 seconds): POST /v1/limit-orders/cancel-sign `{chain, maker, orderIds:[123]}` -> sign `typedData` -> POST /v1/limit-orders/cancel `{chain, maker, orderIds, signature}`. Cancel, immediate but costs gas: POST /v1/limit-orders/hard-cancel `{chain, maker, orderIds:[123]}` -> `transaction {from, to, data, value}` to send from the maker. OMITTING orderIds cancels EVERY open order the maker has on that chain. KyberSwap blocks some countries. That shows up as `451 UPSTREAM_GEO_BLOCKED`. If KyberSwap's bot protection ever challenges this service, that shows up as `502 UPSTREAM_ERROR` with `details.reason: "UPSTREAM_BOT_CHALLENGE"`. Your request is not the cause; do not retry in a loop, and report the `x-request-id`. ## Other endpoints `GET /health` -> `{"ok":true,"version":"0.1.0","chains":[8453,4663],"configured":true}`. `configured:false` means the deployment is missing secrets and every `/v1` route will answer `503 MISCONFIGURED`. `GET /v1/chains` -> array of `{chainId, key, name, native, wrapped, sources}` — `wrapped` is the wrapped-native contract, useful when you want WETH rather than ETH; `sources` is what `source` may be on that chain, `["0x"]` or `["0x", "uniswap"]`. `GET /v1/tokens?chain=base[&lang=en|vi]` -> `{chainId, chain, count, note, tokens:[{address, symbol, name, decimals, kind, tradeable}]}`. For example: { "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "symbol": "USDC", "name": "USD Coin", "decimals": 6, "kind": "stable", "tradeable": true } `kind` is `native` | `wrapped` | `stable` | `other`. `note` repeats both rules: that any unlisted token is reachable by address, and that a `"tradeable": false` token is refused for legal reasons on either side. `tradeable` is ALWAYS present and ALWAYS a boolean on this endpoint, on both chains — you never have to tell "absent" from "false" when filtering. tradeable: true no known restriction. Trade it. (Not a liquidity promise: `liquidityAvailable: false` is still possible.) tradeable: false the venue refuses this token for legal reasons, as the sell side AND as the buy side. /v1/price and /v1/quote answer TOKEN_NOT_TRADEABLE without calling 0x. Pick a different token; the contract address is not a way round. Internally the field is optional on the token record and ABSENT MEANS TRADEABLE — only an explicit `false` blocks, because a token nobody has ever quoted cannot be assumed restricted. The endpoint normalises that to a real boolean, so the absent case never reaches you. The same rule means an unlisted token you reach by contract address is treated as tradeable until 0x says otherwise; if 0x then refuses it, you get the same `TOKEN_NOT_TRADEABLE` code, just from upstream. All 52 Base tokens are `tradeable: true`. On chain 4663, 5 of 34 are: ETH, WETH, USDG, PONS, AGENTOS. ## Worked example: sell 1 WETH for USDC on Base Request: GET /v1/quote?chain=base&sell=WETH&buy=USDC&sellAmount=1 &taker=0xabcdef0123456789abcdef0123456789abcdef01 Response (200; illustrative numbers, but every field, type and null rule is exactly what a real Base quote returns — use the values from YOUR response): { "chainId": 8453, "sellToken": { "address": "0x4200000000000000000000000000000000000006", "symbol": "WETH", "decimals": 18 }, "buyToken": { "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "symbol": "USDC", "decimals": 6 }, "sellAmount": { "raw": "1000000000000000000", "formatted": "1" }, "buyAmount": { "raw": "2994108231", "formatted": "2994.108231" }, "minBuyAmount": { "raw": "2979137689", "formatted": "2979.137689" }, "price": "2994.108231", "fee": { "bps": 20, "token": "WETH", "amount": { "raw": "2000000000000000", "formatted": "0.002" } }, "gas": { "estimate": "288079", "gasPriceWei": "5040000", "estimatedCostNative": "0.00000145" }, "route": [ { "source": "Uniswap_V4", "proportionBps": 6000 }, { "source": "Aerodrome_V1", "proportionBps": 4000 } ], "path": [ { "from": "WETH", "to": "USDC", "source": "Uniswap_V4", "proportionBps": 6000 }, { "from": "WETH", "to": "USDC", "source": "Aerodrome_V1", "proportionBps": 4000 } ], "slippageBps": 50, "liquidityAvailable": true, "cached": false, "recipient": "0xabcdef0123456789abcdef0123456789abcdef01", "approval": { "required": true, "token": "0x4200000000000000000000000000000000000006", "spender": "0x0000000000001ff3684f28c67538d4d072c22734", "currentAllowance": "0", "amountNeeded": "1000000000000000000", "transaction": { "to": "0x4200000000000000000000000000000000000006", "data": "0x095ea7b30000000000000000000000000000000000001ff3684f28c675 38d4d072c227340000000000000000000000000000000000000000000000 000de0b6b3a7640000", "value": "0" }, "explanation": "Wallet 0xabcd… has not approved the spender contract 0x0000000000001ff3684f28c67538d4d072c22734 to spend WETH. Send this approve transaction BEFORE the swap transaction — the swap reverts otherwise." }, "transaction": { "to": "0x0000000000001ff3684f28c67538d4d072c22734", "data": "0x2213bc0b000000000000000000000000…", "value": "0", "gas": "288079", "gasPrice": "5040000" }, "expiresAt": "2026-09-17T09:41:12.000Z", "issues": { "balance": null, "simulationIncomplete": false }, "explanation": "Sell 1 WETH for about 2994.108231 USDC on Base via Uniswap_V4 + Aerodrome_V1. AgentOS fee 0.002 WETH (0.2%); minimum received 2979.137689 USDC at 0.5% slippage; this quote expires in 30 seconds — once it lapses, request /v1/quote again rather than reusing this calldata. The included approve transaction must be sent first, before the swap transaction." } (The `data` fields are shown wrapped/truncated for readability. Use the exact strings from your own response, unmodified — one altered byte is a different trade.) Then, with your own signer: # 1. allowance first, because approval != null eth_sendTransaction { from: 0xabcdef0123456789abcdef0123456789abcdef01, to: approval.transaction.to, # 0x4200…0006 (the WETH contract) data: approval.transaction.data, # approve(spender, 1e18) value: 0x0 } # wait for the receipt, status == 0x1 # 2. the swap eth_sendTransaction { from: 0xabcdef0123456789abcdef0123456789abcdef01, to: transaction.to, # 0x0000000000001ff3684f28c67538d4d072c22734 data: transaction.data, value: 0x0, # hex of transaction.value gas: 0x4654f, # hex of transaction.gas (288079) gasPrice: 0x4ce780 # hex of transaction.gasPrice (5040000) } You receive at least `minBuyAmount.raw` (2979137689 base units = 2979.137689 USDC) or the transaction reverts. That floor is what `slippageBps` buys you. Selling the native coin instead (`sell=ETH`): no approval step, `transaction.value` is the sell amount in wei rather than `"0"`, and `fee.token` comes back as `"ETH"` rather than `"WETH"` — native ETH is the first fee preference on both chains. ## Checklist before you sign anything [ ] both tokens are "tradeable": true on GET /v1/tokens (chain 4663 blocks 29 of its 34 listed tokens outright) [ ] the response is 200 and liquidityAvailable is true [ ] transaction is not null [ ] approval was sent and mined first, if approval != null [ ] now < expiresAt (else re-quote; do not reuse calldata) [ ] transaction.to, .data, .value are copied byte-for-byte from THIS response [ ] gas and gasPrice are set [ ] recipient is the address you intended (it defaults to taker) [ ] minBuyAmount is an outcome you accept