RAVN

exchange.ravnPublished by ravn.exchangeOfficial publisherv1.0.3Updated Oct 24, 2026

Cross-chain swap API for native Bitcoin, Solana and EVM chains. No API key, no custody.

VerifiedStreamable HTTPWeb executableFinanceDeveloper Tools

Overview

AI-generated overview

RAVN's hosted MCP server lets an assistant quote, prepare and track cross-chain crypto swaps across EVM chains, native Bitcoin and Solana.

What you can do
  • Quote swaps: get best-route quotes for same-chain or cross-chain swaps, list supported chains and tokens, resolve token addresses, and check BTC destination coverage and venue health.
  • Prepare execution: turn a quote into a signable payload (transaction, signature or deposit) and build a ready-to-sign Bitcoin PSBT for deposit routes.
  • Submit and track: submit collected signatures to place an order and poll swap status until it is final.
When to use it
Useful when an assistant needs to help a user move tokens between chains or ecosystems, including native BTC and SOL, and the user keeps their own keys and signs locally. Also handy for building token pickers or checking which routes are live before proposing a swap.
Requirements
Remote streamable HTTP endpoint at app.ravn.exchange; no signup, API key or payment needed to start. A free key can be passed as x-api-key for higher rate limits. Anonymous use is limited to 30 requests per minute per IP plus 120 status polls per minute. A wallet is needed to sign or send the payloads.
Before you install
The server prepares real fund-moving transactions: the assistant's output must be signed or broadcast by the user's wallet, and deposit routes require sending assets to an address. ERC-20 swaps may need a separate approve() mined before the swap, or the swap reverts or silently never fills. Amounts are strings in smallest units. Optional integrator fees must be paid and swaps reported to status to be paid out. Rate limits apply.

Installation

In SourceWeft

  1. Open RAVN in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/exchange.ravn%2Fravn/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

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

README

RAVN examples

[smithery badge]

Working code for the RAVN cross-chain swap API — including native Bitcoin, not wrapped BTC.

One integration covers EVM chains, native Bitcoin and Solana. Every quote races every live execution venue 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-examplescd ravn-examples && npm installnpm run health

The examples

What it shows
src/health.ts10-second smoke test — which venues are racing right now. Start here.
src/btc-out.tsUSDC on Base → native BTC, end to end on the SDK's executeAndTrack, fee and status reporting included. The one most swap APIs can't do. Dry-runs without a wallet.
src/agent-swap.tsClaude tool-calling loop: the model picks the swap, your code keeps the keys.
src/x402-client.tsPay-per-call over x402 — no key, no account.
src/ravn.tsThe shared client: the official @ravnexchange/sdk (zero dependencies, typed) plus amount helpers.
MCP.mdPoint 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 quoteTokenPOST /execute → an execution payload tagged by executionType, with its own quoteToken                (+ submit-signature, when the type is SIGNATURE)POST /status  → pending → processing → success (or refunded / failed)

Poll /status with the quoteToken execute returned, its statusRef (else your swap's tx hash), and as txHash the hash of the fee payment you sent beside the swap, or on a two-step route (a statusRef came with a TRANSACTION) your swap's own tx hash, until the status is final. Use POST: a quoteToken can run to tens of kilobytes, and a large one in a GET query string fails.

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 { to, data, value } = execution.approval;            // value is a decimal string  const hash = await wallet.sendTransaction({ to, data, value: BigInt(value) });  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 and DEPOSIT routes never carry approval.

RAVN reads your user's allowance on-chain at /execute and leaves approval out when it already covers the amount. When that read fails, approval is included anyway, so check the allowance for approval.spender yourself and skip it when it covers approval.amount (btc-out.ts does, through executeAndTrack's hasAllowance). RAVN's read sees the latest block only, so run one swap per token and spender at a time. An approval.reset (Ethereum USDT holding a partial allowance) is an approve(spender, 0) to send and mine first; executeAndTrack does.

0x Gasless can also return approvalData: a second typed-data signature that approves the token gaslessly, sent to /submit-signature as approvalSignature. executeAndTrack signs it for you.

Collecting your fee

If your key sets a fee, a swap only pays you when you do two things:

  1. Pay execution.fee exactly as returned, when there is one (Rift, private swaps, Eco Routes, Layerswap, Mayan routes paying no referrer). EVM: send fee.transaction once the swap has succeeded, or batch an ERC-20 fee with it. Bitcoin: the fee is a second output of the deposit's own transaction. Solana: the transfer goes inside the deposit's own transaction.
  2. Report the swap to /status until it's final, with that fee payment's hash (on a two-step route, your swap's own hash) as txHash on every poll. On same-chain venues RAVN only learns a swap happened from your poll: never reported, never paid.

On a TRANSACTION, executeAndTrack pays the fee and hands you the hash to poll with (statusTxHash); from SDK 0.2.0 its own polling also runs through expired and not_found and retries a failed status call. A DEPOSIT it leaves to you: btc-out.ts sends the deposit and the fee, then polls them all through one loop. The full checklist: https://docs.ravn.exchange/collecting-your-fee

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 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 key30 req/min per IP, plus 120 /status polls/min
Free key, instant, no review120 req/min, plus 480 /status polls/min

Status polls have a budget of their own (4× your limit). Every rate-limited response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds), and a 429 adds Retry-After. Pass your key 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 (an unsupported chain is one of these) · UNSUPPORTED_TOKEN · NO_LIQUIDITY · QUOTE_EXPIRED · QUOTE_INVALID · QUOTE_NOT_EXECUTABLE · BUILD_FAILED · ORDER_REJECTED · VENUE_RATE_LIMITED · RATE_LIMITED · UNAUTHORIZED · UNAVAILABLE · NOT_FOUND · NOT_CONFIGURED · INTERNAL. The SDK adds NETWORK_ERROR when no response came back at all. Full table: https://docs.ravn.exchange/errors

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

