> For the complete documentation index, see [llms.txt](https://docs.beamswap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.beamswap.io/api-reference.md).

# Build with Beamswap

REST API endpoint groups for vaults, swaps, limit orders and automations, MCP source and the OpenAPI schema.

Use the integration that fits your application:

* [Hosted MCP](https://docs.beamswap.io/mcp-access) for supported AI clients and browser-approved requests.
* [Standalone local MCP source](https://github.com/BeamSwap/beamswap-mcp) for stdio clients and operator-controlled local automation.
* [REST API reference](https://app.beamswap.io/docs) for direct integration.
* [OpenAPI JSON](https://api.beamswap.io/v1/openapi.json) for exact endpoint schemas.

API base URL: `https://api.beamswap.io`. Hosted MCP URL: `https://api.beamswap.io/mcp`.

## First HTTP request

```sh
curl -i "https://api.beamswap.io/v1/quote?sell=ETH&buy=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&amount=10000000000000000"
```

This asks for a quote for 0.01 ETH. Without payment or eligible quota, expect **402 Payment Required**. That response is a price challenge, not an outage. Use an x402 client for the signed retry; the full reference contains examples.

Token amounts in API requests are decimal **strings in the smallest token unit**. Never convert them to floating-point numbers. Website CSV amounts are human-readable and are converted separately using the token's decimals.

## Endpoint groups

The [OpenAPI JSON](https://api.beamswap.io/v1/openapi.json) is the exact source for request and response schemas. This is the map. Except where noted, these groups are **free** and rate limited per IP. Wallet-scoped routes need a session bearer (see Sessions below).

| Group        | Routes                                                                                                                                                                                                                             | Auth                                         |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Agent Vaults | `/v1/vaults`, `/v1/vaults/{address}`, `/v1/vaults/agent-key`, `/v1/vaults/{address}/orders`, `/v1/vaults/{address}/orders/prepare`, `/v1/vaults/{address}/cancel`, `/v1/vaults/{address}/pause`, `/v1/vaults/{address}/mcp-tokens` | Session, vault capability or agent signature |
| Swaps        | `/v1/swap/quote`, `/v1/swap/route`, `/v1/swap/record`                                                                                                                                                                              | Quote: none. Route and record: session       |
| Limit orders | `/v1/orders/prepare`, `/v1/orders`, `/v1/orders/{uid}`, `/v1/orders/cancel`                                                                                                                                                        | Session, except reading one order by UID     |
| Automations  | `/v1/automations/preview`, `/v1/automations`, `/v1/automations/{id}`, pause, resume, cancel, and per-run prepare and submit                                                                                                        | Session, except preview                      |
| Cross-chain  | `/v1/crosschain/chains`, `/v1/crosschain/quote`, `/v1/crosschain/status`, `/v1/crosschain/transfers`                                                                                                                               | Transfers: session                           |
| Account      | `/v1/account/spending`, `/v1/account/spending/pause`, `/v1/account/receipts`, `/v1/distributions`                                                                                                                                  | Session                                      |

The earlier paid routes (token facts, portfolio, quote, execute route, watch, distribution creation and proofs) are unchanged.

### Agent Vaults

Vault routes let an app or agent read a vault and trade from it. Every rule the vault enforces on chain also applies here. A call that breaks a vault rule is refused, usually with **422**, and a body such as `{ error, code, rule }`, for example "This trade is 180 USD; your per-trade limit is 100 USD."

* `POST /v1/vaults/agent-key`: the owner asks for a Beamswap-hosted agent key for a new vault. Returns the agent address to register when the vault is created. The key stays encrypted on the server and can trade only inside the vault rules.
* `GET /v1/vaults` and `GET /v1/vaults/{address}`: the owner's vaults, and one vault with balances in USD, rules, today's spend, open orders and recent orders with their reasons. The vault's private capability can read its own vault.
* `POST /v1/vaults/{address}/orders`: trade from the vault. Send the private capability as `Authorization: Bearer <capability>` with `sell`, `buy`, `sellAmount` (base units), either `limitPrice` (buy tokens per one sell token) or `maxSlippageBps`, `validFor` in seconds and an optional `reason` of up to 200 characters. Beamswap signs with the hosted agent key, checks the call against the chain, relays it and posts the order to CoW.
* `POST /v1/vaults/{address}/orders/prepare`: for a local agent that holds its own key. Returns the order and the intent to sign. Submit the signed result to the orders route.
* `POST /v1/vaults/{address}/cancel` and `POST /v1/vaults/{address}/pause`: cancel an order or pause the vault. Only the owner can resume, from a wallet.
* `GET`, `POST` and `DELETE /v1/vaults/{address}/mcp-tokens`: list, create and revoke private MCP links. A new link is returned once. See [MCP access](https://docs.beamswap.io/mcp-access).

There is no route to withdraw or change rules. Those are owner transactions on Base. Amounts are decimal strings in base units.

### Swaps

`POST /v1/swap/quote` returns the price, Beamswap fee and aggregator for a swap on Base through the own route, without calldata. `POST /v1/swap/route` returns signable calldata for the session wallet, limited to 20 a minute. `POST /v1/swap/record` records a swap the wallet sent so it appears in transfers and Activity. Cross-chain swaps use `/v1/crosschain/quote`, which returns LI.FI routes.

### Limit orders

`POST /v1/orders/prepare` builds the CoW order for the wallet to sign, including the Beamswap partner fee. `POST /v1/orders` submits the signed order, `GET /v1/orders` lists the session wallet's orders and `POST /v1/orders/cancel` cancels. `GET /v1/orders/{uid}` reads one order by its CoW UID with no session.

### Automations

`POST /v1/automations/preview` validates a reserve refill (`refill`), a trade split into parts (`twap`) or a recurring buy (`recurring`) and describes it, with maximum exposure and warnings, without creating anything. `POST /v1/automations` creates one for the session wallet, at most 20 active. Without a vault, each due run must be prepared and signed by the wallet. Add a top-level `vault` field with the address of a vault you own that uses a Beamswap-hosted agent, and each run is placed by the vault agent with no signature, inside the vault rules and paying into the vault.

## Sessions

A canonical wallet signature creates a 24-hour bearer session. It lets the API apply that wallet's quota and tier discounts. A session is not permission to move its tokens. The local MCP's `session_create` helper retains its bearer in process memory.

## Monitoring

Supply a public HTTPS webhook receiver. Verify the HMAC signature over the raw request body and deduplicate deliveries. Watch IDs permit lookup and cancellation, so keep them private. Delivery can be retried; it is not exactly once.

For schemas, errors, fee calculations and endpoint-specific limits, use the [maintained API reference](https://app.beamswap.io/docs) and the [OpenAPI JSON](https://api.beamswap.io/v1/openapi.json).