AgentOS markAgentOS

DEX API

View .mdllms.txt

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 GET requests.
  • 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

Chainchain valueChain ID
Basebase8453
Robinhood Chainrobinhood4663

GET /v1/chains is the live list, including which liquidity sources each chain offers.

Endpoints

EndpointWhat it returns
GET /v1/chainsSupported chains and their liquidity sources
GET /v1/tokensThe token symbol list for one chain
GET /v1/priceAn indicative price. No wallet needed; cached for about 5 seconds
GET /v1/quoteAn executable quote with unsigned calldata. Requires taker
POST /v1/limit-orders/sign-messageA limit order for the maker to sign (EIP-712)
POST /v1/limit-ordersSubmits the signed limit order
GET /v1/limit-ordersA maker's limit orders on one chain
POST /v1/limit-orders/cancel-sign, /cancelGasless cancel: typed data to sign, then submit
POST /v1/limit-orders/hard-cancelUnsigned calldata for an on-chain cancel
GET /healthLiveness

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:

  1. If approval is not null, sign and send approval.transaction first and wait for it to be mined. It approves exactly the amount this swap needs.
  2. Sign and send transaction (to, data, value, gas, gasPrice).
  3. If expiresAt has 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:

ParameterRequiredMeaning
chainyesbase, robinhood, or the chain ID
sell, buyyesA symbol from /v1/tokens, a token contract address, or ETH
sellAmount or sellAmountRawexactly oneHuman units (0.25) or base units. The API always sells an exact input
slippageBpsno1 to 500. Default 50 (0.5%)
sourceno0x (default) or uniswap, where the chain offers it
taker/v1/quote onlyThe wallet that will sign and send
recipientno, /v1/quote onlyWhere 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

RouteLimit
/v1/price60 requests per minute per IP
/v1/quote120 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.