Links

MIT licensed. Issues and PRs welcome.

Source: README.md at commit 56ceac9

Tools

10

ravn_quote

Get a RAVN swap quote

Get a swap quote from RAVN — same-chain or cross-chain, across 18 chains including native (non-wrapped) Bitcoin and Solana as source or destination. Free, no API key or payment required. Returns a quoteToken; pass it to ravn_execute to get a signable/broadcastable execution payload.

ParametersapiKeytimeoutMsinputTokenrequiredonlyVenuesinputAmountrequiredoutputTokenrequiredrankingModeslippageBpsuserAddressrequiredconfidentialinputChainIdrequiredexcludeVenues+4 more

ravn_execute

Execute a RAVN swap quote

Turn a quoteToken from ravn_quote into an execution payload. Returns one of three shapes (executionType): TRANSACTION (sign and broadcast yourself), SIGNATURE (sign, RAVN submits), or DEPOSIT (send the input asset to a given address). RAVN never takes custody of funds — you always sign or send from your own wallet. TRANSACTION and SIGNATURE may also include an `approval` — an ERC-20 approve() you must broadcast and wait to be MINED before the transaction/signature, or it fails (reverts on TRANSACTION; on SIGNATURE the order is accepted and silently never fills). Only present when the sold token needs it — omitted for native-coin sells and already-approved tokens. An `approval.reset` (Ethereum USDT holding a partial allowance) goes first, mined, then the approval. A result with `sandbox: true` is a test: send nothing from it.

ParametersapiKeyquoteTokenrequiredrefundAddressdestinationAddress

ravn_submit_signature

Submit a signed RAVN order

For a SIGNATURE-type ravn_execute result only: submit the signature(s) you collected (over typedData, and approvalData if present) to actually place the order. RAVN decodes the venue from quoteToken and routes to the right venue-specific submit path — you never touch a per-venue endpoint. Returns a statusRef — pass it to ravn_status as `ref` to poll this swap.

ParametersapiKeysignaturerequiredquoteTokenrequiredapprovalSignature

ravn_status

Check RAVN swap status

Poll the status of a swap by its quoteToken and ref from ravn_execute (statusRef, deposit address, or origin tx hash). Use the quoteToken execute returned — compose rebinds hop 1 onto hop 2's deposit. Status is authoritative where the venue exposes it; a swap the venue can't track reports 'unknown' rather than a guess.

ParametersrefrequiredapiKeytxHashquoteTokenrequired

ravn_health

Check RAVN venue health

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

Takes no parameters.

ravn_tokens

List RAVN's token registry for a chain

RAVN's own listed token registry for one chain — populate a token picker without hardcoding one. This is "what RAVN knows about and might route", not a per-pair routability guarantee for any specific pair; call ravn_quote to check that.

ParametersapiKeychainIdrequired

ravn_tokens_resolve

Resolve a token address to its metadata

Resolve an arbitrary token address to its metadata (symbol, name, decimals) via an on-chain read — for a paste-any-address flow, when the token isn't necessarily on ravn_tokens's list.

ParametersapiKeyaddressrequiredchainIdrequired

ravn_btc_coverage

Which tokens actually route from native Bitcoin

For a swap where native BTC is the source, not every token on the destination chain is reachable. Returns which of ravn_tokens's list on `chainId` a BTC venue can actually route to, and how many venues serve each, so you can build a token list that matches what will really quote instead of discovering it one NO_LIQUIDITY at a time. BTC-as-source only — selling a token INTO BTC isn't restricted the same way (nearly any token can be sold into BTC), so this has nothing useful to say about that direction.

ParametersapiKeychainIdrequired

ravn_chains

List every chain RAVN supports

Every chain RAVN lists a token registry for (see ravn_tokens). Static, doesn't change per request, safe to cache instead of hardcoding a chain table.

ParametersapiKey

ravn_btc_prepare_send

Prepare a signable Bitcoin transaction for a RAVN DEPOSIT

Turns a DEPOSIT-type ravn_execute result (deposit.address + deposit.amount) into a ready-to-sign PSBT, so you don't have to write your own UTXO selection and fee-estimation code. If that result also has a `fee` (an integrator fee RAVN collects beside the deposit), pass its fee.address as feeAddress and fee.amount as feeAmountSats: the PSBT then pays it as a second output of the same transaction, which is the only place RAVN looks for it. Fetches your UTXOs and the current network fee rate from mempool.space (public, no auth). RAVN never sees or touches a private key — sign the returned PSBT with your own wallet and broadcast it yourself. Only one signer is ever needed (unlike PSBT flows that require coordinating signatures across multiple UTXO-holding wallets), because every RAVN BTC-source venue resolves to a plain payment to the deposit address (plus RAVN's fee output, when there is one).

ParametersnetworktoAddressrequiredamountSatsrequiredfeeAddressfromAddressrequiredfeeAmountSatsfeeRateSatsPerVb

Version history

2
  1. v1.0.3LatestSep 25, 2026
  2. v1.0.2Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts