> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravn.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Claude, Cursor, or any MCP client to RAVN's quote/execute/status loop, free, no API key required.

RAVN runs a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
Integrator API as native tools. Point any MCP-speaking client at it, and your agent can
discover and call RAVN without you writing any HTTP glue code.

**Endpoint:** `https://app.ravn.exchange/api/mcp`
**Transport:** Streamable HTTP
**Auth:** None required. Every tool works anonymously; pass your own API key as the optional
`apiKey` argument on any tool for a higher rate limit (see [Authentication](/authentication)).
**Cost:** Free. These tools call the same free `/v1/*` endpoints as the REST API, not the
paid [x402 endpoints](/ai-agents/x402-payments).

<Tip>
  Sanity-checking the endpoint with `curl` or a browser? A plain `GET` returns `405 Method Not
    Allowed` — that's expected, not broken. Streamable HTTP MCP servers only speak `POST`; use an
  MCP client to actually call it.
</Tip>

## Connect a client

<CodeGroup>
  ```json Claude Desktop / Claude Code (claude_desktop_config.json / .mcp.json) theme={null}
  {
    "mcpServers": {
      "ravn": {
        "url": "https://app.ravn.exchange/api/mcp"
      }
    }
  }
  ```

  ```json Cursor (.cursor/mcp.json) theme={null}
  {
    "mcpServers": {
      "ravn": {
        "url": "https://app.ravn.exchange/api/mcp"
      }
    }
  }
  ```
</CodeGroup>

Any client that supports remote MCP servers over Streamable HTTP works the same way; there's
nothing to install locally.

## Try it: one prompt, one loop

With the config above added, prompt your client with something like:

> Swap 0.01 ETH on Ethereum to USDC on Base for 0x1234...5678, my wallet address.

A capable MCP client resolves that into:

1. `ravn_quote({ inputChainId: 1, outputChainId: 8453, inputToken: "0xEeee...EEeE", outputToken: "<Base USDC address>", inputAmount: "10000000000000000", userAddress: "0x1234...5678" })` → returns a `quoteToken` plus the priced route.
2. `ravn_execute({ quoteToken })` → returns `{ executionType: "TRANSACTION", transaction: {...} }` for this route (0x Gasless/RFQ-style routes instead return `SIGNATURE`).
3. Your agent signs and sends the returned `transaction` with its own wallet — RAVN never touches it.
4. `ravn_status({ quoteToken, ref: <statusRef from step 2> })`, polled until `status` is terminal (`success`, `refunded`, or `failed`).

No other setup, no API key, no payment. See [Execution Types](/execution-types) for what
`transaction` looks like for each `executionType`, and [Signing: who holds the wallet?](/ai-agents/overview#signing-who-holds-the-wallet)
for how an autonomous agent handles step 3 without a human clicking "confirm."

## Tools

### `ravn_quote`

Get a swap quote, same-chain or cross-chain, across all 16 supported chains including native
Bitcoin and Solana as source or destination. Returns a `quoteToken` to pass to `ravn_execute`.

| Argument             | Type                           | Required | Notes                                                              |
| -------------------- | ------------------------------ | -------- | ------------------------------------------------------------------ |
| `inputChainId`       | number                         | yes      | See [chain IDs](#chain-ids) below                                  |
| `outputChainId`      | number                         | yes      |                                                                    |
| `inputToken`         | string                         | yes      | Contract address, or `0xEeee…EEeE` for the chain's native coin     |
| `outputToken`        | string                         | yes      |                                                                    |
| `inputAmount`        | string                         | yes      | Positive integer, in the input token's smallest unit (no decimals) |
| `userAddress`        | string                         | yes      | Address the input asset will be sent from                          |
| `destinationAddress` | string                         | no       | Where output should land, if different from `userAddress`          |
| `refundAddress`      | string                         | no       |                                                                    |
| `slippageBps`        | number                         | no       | 1 to 5000                                                          |
| `rankingMode`        | `"best_output"` \| `"fastest"` | no       | Defaults to `best_output`                                          |
| `apiKey`             | string                         | no       | Your RAVN API key, if you have one                                 |

### `ravn_execute`

Turn a `quoteToken` from `ravn_quote` into an execution payload.

| Argument             | Type   | Required |
| -------------------- | ------ | -------- |
| `quoteToken`         | string | yes      |
| `destinationAddress` | string | no       |
| `refundAddress`      | string | no       |
| `apiKey`             | string | no       |

Returns one of three shapes, tagged by `executionType`:

* **`TRANSACTION`**: sign and broadcast yourself
* **`SIGNATURE`**: sign, RAVN submits on your behalf
* **`DEPOSIT`**: send the input asset to a given address (the common case for Bitcoin-source
  swaps; see `ravn_btc_prepare_send` below)

RAVN never takes custody of funds under any of the three; you always sign or send from your
own wallet.

### `ravn_status`

Poll a swap's status.

| Argument     | Type   | Required | Notes                                                                                       |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `quoteToken` | string | yes      |                                                                                             |
| `ref`        | string | yes      | Deposit address (`DEPOSIT` venues) or `statusRef` (`SIGNATURE` venues), from `ravn_execute` |
| `apiKey`     | string | no       |                                                                                             |

Status is authoritative where the venue exposes it. A few venues (Rift, Jupiter, Bebop, 0x
Gasless) report `"unknown"` honestly rather than guessing. Check the response's `tracking`
field.

### `ravn_health`

No arguments. Liveness check across every venue RAVN routes through, useful to call before a
swap if you want to know whether a route is degraded ahead of time.

### `ravn_btc_prepare_send`

Turns a `DEPOSIT`-type `ravn_execute` result into a ready-to-sign Bitcoin transaction (a PSBT),
so your agent doesn't have to implement UTXO selection or fee estimation itself.

| Argument           | Type                       | Required | Notes                                                                                              |
| ------------------ | -------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `fromAddress`      | string                     | yes      | Your Bitcoin address holding the UTXOs to spend; native SegWit (`bc1q…`) or Taproot (`bc1p…`) only |
| `toAddress`        | string                     | yes      | The `depositAddress` from `ravn_execute`                                                           |
| `amountSats`       | string                     | yes      | The `depositAmount` from `ravn_execute`, in satoshis                                               |
| `feeRateSatsPerVb` | number                     | no       | Omit to use mempool.space's current fee estimate                                                   |
| `network`          | `"mainnet"` \| `"testnet"` | no       | Defaults to `mainnet`                                                                              |

UTXOs and the fee rate are fetched from the public [mempool.space](https://mempool.space) API,
with no keys and no auth required.

<Note>
  RAVN never sees or handles a private key at any point. The response is an unsigned PSBT
  (`psbtBase64`): sign it with your own wallet's key and broadcast it yourself.
</Note>

Only one signature is ever needed. Every RAVN Bitcoin-source venue (Garden, Chainflip, NEAR
Intents, Rift) resolves to a plain, single-recipient payment, not a multi-wallet
UTXO-co-signing ceremony some other aggregators require for their BTC routes.

## Chain IDs

| Chain       | ID   |   | Chain           | ID     |
| ----------- | ---- | - | --------------- | ------ |
| Ethereum    | 1    |   | Robinhood Chain | 4663   |
| Optimism    | 10   |   | **Bitcoin**     | **-1** |
| BNB Chain   | 56   |   | **Solana**      | **-2** |
| Unichain    | 130  |   | Monad           | 143    |
| Polygon     | 137  |   | HyperEVM        | 999    |
| zkSync      | 324  |   | Arbitrum        | 42161  |
| World Chain | 480  |   | Linea           | 59144  |
| Base        | 8453 |   | Avalanche       | 43114  |

Bitcoin and Solana use negative sentinel IDs rather than their (non-existent, in Bitcoin's
case) EVM chain IDs. Don't assume 0 or a positive placeholder.

## A full loop, end to end

1. `ravn_quote`: get a `quoteToken`
2. `ravn_execute`: get back `TRANSACTION` / `SIGNATURE` / `DEPOSIT`
   * If `DEPOSIT` and the input asset is Bitcoin: `ravn_btc_prepare_send` → sign the PSBT with
     your own wallet → broadcast
   * Otherwise: sign/send with your own wallet per the returned payload
3. `ravn_status`: poll until terminal