{"openapi":"3.1.0","info":{"title":"AgentOS Aggregator","version":"0.1.0","summary":"Non-custodial token swap prices and unsigned calldata for AI agents.","description":"A Cloudflare Worker fronting 0x Swap API v2 on Base (8453) and Robinhood Chain (4663).\n\nThis service holds no private key: it never signs and never broadcasts. `/v1/quote` returns unsigned transaction calldata that the caller's own wallet must sign and send.\n\nNo authentication of any kind is required. Every endpoint is a GET. A 20 bps integrator fee is attached to each swap and is already deducted from the reported `buyAmount`. The fee is charged in one of the two traded tokens, and since 2026-09-17 that may be native ETH — which token it lands in depends on the pair, so read `fee.token` off the response.\n\n**Chain 4663 carries a legal restriction.** The 29 tokenised-stock tokens on Robinhood Chain (AAPL, TSLA, NVDA, SPY, …) cannot be traded in either direction: the upstream venue refuses them for legal reasons, `/v1/tokens` marks each one `\"tradeable\": false`, and `/v1/price` and `/v1/quote` answer `400 TOKEN_NOT_TRADEABLE` without calling 0x. This is not a bug and not a liquidity problem, so it must not be retried. ETH, WETH and USDG on 4663 trade normally.\n\nThere is one upstream budget shared by every caller of this service: 15 requests per second, measured against live 0x responses on 2026-09-17. Exceeding it surfaces as `503 UPSTREAM_RATE_LIMITED`.\n\nThe same API is described in plain text, with a worked example, at `/llms.txt`."},"servers":[{"url":"/","description":"The origin serving this document."}],"tags":[{"name":"meta","description":"Liveness and machine-readable docs."},{"name":"reference","description":"Static chain and token data."},{"name":"swap","description":"Prices and unsigned swap calldata."},{"name":"limit-orders","description":"Gasless limit orders on KyberSwap's order book. Non-custodial: the maker signs EIP-712 messages; this service never signs and stores nothing. No fee is charged by this service; KyberSwap deducts its own fee from the buy side on fill."}],"paths":{"/":{"get":{"tags":["meta"],"operationId":"getIndex","summary":"Discovery index.","description":"A signpost for an agent handed nothing but the origin. Points at `/llms.txt` (the whole API as prose) and `/openapi.json` (this document), and lists the live endpoints. Answers even when the deployment is missing its secrets.","responses":{"200":{"description":"Where to read about this API.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["name","description","documentation","endpoints","startHere"],"properties":{"name":{"type":"string","example":"agentos-aggregator"},"description":{"type":"string"},"documentation":{"type":"object","required":["llms","openapi"],"properties":{"llms":{"type":"string","example":"/llms.txt"},"openapi":{"type":"string","example":"/openapi.json"}}},"endpoints":{"type":"array","items":{"type":"string"}},"startHere":{"type":"string","example":"/llms.txt"}}}}}}}}},"/health":{"get":{"tags":["meta"],"operationId":"getHealth","summary":"Liveness.","description":"Answers even when the Worker is misconfigured — `configured: false` means the deployment is missing its secrets and every `/v1` route will return 503 MISCONFIGURED.","responses":{"200":{"description":"The service is running.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/llms.txt":{"get":{"tags":["meta"],"operationId":"getLlmsTxt","summary":"The whole API as plain text for an autonomous agent.","description":"Self-contained: an agent that reads only this file can complete a swap.","responses":{"200":{"description":"The agent guide.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/openapi.json":{"get":{"tags":["meta"],"operationId":"getOpenapi","summary":"This document.","responses":{"200":{"description":"An OpenAPI 3.1 document.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/chains":{"get":{"tags":["reference"],"operationId":"listChains","summary":"Supported chains.","description":"Driven by the operator's `SUPPORTED_CHAINS` config, so a disabled chain disappears from this list.","responses":{"200":{"description":"The chains this deployment will quote on.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Chain"}},"example":[{"chainId":8453,"key":"base","name":"Base","native":"ETH","wrapped":"0x4200000000000000000000000000000000000006","sources":["0x","uniswap"]},{"chainId":4663,"key":"robinhood","name":"Robinhood Chain","native":"ETH","wrapped":"0x0bd7d308f8e1639fab988df18a8011f41eacad73","sources":["0x","uniswap"]}]}}},"503":{"$ref":"#/components/responses/Misconfigured"}}}},"/v1/tokens":{"get":{"tags":["reference"],"operationId":"listTokens","summary":"The symbol list for one chain.","description":"Symbols resolve ONLY against this list. Any other ERC-20 is still reachable — pass its contract address as `sell` or `buy` instead of a symbol.\n\nBeing on the list is not itself permission to trade: read the `tradeable` flag on every entry. `false` means the upstream venue refuses that token for legal reasons on both sides of a swap, and `/v1/price` and `/v1/quote` will answer `400 TOKEN_NOT_TRADEABLE` for it. All 52 Base tokens are `true`; on chain 4663 only 5 of 34 are (ETH, WETH, USDG, PONS, AGENTOS).","parameters":[{"$ref":"#/components/parameters/Chain"},{"$ref":"#/components/parameters/Lang"}],"responses":{"200":{"description":"The bundled token list.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"503":{"$ref":"#/components/responses/Misconfigured"}}}},"/v1/price":{"get":{"tags":["swap"],"operationId":"getPrice","summary":"Indicative price. No wallet required.","description":"Reference price for a pair and size. Cached for a few seconds and shared between callers, so it deliberately ignores `taker` and returns no calldata. Rate limited to 60 requests per minute per IP, on top of a 15-request-per-second upstream budget shared by every caller.\n\nIf either side resolves to a token marked `\"tradeable\": false` on `/v1/tokens`, the request is rejected with `400 TOKEN_NOT_TRADEABLE` and 0x is never called.\n\nThis body carries no `issues` field and is not an allowance check. Asked without a `taker`, the upstream still returns allowance and balance — but for a default wallet it substitutes, not the caller's (measured 2026-09-17). Use `/v1/quote` with your own `taker` for anything wallet-specific.","parameters":[{"$ref":"#/components/parameters/Chain"},{"$ref":"#/components/parameters/Sell"},{"$ref":"#/components/parameters/Buy"},{"$ref":"#/components/parameters/SellAmount"},{"$ref":"#/components/parameters/SellAmountRaw"},{"$ref":"#/components/parameters/SlippageBps"},{"$ref":"#/components/parameters/Lang"},{"$ref":"#/components/parameters/Source"}],"responses":{"200":{"description":"A price. `liquidityAvailable: false` is also a 200, with every amount nulled.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"X-Cache":{"description":"`HIT` when served from the edge cache; the body then carries `cached: true`.","schema":{"type":"string","enum":["HIT","MISS"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/quote":{"get":{"tags":["swap"],"operationId":"getQuote","summary":"Executable quote with unsigned calldata.","description":"Returns everything `/v1/price` does, plus the transaction to sign, an `approval` transaction when the allowance is short, and a synthetic 30-second `expiresAt`.\n\nNever cached (`Cache-Control: no-store`), so every call spends one request of the 15-per-second upstream budget shared by all callers. Rate limited to 120 requests per minute per IP and 30 per minute per (taker, IP) pair.\n\nIf either side resolves to a token marked `\"tradeable\": false` on `/v1/tokens`, the request is rejected with `400 TOKEN_NOT_TRADEABLE` and 0x is never called.\n\nSend `approval.transaction` first and wait for it to mine; then send `transaction`. Re-quote once `expiresAt` has passed rather than reusing calldata.","parameters":[{"$ref":"#/components/parameters/Chain"},{"$ref":"#/components/parameters/Sell"},{"$ref":"#/components/parameters/Buy"},{"$ref":"#/components/parameters/SellAmount"},{"$ref":"#/components/parameters/SellAmountRaw"},{"$ref":"#/components/parameters/SlippageBps"},{"$ref":"#/components/parameters/Lang"},{"$ref":"#/components/parameters/Source"},{"$ref":"#/components/parameters/Taker"},{"$ref":"#/components/parameters/Recipient"}],"responses":{"200":{"description":"A signable quote. `liquidityAvailable: false` is also a 200, with `transaction` and `approval` null.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"description":"Always `no-store`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/limit-orders":{"get":{"tags":["limit-orders"],"operationId":"listLimitOrders","summary":"A maker's limit orders on one chain.","parameters":[{"$ref":"#/components/parameters/Chain"},{"name":"maker","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","open","partially_filled","filled","cancelled","expired"],"default":"active"}}],"responses":{"200":{"description":"Orders, newest data from KyberSwap.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["chainId","maker","status","orders"],"properties":{"chainId":{"type":"integer"},"maker":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"status":{"type":"string"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/LimitOrder"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"451":{"$ref":"#/components/responses/GeoBlocked"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"tags":["limit-orders"],"operationId":"createLimitOrder","summary":"Submit a signed limit order.","description":"Body is the `order` object from `/v1/limit-orders/sign-message`, unchanged, plus `signature`. The maker must also approve `approval.spender` for the sell token or the order cannot fill.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/LimitOrderFields"},{"type":"object","required":["signature"],"properties":{"signature":{"type":"string","pattern":"^0x([0-9a-fA-F]{2}){65,}$"}}}]}}}},"responses":{"201":{"description":"Order accepted into KyberSwap's book.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["chainId","orderId","status","next"],"properties":{"chainId":{"type":"integer"},"orderId":{"type":["integer","null"]},"status":{"type":"string"},"next":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"451":{"$ref":"#/components/responses/GeoBlocked"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/limit-orders/sign-message":{"post":{"tags":["limit-orders"],"operationId":"limitOrderSignMessage","summary":"Build a limit order for the maker to sign.","description":"A limit order fixes both sides: sell exactly `sellAmount`, receive at least `buyAmount`. ETH is not accepted — use WETH. The typed data is checked against the request before it is returned.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chain","sell","buy","maker"],"properties":{"chain":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Chain key (base, robinhood) or id (8453, 4663)."},"sell":{"type":"string"},"buy":{"type":"string"},"sellAmount":{"type":"string"},"sellAmountRaw":{"type":"string","pattern":"^\\d+$"},"buyAmount":{"type":"string"},"buyAmountRaw":{"type":"string","pattern":"^\\d+$"},"maker":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"receiver":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"expiresInSeconds":{"type":"integer","minimum":60,"maximum":31536000,"default":604800}}}}}},"responses":{"200":{"description":"Typed data to sign and the order body to submit.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitOrderSignMessage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"451":{"$ref":"#/components/responses/GeoBlocked"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/limit-orders/cancel-sign":{"post":{"tags":["limit-orders"],"operationId":"limitOrderCancelSign","summary":"Typed data for a gasless cancel.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chain","maker","orderIds"],"properties":{"chain":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Chain key (base, robinhood) or id (8453, 4663)."},"maker":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"orderIds":{"type":"array","items":{"type":"integer"},"minItems":1,"maxItems":50}}}}}},"responses":{"200":{"description":"Typed data to sign.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["chainId","maker","orderIds","typedData","next"],"properties":{"chainId":{"type":"integer"},"maker":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"orderIds":{"type":"array","items":{"type":"integer"}},"typedData":{"type":"object"},"next":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"451":{"$ref":"#/components/responses/GeoBlocked"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/limit-orders/cancel":{"post":{"tags":["limit-orders"],"operationId":"limitOrderCancel","summary":"Submit a signed gasless cancel.","description":"Not instant: the order can still fill for up to ~90 seconds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chain","maker","orderIds","signature"],"properties":{"chain":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Chain key (base, robinhood) or id (8453, 4663)."},"maker":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"orderIds":{"type":"array","items":{"type":"integer"},"minItems":1,"maxItems":50},"signature":{"type":"string","pattern":"^0x([0-9a-fA-F]{2}){65,}$"}}}}}},"responses":{"200":{"description":"Cancellation submitted.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["chainId","orderIds","status","note"],"properties":{"chainId":{"type":"integer"},"orderIds":{"type":"array","items":{"type":"integer"}},"status":{"type":"string"},"note":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"451":{"$ref":"#/components/responses/GeoBlocked"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/limit-orders/hard-cancel":{"post":{"tags":["limit-orders"],"operationId":"limitOrderHardCancel","summary":"Unsigned calldata for an on-chain cancel.","description":"With `orderIds`, cancels those orders. Without, increases the maker's nonce, which cancels EVERY open order of the maker on the chain. Costs gas; immediate once mined.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chain","maker"],"properties":{"chain":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Chain key (base, robinhood) or id (8453, 4663)."},"maker":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"orderIds":{"type":"array","items":{"type":"integer"},"minItems":1,"maxItems":50}}}}}},"responses":{"200":{"description":"Transaction for the maker to send.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["chainId","scope","orderIds","transaction","note"],"properties":{"chainId":{"type":"integer"},"scope":{"type":"string","enum":["all_orders","listed_orders"]},"orderIds":{"type":["array","null"],"items":{"type":"integer"}},"transaction":{"type":"object","required":["from","to","data","value"],"properties":{"from":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"to":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"data":{"type":"string"},"value":{"type":"string"}}},"note":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"451":{"$ref":"#/components/responses/GeoBlocked"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"headers":{"RequestId":{"description":"Correlation id for this request. Quote it in bug reports.","schema":{"type":"string","format":"uuid"}},"RetryAfter":{"description":"Seconds to wait. Mirrors `error.retryAfterSeconds`.","schema":{"type":"integer","minimum":1}}},"parameters":{"Chain":{"name":"chain","in":"query","required":true,"description":"Chain key or chain id.","schema":{"type":"string","examples":["base","8453","robinhood","4663"]}},"Sell":{"name":"sell","in":"query","required":true,"description":"Token to sell: a symbol from `/v1/tokens`, a contract address, or `ETH` for the native coin. A token `/v1/tokens` marks `\"tradeable\": false` is rejected with `400 TOKEN_NOT_TRADEABLE` whichever side it is on.","schema":{"type":"string","maxLength":64,"examples":["WETH","ETH","0x4200000000000000000000000000000000000006"]}},"Buy":{"name":"buy","in":"query","required":true,"description":"Token to buy. Same forms as `sell`, and must resolve to a different token. Same `\"tradeable\": false` rule as `sell` — the refusal is on the token, not on the direction.","schema":{"type":"string","maxLength":64,"examples":["USDC","USDG"]}},"SellAmount":{"name":"sellAmount","in":"query","required":false,"description":"Amount to sell in human units. Exactly one of `sellAmount` or `sellAmountRaw` must be present. Requires the sell token's decimals to be known.","schema":{"type":"string","examples":["1","0.25"]}},"SellAmountRaw":{"name":"sellAmountRaw","in":"query","required":false,"description":"Amount to sell in base units. Exactly one of `sellAmount` or `sellAmountRaw` must be present.","schema":{"type":"string","pattern":"^[0-9]+$","examples":["1000000000000000000"]}},"SlippageBps":{"name":"slippageBps","in":"query","required":false,"description":"Slippage tolerance in basis points, 1..500. Defaults to 50 (0.5%). Out of range is reported, never clamped.","schema":{"type":"string","pattern":"^[0-9]+$","examples":["50","125"]}},"Lang":{"name":"lang","in":"query","required":false,"description":"Language of the human-readable `explanation` / `note` fields.","schema":{"type":"string","enum":["en","vi"],"default":"en"}},"Source":{"name":"source","in":"query","required":false,"description":"Which liquidity API answers. `0x` is the default. `uniswap` asks the Uniswap Trading API instead and is always executed through the AgentOS Router; it is offered only on chains whose `GET /v1/chains` entry lists it in `sources`, and elsewhere answers `503 SOURCE_UNAVAILABLE`. A token marked `\"tradeable\": false` is refused by 0x only and can be requested with `uniswap`.","schema":{"type":"string","enum":["0x","uniswap"],"default":"0x"}},"Taker":{"name":"taker","in":"query","required":true,"description":"Wallet that will sign and send the swap. Required on `/v1/quote`: the calldata is built for that wallet, and `approval` and `issues.balance` are facts about that wallet. The zero address is rejected.\n\nNote (measured 2026-09-17, correcting an earlier claim in these docs): a taker-less upstream price does NOT come back with allowance and balance empty — 0x substitutes a default taker and reports that stranger's real on-chain figures. `/v1/price` therefore publishes no `issues` field at all and must never be used as an allowance check; `/v1/quote` with your own `taker` is the only source of those facts.","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"Recipient":{"name":"recipient","in":"query","required":false,"description":"Where the bought token is delivered. Defaults to `taker`. Setting it sends the entire buy side elsewhere. The zero address is rejected.","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}},"responses":{"BadRequest":{"description":"The request was rejected before or by the upstream. `INVALID_REQUEST`, `UNKNOWN_TOKEN`, `TOKEN_NOT_TRADEABLE`, `UNSUPPORTED_CHAIN`, `SLIPPAGE_OUT_OF_RANGE`, `DECIMALS_UNKNOWN` or `UPSTREAM_REJECTED`.\n\n`DECIMALS_UNKNOWN` may carry `retryAfterSeconds` and the matching `Retry-After` header when the decimals RPC was rate limiting this service.\n\n`TOKEN_NOT_TRADEABLE` is the one code here that no change to the request can fix: the token is real and its address is correct, but the upstream venue refuses to route it for legal reasons, as the sell side and as the buy side alike. It is raised locally — without calling 0x — for every token `/v1/tokens` marks `\"tradeable\": false` (today, the 29 tokenised stocks on chain 4663), and raised from upstream when 0x answers HTTP 422 `BUY_TOKEN_NOT_AUTHORIZED_FOR_TRADE` or `SELL_TOKEN_NOT_AUTHORIZED_FOR_TRADE` for a token this service's list has not caught up with. Do not retry it and do not resend the contract address in place of the symbol; name a different token.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unknownToken":{"summary":"A symbol that is not on the chain's list.","value":{"error":{"code":"UNKNOWN_TOKEN","message":"Unknown token \"NOTATOKEN\" on Base. Symbols resolve only against this chain's bundled list — pass the contract address (0x + 40 hex) instead.","details":{"chain":"base","input":"NOTATOKEN"}}}},"tokenNotTradeable":{"summary":"A real chain-4663 stock token the venue refuses for legal reasons.","value":{"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 — it answers NOT_AUTHORIZED_FOR_TRADE for this token as the sell side and as the buy side alike, so no price and no calldata exist for it here. Passing the contract address instead of the symbol reaches the same refusal, and retrying will not change it. GET /v1/tokens?chain=robinhood marks every token in this state with \"tradeable\": false; pick one marked true.","details":{"chain":"robinhood","param":"buy","symbol":"TSLA","address":"0x322f0929c4625ed5bad873c95208d54e1c003b2d"}}}}}}}},"RateLimited":{"description":"This service's own rate limiter refused the request.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests from this IP. Wait 60 seconds and call again; this service does not queue or retry for you.","retryAfterSeconds":60,"details":{"scope":"IP"}}}}}},"UpstreamError":{"description":"`UPSTREAM_ERROR` — the 0x API is down or answered something unusable.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"`UPSTREAM_RATE_LIMITED`, `SOURCE_UNAVAILABLE` or `MISCONFIGURED`.\n\n`UPSTREAM_RATE_LIMITED` means 0x is limiting this service. The shared upstream budget is 15 requests per second for every caller combined — measured on 2026-09-17, where every live 0x response carried `RateLimit-Limit: 15` and `X-RateLimit-Limit-Second: 15`. Nothing about the caller's request is wrong; `retryAfterSeconds` is derived from 0x's own `Retry-After` header (delta-seconds; observed value `1`), falling back to 2 and capped at 300, and is mirrored in this response's `Retry-After` header. Honour it and back off; this service does not retry for you.\n\n`MISCONFIGURED` means this deployment is broken and nothing the caller changes will help.\n\n`SOURCE_UNAVAILABLE` means the request asked for `source=uniswap` and that source cannot serve it: it is not switched on for the chain (`details.reason` `not_enabled`), or the Router it is executed through is paused or cannot be read (`router_unavailable`, `wallet_unreadable`). There is no fallback, because that source has no fee-paying path outside the Router. The request itself is fine: retry later, or repeat it without `source`.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Misconfigured":{"description":"`MISCONFIGURED` — the deployment is missing `ZEROX_API_KEY` or `FEE_RECIPIENT`, or a config var is invalid.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"GeoBlocked":{"description":"`UPSTREAM_GEO_BLOCKED`: KyberSwap refuses requests from the caller's country. Swaps are unaffected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"The single error envelope used by every endpoint, including 404s.","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"string","enum":["INVALID_REQUEST","UNKNOWN_TOKEN","TOKEN_NOT_TRADEABLE","UNSUPPORTED_CHAIN","SLIPPAGE_OUT_OF_RANGE","DECIMALS_UNKNOWN","RATE_LIMITED","UPSTREAM_RATE_LIMITED","UPSTREAM_ERROR","UPSTREAM_REJECTED","MISCONFIGURED","INTERNAL_ERROR","UPSTREAM_GEO_BLOCKED","SOURCE_UNAVAILABLE"]},"message":{"type":"string","description":"Human readable and safe to show a user. Never carries a raw upstream body."},"retryAfterSeconds":{"type":"integer","minimum":1,"description":"Seconds to wait before retrying. Present on `RATE_LIMITED` and `UPSTREAM_RATE_LIMITED`, and also on `DECIMALS_UNKNOWN` when the decimals RPC was the thing rate-limiting this service — so do not treat it as a 429/503-only field. Whenever it is present it is mirrored in the `Retry-After` response header."},"details":{"type":"object","additionalProperties":true,"description":"Code-specific. E.g. `param` for INVALID_REQUEST, `supported` for UNSUPPORTED_CHAIN, `min`/`max` for SLIPPAGE_OUT_OF_RANGE, `reason` for UPSTREAM_REJECTED, `scope` for RATE_LIMITED, and `chain`/`param`/`symbol`/`address` for a locally-caught TOKEN_NOT_TRADEABLE (`reason` instead when that code came back from the upstream)."}}}}},"Health":{"type":"object","required":["ok","version","chains","configured"],"additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"version":{"type":"string","examples":["0.1.0"]},"chains":{"type":"array","items":{"type":"integer"},"examples":[[8453,4663]]},"configured":{"type":"boolean","description":"False when the required secrets are absent; every `/v1` route then returns 503."}}},"Chain":{"type":"object","required":["chainId","key","name","native","wrapped","sources"],"additionalProperties":false,"properties":{"chainId":{"type":"integer","examples":[8453]},"key":{"type":"string","description":"URL-facing alias.","examples":["base"]},"name":{"type":"string","examples":["Base"]},"native":{"type":"string","description":"Symbol of the native coin.","examples":["ETH"]},"wrapped":{"type":"string","pattern":"^0x[0-9a-f]{40}$","description":"Lowercase address of the wrapped native token."},"sources":{"type":"array","items":{"type":"string","enum":["0x","uniswap"]},"description":"What `source` may be on `/v1/price` and `/v1/quote` for this chain. `0x` is always present and is the default.","examples":[["0x"],["0x","uniswap"]]}}},"TokenList":{"type":"object","required":["chainId","chain","count","note","tokens"],"additionalProperties":false,"properties":{"chainId":{"type":"integer"},"chain":{"type":"string"},"count":{"type":"integer"},"note":{"type":"string","description":"States both halves of the rule: that unlisted tokens are reachable by contract address, and that a `tradeable: false` token is refused by the venue for legal reasons on either side. Part of the contract, not decoration."},"tokens":{"type":"array","items":{"$ref":"#/components/schemas/ListedToken"}}}},"ListedToken":{"type":"object","required":["address","symbol","name","decimals","kind","tradeable"],"additionalProperties":false,"properties":{"address":{"type":"string","pattern":"^0x[0-9a-f]{40}$","description":"Lowercase. The native coin uses 0x's sentinel 0xeee…eee."},"symbol":{"type":"string"},"name":{"type":"string"},"decimals":{"type":"integer"},"kind":{"type":"string","enum":["native","wrapped","stable","other"]},"tradeable":{"type":"boolean","description":"Always present and always a boolean on this endpoint, so a caller never has to tell 'absent' from 'false'.\n\n`true`: no known restriction — but not a liquidity promise, since `liquidityAvailable: false` is still possible.\n\n`false`: the upstream venue refuses this token for legal reasons, on the sell side and the buy side alike. `/v1/price` and `/v1/quote` answer `400 TOKEN_NOT_TRADEABLE` for it without calling 0x, and passing the contract address in place of the symbol reaches the same refusal. Today the only `false` entries are the 29 tokenised-stock tokens on chain 4663, measured against live 0x on 2026-09-17.\n\nOn the internal token record the field is optional and absence means tradeable — only an explicit `false` blocks, because a token that has never been quoted cannot be assumed restricted. This endpoint normalises that to a real boolean.","examples":[true]}}},"AmountPair":{"type":"object","description":"`raw` is authoritative base units. `formatted` is for reading aloud, and is null — never a copy of `raw` — when the token's decimals could not be read.","required":["raw","formatted"],"additionalProperties":false,"properties":{"raw":{"type":"string","pattern":"^[0-9]+$","examples":["1000000000000000000"]},"formatted":{"type":["string","null"],"examples":["1"]}}},"MappedToken":{"type":"object","required":["address","symbol","decimals"],"additionalProperties":false,"properties":{"address":{"type":"string","pattern":"^0x[0-9a-f]{40}$"},"symbol":{"type":"string"},"decimals":{"type":["integer","null"],"description":"Null when `decimals()` could not be read — never a placeholder 0."}}},"Fee":{"type":["object","null"],"description":"The AgentOS integrator fee, already deducted from `buyAmount`. Charged in one of the two traded tokens; the caller cannot choose which.\n\nWhich one depends on the pair. Each chain has an ordered preference list and the first entry that is one of {sell, buy} wins, otherwise it falls back to the sell token. Base: ETH (native) -> WETH -> USDC -> USDT -> DAI. Robinhood: ETH (native) -> WETH -> USDG.\n\nThe fee may be taken in native ETH: a live probe on 2026-09-17 confirmed 0x accepts the native sentinel as `swapFeeToken` (HTTP 200, integrator fee 20000000000000 on a sell of 10000000000000000 — exactly 20 bps in ETH), so the deployment now lists native ETH first on both chains. Before that date it was gated off and a native sell was charged in the buy token instead. Read `fee.token` off the response rather than recomputing the order.","required":["bps","token","amount"],"additionalProperties":false,"properties":{"bps":{"type":"integer","examples":[20]},"token":{"type":"string","description":"Symbol of the token the fee is taken in — an address only when the token is unlisted.","examples":["WETH","ETH"]},"amount":{"$ref":"#/components/schemas/AmountPair"}}},"Gas":{"type":"object","required":["estimate","gasPriceWei","estimatedCostNative"],"additionalProperties":false,"properties":{"estimate":{"type":["string","null"],"description":"Decimal gas limit.","examples":["288079"]},"gasPriceWei":{"type":["string","null"],"examples":["5040000"]},"estimatedCostNative":{"type":["string","null"],"description":"From 0x's `totalNetworkFee`, so it already includes the L2 chain's L1 data cost. Do not recompute as gas x gasPrice.","examples":["0.00000145"]}}},"RouteLeg":{"type":"object","required":["source","proportionBps"],"additionalProperties":false,"properties":{"source":{"type":"string","examples":["Uniswap_V4"]},"proportionBps":{"type":"integer","examples":[6000]}}},"PathHop":{"type":"object","required":["from","to","source","proportionBps"],"additionalProperties":false,"properties":{"from":{"type":"string","description":"Symbol of the token this hop spends, or its lowercase address when no symbol is known. A native sell starts from the wrapped token.","examples":["WETH"]},"to":{"type":"string","description":"Symbol of the token this hop receives, or its lowercase address when no symbol is known.","examples":["USDC"]},"source":{"type":"string","examples":["Uniswap_V2"]},"proportionBps":{"type":"integer","description":"Share of this token pair's flow that goes through this source.","examples":[10000]}}},"Execution":{"type":"object","description":"Which contract the swap `transaction` calls, and so which contract the wallet approves. `contract`: AgentOSRouter, which takes the fee on-chain in the sell token and then runs the source's calldata. `direct`: 0x's own entry point, with the fee inside 0x's calldata. A chain uses `contract` once it is switched on; any single request can still come back `direct` (Router paused, RPC unavailable, a token that taxes transfers), so read this field on every quote instead of assuming.","required":["mode","source","router"],"properties":{"mode":{"type":"string","enum":["direct","contract"]},"source":{"type":"string","description":"The liquidity source the swap runs through, as the Router's source registry names it. `0x` unless the request asked for `source=uniswap`; then `uniswap` for an ERC-20 sell and `uniswap-native` for a native sell, always with `mode` `contract`. ETH<->WETH is a fee-free direct WETH9 call and never goes through the Router.","examples":["0x","uniswap"],"enum":["0x","uniswap","uniswap-native"]},"router":{"type":["string","null"],"description":"The AgentOSRouter address when `mode` is `contract`; null on the direct path."}}},"Price":{"type":"object","required":["chainId","sellToken","buyToken","sellAmount","buyAmount","minBuyAmount","price","fee","gas","route","path","slippageBps","liquidityAvailable","cached","execution","explanation"],"description":"The `/v1/price` body. `additionalProperties` is left open because `Quote` extends this schema with `allOf`; a `/v1/price` response carries exactly the listed fields and no others.","properties":{"chainId":{"type":"integer"},"sellToken":{"$ref":"#/components/schemas/MappedToken"},"buyToken":{"$ref":"#/components/schemas/MappedToken"},"sellAmount":{"$ref":"#/components/schemas/AmountPair"},"buyAmount":{"oneOf":[{"$ref":"#/components/schemas/AmountPair"},{"type":"null"}],"description":"Null when no liquidity. Already net of the AgentOS fee and 0x's own fee."},"minBuyAmount":{"oneOf":[{"$ref":"#/components/schemas/AmountPair"},{"type":"null"}],"description":"The floor enforced on-chain by `slippageBps`; below it the swap reverts."},"price":{"type":["string","null"],"description":"Buy per 1 sell, computed by this service, net of both fees. Null when either side's decimals are unknown.","examples":["2994.210448"]},"fee":{"$ref":"#/components/schemas/Fee"},"gas":{"$ref":"#/components/schemas/Gas"},"route":{"type":"array","items":{"$ref":"#/components/schemas/RouteLeg"},"description":"First-hop fills only, folded per source — how the order was split, not the whole path. For every pool the swap touches, read `path`."},"path":{"type":"array","items":{"$ref":"#/components/schemas/PathHop"},"description":"Every hop of the swap in routing order, intermediate tokens included. Shares are per token pair, so they do NOT sum to 10000 across the list. Empty when `liquidityAvailable` is false."},"slippageBps":{"type":"integer","examples":[50]},"liquidityAvailable":{"type":"boolean","description":"False is still HTTP 200, with every amount nulled and `route` empty."},"cached":{"type":"boolean","description":"True when served from the edge cache."},"execution":{"$ref":"#/components/schemas/Execution"},"explanation":{"type":"string","description":"Plain-language summary in `lang`, safe to read to a user."}}},"Approval":{"type":"object","description":"Present only when the taker's allowance is short. Send this transaction and wait for it to mine BEFORE the swap. It approves exactly `amountNeeded` — never unlimited — so it recurs on the next swap. It carries no gas field; let the wallet estimate.","required":["required","token","spender","currentAllowance","amountNeeded","transaction","explanation"],"additionalProperties":false,"properties":{"required":{"type":"boolean","const":true},"token":{"type":"string","pattern":"^0x[0-9a-f]{40}$","description":"The sell token's contract."},"spender":{"type":"string","description":"From 0x's `issues.allowance.spender`; never hard-coded here."},"currentAllowance":{"type":"string"},"amountNeeded":{"type":"string"},"transaction":{"type":"object","required":["to","data","value"],"additionalProperties":false,"properties":{"to":{"type":"string"},"data":{"type":"string","description":"`approve(spender, amountNeeded)` calldata."},"value":{"type":"string","const":"0"}}},"explanation":{"type":"string"}}},"Quote":{"allOf":[{"$ref":"#/components/schemas/Price"},{"type":"object","required":["recipient","approval","transaction","expiresAt","issues"],"properties":{"recipient":{"type":["string","null"],"description":"Who actually receives the buy token: the `recipient` param when given, otherwise the taker."},"approval":{"oneOf":[{"$ref":"#/components/schemas/Approval"},{"type":"null"}],"description":"Null when the allowance already suffices, and when selling the native coin."},"transaction":{"oneOf":[{"type":"object","required":["to","data","value","gas","gasPrice"],"additionalProperties":false,"properties":{"to":{"type":"string"},"data":{"type":"string","description":"Sign and send byte-for-byte; do not edit."},"value":{"type":"string","description":"Wei of the native coin to attach. `0` for ERC-20 sells; the sell amount when selling ETH."},"gas":{"type":["string","null"],"description":"Decimal gas limit. Never broadcast without one."},"gasPrice":{"type":["string","null"]}}},{"type":"null"}],"description":"Null when there is no liquidity, or when the upstream omitted it. Check before signing."},"expiresAt":{"type":"string","format":"date-time","description":"Synthetic: issue time + 30s. 0x publishes no expiry field of any kind, so this is a deadline this service chose, not an upstream guarantee. Past it, re-quote instead of reusing the calldata."},"issues":{"type":"object","required":["balance","simulationIncomplete"],"additionalProperties":false,"properties":{"balance":{"type":["object","null"],"required":["token","actual","expected"],"additionalProperties":false,"description":"Non-null means the taker cannot pay yet. The quote is still a 200 and the calldata is still valid; it will revert until the wallet is funded.","properties":{"token":{"type":"string"},"actual":{"type":"string"},"expected":{"type":"string"}}},"simulationIncomplete":{"type":"boolean"}}}}}]},"LimitOrderFields":{"type":"object","description":"The exact order body. Returned as `order` by sign-message; POST it back unchanged plus `signature`.","required":["chainId","makerAsset","takerAsset","maker","receiver","makingAmount","takingAmount","expiredAt","salt"],"properties":{"chainId":{"type":"string"},"makerAsset":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"takerAsset":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"maker":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"receiver":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"allowedSenders":{"type":"array","items":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"maxItems":1},"makingAmount":{"type":"string","pattern":"^\\d+$"},"takingAmount":{"type":"string","pattern":"^\\d+$"},"expiredAt":{"type":"integer"},"salt":{"type":"string"}}},"LimitOrderSide":{"type":"object","required":["symbol","address","decimals","amount","amountRaw"],"properties":{"symbol":{"type":"string"},"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"decimals":{"type":["integer","null"]},"amount":{"type":["string","null"]},"amountRaw":{"type":"string","pattern":"^\\d+$"}}},"LimitOrderSignMessage":{"type":"object","required":["chainId","sell","buy","price","expiresAt","typedData","order","approval","next","fee"],"properties":{"chainId":{"type":"integer"},"sell":{"$ref":"#/components/schemas/LimitOrderSide"},"buy":{"$ref":"#/components/schemas/LimitOrderSide"},"price":{"type":["string","null"],"description":"Buy per 1 sell: the limit price."},"expiresAt":{"type":"string","format":"date-time"},"typedData":{"type":"object","description":"EIP-712 typed data (domain, types, primaryType, message). Sign with eth_signTypedData_v4 as the maker."},"order":{"$ref":"#/components/schemas/LimitOrderFields"},"approval":{"type":"object","required":["token","spender","minimumAmountRaw","note"],"properties":{"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"spender":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"minimumAmountRaw":{"type":"string","pattern":"^\\d+$"},"note":{"type":"string"}}},"next":{"type":"string"},"fee":{"type":"string"}}},"LimitOrder":{"type":"object","required":["orderId","status","sell","buy","price","filledPercent","createdAt","expiresAt","orderHash"],"properties":{"orderId":{"type":["integer","null"]},"status":{"type":["string","null"]},"sell":{"type":"object","properties":{"symbol":{"type":["string","null"]},"address":{"type":["string","null"]},"decimals":{"type":["integer","null"]},"amount":{"type":["string","null"]},"amountRaw":{"type":["string","null"]},"filled":{"type":"object","properties":{"amount":{"type":["string","null"]},"amountRaw":{"type":["string","null"]}}}}},"buy":{"type":"object","properties":{"symbol":{"type":["string","null"]},"address":{"type":["string","null"]},"decimals":{"type":["integer","null"]},"amount":{"type":["string","null"]},"amountRaw":{"type":["string","null"]},"filled":{"type":"object","properties":{"amount":{"type":["string","null"]},"amountRaw":{"type":["string","null"]}}}}},"price":{"type":["string","null"]},"filledPercent":{"type":["number","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"orderHash":{"type":["string","null"]}}}}}}