AI Agents on RAVN: MCP Server, x402 Payments, and the Swap API

Quick answer

RAVN lets AI agents quote and execute cross-chain swaps, including native Bitcoin, three ways: the MCP server (no signup, built for Claude and Cursor), x402 payments (pay-per-call in USDC, no signup, no API key), or the REST API (free, optional API key). All three sit on the same Integrator API underneath, so the quote and execution logic, the fields, and the 0% swap fee are identical regardless of which door an agent walks through.

MCP server (free, no signup)

RAVN runs a remote MCP server at https://app.ravn.exchange/api/mcp, discoverable by any MCP-compliant client over Streamable HTTP. It exposes five tools:

• 1ravn_quote: best-execution quote across 16 chains, same-chain or cross-chain, returns a quoteToken
• 2ravn_execute: turns a quoteToken into an execution payload — TRANSACTION, SIGNATURE, or DEPOSIT
• 3ravn_status: polls swap status by quoteToken and reference
• 4ravn_health: liveness check across every venue RAVN routes through
• 5ravn_btc_prepare_send: converts a DEPOSIT result into an unsigned Bitcoin PSBT for agent-assisted signing

These tools call the same free /v1/* endpoints as the REST API. No signup is required; an API key is optional and only raises rate limits.

{"mcpServers": {"ravn": {"url": "https://app.ravn.exchange/api/mcp"}}}

Drop that into claude_desktop_config.json or a Cursor .cursor/mcp.json and the tools are discoverable immediately. Sanity-checking the endpoint with curl or a browser first? A plain GET returns 405 Method Not Allowed — expected, not broken, since Streamable HTTP only speaks POST.

x402 payments (pay-per-call, no key)

For agents that would rather pay per call than hold a stored API key, RAVN exposes x402 endpoints priced in USDC on Base or Solana. Only quote and execute are metered this way; status and health have no /x402/ counterpart and stay free REST/MCP calls even after a paid execute.

• $0.001POST /api/v1/x402/quote — same contract as the free quote endpoint
• $0.01POST /api/v1/x402/execute — same contract as the free execute endpoint

The flow repurposes the HTTP 402 status code: call with no payment attached, get a 402 back with a payment-required header describing accepted options (the response body itself is an empty {}, since payment terms live in the header, not the body), sign a payment authorization (an EIP-3009 USDC authorization on Base, or a Solana USDC transfer) and retry with the payment header attached, then RAVN verifies and settles the payment and returns the normal response. Request and response bodies match the free endpoints exactly, including the quoteToken, which works interchangeably between the free and x402 execute calls. This access fee is separate from RAVN's swap fee, which is still 0% on every route.

Why pay when free REST/MCP access already exists? Because x402 buys you things a free key can't: nothing to provision, rotate, or leak; spend capped per call instead of per key; the on-chain payment itself as an independently verifiable audit trail; and discoverability by other agents crawling x402-compatible catalogs (Coinbase's x402 Bazaar, x402scan.com), which the free doors aren't part of.

REST API (existing integrators)

Agents built as part of an existing bot, backend, or wallet that already manages API keys can call the same Integrator API directly: POST /quote, POST /execute, GET /status. See the cross-chain swap API guide and for integrators for the full endpoint map.

Receiving real Bitcoin

Native BTC is not an afterthought for agents. When a route resolves to a DEPOSIT execution type on a Bitcoin leg, ravn_btc_prepare_send turns the deposit address and amount into an unsigned PSBT, ready for the agent to sign and broadcast, so it never has to write its own coin-selection logic. RAVN never sees or holds a private key at any point in that flow. Agents send and receive the canonical asset on the Bitcoin network, not a wrapped representation. See native BTC swaps without wrapping.

Who signs the transaction?

A TRANSACTION or SIGNATURE result still needs a signature RAVN never produces. For an autonomous agent that's a design decision made once, not per swap: hold a local key in the agent's own environment and sign directly; hand the payload to a human (or a wallet app) for review before anything broadcasts; or call out to a TEE or custody service (a CDP-managed wallet, Turnkey, Privy) that never exposes the key to the agent process itself. DEPOSIT results, the common case for Bitcoin-source swaps, sidestep this entirely: no typed data, just a plain transfer, which is what ravn_btc_prepare_send builds for you. See the full signing patterns breakdown in the docs.

Which one should I use?

• Already inside Claude or Cursor: use the MCP server. Zero setup beyond adding the server URL.
• Fully autonomous agent, no stored secrets: use x402. Pay per call, no key to rotate or leak.
• Existing integration with keys and infra: use the REST API directly.

All three answer to the same underlying quote/execute/status logic, so switching later is a transport change, not a rebuild.

FAQ