# DEX API
> Source: https://useagentos.dev/docs/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 `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

| 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`](https://agg.useagentos.dev/llms.txt) for agents and [`/openapi.json`](https://agg.useagentos.dev/openapi.json) for tooling.

## Swap in three calls

```bash
# 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`:

| 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](https://useagentos.dev/docs/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:

```json
{
  "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`](https://agg.useagentos.dev/llms.txt).
