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 for supported AI clients and browser-approved requests.

• Standalone local MCP source for stdio clients and operator-controlled local automation.

• REST API reference for direct integration.

• OpenAPI JSON for exact endpoint schemas.

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

First HTTP request

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 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.

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 and the OpenAPI JSON.