# RAVN [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/ravndex/ravn-examples  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ravn-2

## Description
Cross-chain swap aggregator across 16+ chains, incl. native Bitcoin/Solana. 0% fees, non-custodial.

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "ravn": {
    "url": "https://smithery.ai/badge/team-dgp6/ravn)](https://smithery.ai/servers/team-dgp6/ravn"
  }
}
```

## Documentation & README

# RAVN examples

[![smithery badge](https://smithery.ai/badge/team-dgp6/ravn)](https://smithery.ai/servers/team-dgp6/ravn)

Working code for the [RAVN](https://ravn.exchange) cross-chain swap API — including **native
Bitcoin**, not wrapped BTC.

One integration covers 16 chains (14 EVM + Bitcoin + Solana). Every quote races 12 execution
venues in parallel and the best net output wins. **RAVN takes 0 bps on every route.** Non-custodial:
RAVN never holds your funds and writes no smart contracts of its own.

No signup required to start. Every example below runs anonymously.

```bash
git clone https://github.com/ravndex/ravn-examples
cd ravn-examples && npm install
npm run health
```

## The examples

| | What it shows |
| --- | --- |
| [`src/health.ts`](https://github.com/ravndex/ravn-examples/blob/HEAD/src/health.ts) | 10-second smoke test — which venues are racing right now. Start here. |
| [`src/btc-out.ts`](https://github.com/ravndex/ravn-examples/blob/HEAD/src/btc-out.ts) | **USDC on Base → native BTC**, end to end. The one most swap APIs can't do. Dry-runs without a wallet. |
| [`src/agent-swap.ts`](https://github.com/ravndex/ravn-examples/blob/HEAD/src/agent-swap.ts) | Claude tool-calling loop: the model picks the swap, your code keeps the keys. |
| [`src/x402-client.ts`](https://github.com/ravndex/ravn-examples/blob/HEAD/src/x402-client.ts) | Pay-per-call over [x402](https://x402.org) — no key, no account. |
| [`src/ravn.ts`](https://github.com/ravndex/ravn-examples/blob/HEAD/src/ravn.ts) | The whole client, ~150 lines. There is no SDK because you don't need one — copy this file. |
| [`MCP.md`](https://github.com/ravndex/ravn-examples/blob/HEAD/MCP.md) | Point Claude or Cursor at the hosted MCP server. Three lines of config. |

## The contract

Four calls, always the same order.

```
POST /quote   → best route + an opaque quoteToken
POST /execute → an execution payload tagged by executionType
                (+ submit-signature, when the type is SIGNATURE)
GET  /status  → pending → processing → success (or refunded / failed)
```

Everything branches on **one field**:

```ts
switch (execution.executionType) {
  case "TRANSACTION": // sign and broadcast it yourself
  case "SIGNATURE":   // sign typed data; RAVN submits it, no gas
  case "DEPOSIT":     // send the input asset to an address
}
```

### The one thing that trips people up

An ERC-20 swap is really **two** transactions. Before any contract can move your tokens you must
sign a separate on-chain permission — an `approve()`. `TRANSACTION` and `SIGNATURE` payloads carry
that ready to send, as **`approval`**, whenever it's needed.

```ts
if (execution.approval) {
  const hash = await wallet.sendTransaction(execution.approval);
  await client.waitForTransactionReceipt({ hash });   // MINED, not just broadcast
}
// …now send the swap
```

Broadcasting the swap before the allowance is **mined** reverts on `transferFrom` and the user eats
the gas. On gasless venues (CoW, Bebop) it's quieter and worse: the order is accepted and simply
**never fills**, with no error. Native-coin sells, already-approved tokens and `DEPOSIT` routes omit
`approval` entirely.

RAVN doesn't read the chain for you, so `approval` can appear on a token you've already approved —
check the allowance for `approval.spender` and skip it when it already covers `approval.amount`.

`unlimitedRecommended: true` (CoW) means the venue would rather you approve once for a large amount
than pay approval gas on every swap. `data` still encodes the exact amount; raising it is your call.

## Amounts

Always strings, always the token's smallest unit — wei, lamports, satoshis. Never floats.
`toBaseUnits()` / `fromBaseUnits()` in [`src/ravn.ts`](https://github.com/ravndex/ravn-examples/blob/HEAD/src/ravn.ts) convert safely.

## Cross-ecosystem swaps

Selling on EVM and receiving BTC or SOL needs a `destinationAddress` — the payout chain has no
idea what your EVM address is.

## Rate limits

| | |
| --- | --- |
| No key | 30 req/min per IP |
| [Free key](https://docs.ravn.exchange/tools/get-api-key), instant, no review | 120 req/min |

Pass it as `x-api-key`. **CORS is enabled on every endpoint**, so browser-side dapps and wallet
widgets can call the API directly with no server-side proxy.

## Errors

Branch on the stable `code`, never the message.

`INVALID_REQUEST` · `UNSUPPORTED_TOKEN` · `UNSUPPORTED_CHAIN` · `NO_LIQUIDITY` · `QUOTE_EXPIRED` ·
`QUOTE_INVALID` · `RATE_LIMITED` · `UNAUTHORIZED` · `INTERNAL`

Every response carries `x-request-id`. Quote it if you report a bad quote — it's how we find it.

## Links

- Docs — <https://docs.ravn.exchange>
- App — <https://app.ravn.exchange>
- MCP server — `https://app.ravn.exchange/api/mcp`
- OpenAPI spec (Postman / Insomnia import) — `https://app.ravn.exchange/openapi.json`
- Partnerships — team@ravn.exchange · [@ravnexchange](https://x.com/ravnexchange)

MIT licensed. Issues and PRs welcome.