DEX API
The AgentOS DEX API is a keyless HTTP API that lets an agent swap tokens. You ask for a price or a quote and get JSON back; a quote carries unsigned transaction calldata that your own wallet signs and sends.
- Base URL:
https://agg.useagentos.dev - No API key, no auth header. Swap endpoints are plain
GETrequests. - Non-custodial. The service holds no private key. It never signs and never broadcasts; a swap happens only when your signer sends the transaction.
Chains
| Chain | chain value | Chain ID |
|---|---|---|
| Base | base | 8453 |
| Robinhood Chain | robinhood | 4663 |
GET /v1/chains is the live list, including which liquidity sources each chain offers.
Endpoints
| Endpoint | What it returns |
|---|---|
GET /v1/chains | Supported chains and their liquidity sources |
GET /v1/tokens | The token symbol list for one chain |
GET /v1/price | An indicative price. No wallet needed; cached for about 5 seconds |
GET /v1/quote | An executable quote with unsigned calldata. Requires taker |
POST /v1/limit-orders/sign-message | A limit order for the maker to sign (EIP-712) |
POST /v1/limit-orders | Submits the signed limit order |
GET /v1/limit-orders | A maker's limit orders on one chain |
POST /v1/limit-orders/cancel-sign, /cancel | Gasless cancel: typed data to sign, then submit |
POST /v1/limit-orders/hard-cancel | Unsigned calldata for an on-chain cancel |
GET /health | Liveness |
The full reference is served by the API itself: /llms.txt for agents and /openapi.json for tooling.
Swap in three calls
# 1. Find symbols and check both sides are tradeable
curl "https://agg.useagentos.dev/v1/tokens?chain=base"
# 2. (Optional) check the rate
curl "https://agg.useagentos.dev/v1/price?chain=base&sell=WETH&buy=USDC&sellAmount=1"
# 3. Get calldata built for your wallet
curl "https://agg.useagentos.dev/v1/quote?chain=base&sell=WETH&buy=USDC&sellAmount=1&taker=0xYourWallet"
Then, from the wallet you passed as taker:
- If
approvalis notnull, sign and sendapproval.transactionfirst and wait for it to be mined. It approves exactly the amount this swap needs. - Sign and send
transaction(to,data,value,gas,gasPrice). - If
expiresAthas passed (about 30 seconds), discard the quote and ask again. Never sign stale calldata.
Selling native ETH needs no approval: approval is null and transaction.value carries the ETH.
Request parameters
Shared by /v1/price and /v1/quote:
| Parameter | Required | Meaning |
|---|---|---|
chain | yes | base, robinhood, or the chain ID |
sell, buy | yes | A symbol from /v1/tokens, a token contract address, or ETH |
sellAmount or sellAmountRaw | exactly one | Human units (0.25) or base units. The API always sells an exact input |
slippageBps | no | 1 to 500. Default 50 (0.5%) |
source | no | 0x (default) or uniswap, where the chain offers it |
taker | /v1/quote only | The wallet that will sign and send |
recipient | no, /v1/quote only | Where the bought token is delivered. Defaults to taker |
Every amount in a response comes as raw (base units, authoritative) and formatted (for display). When there is no route, the answer is still HTTP 200 with liquidityAvailable: false.
Fees
A 20 bps (0.2%) fee applies to swaps that execute. It is reported in the fee field and already deducted from buyAmount. A quote you never broadcast costs nothing. Wrapping ETH to WETH, or back, is free.
Each response also carries an execution block that says which contract you approve and call. On the contract path that is the AgentOS Router, which takes the fee on-chain. See DEX Contracts.
Limit orders
Limit orders are placed in an off-chain order book and filled on-chain once your price is reached. Both sides must be ERC-20 tokens, so wrap ETH first. Creating an order and cancelling it gaslessly cost no gas, and the API charges no fee on limit orders.
Rate limits
| Route | Limit |
|---|---|
/v1/price | 60 requests per minute per IP |
/v1/quote | 120 per minute per IP, and 30 per minute per taker |
/v1/limit-orders (all routes) | 60 per minute per IP |
Do not poll. Ask for a price once, reuse it for its few seconds of life, and request a quote only when you intend to sign.
Errors
Every failure uses one envelope:
{
"error": {
"code": "UNKNOWN_TOKEN",
"message": "human-readable, safe to show a user",
"retryAfterSeconds": 60,
"details": { "chain": "base" }
}
}
retryAfterSeconds and details are optional. Common codes are INVALID_REQUEST, UNKNOWN_TOKEN, TOKEN_NOT_TRADEABLE, UNSUPPORTED_CHAIN and RATE_LIMITED; the complete list is in /llms.txt.