RAVN

exchange.ravn由 ravn.exchange 發布官方發布者v1.0.3更新於 Oct 24, 2026

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

已驗證Streamable HTTP可網頁執行金融開發者工具

概覽

AI 產生的概覽

RAVN 託管 MCP 伺服器，讓助理為 EVM 鏈、原生比特幣與 Solana 之間的跨鏈兌換報價、產生執行載荷並追蹤狀態。

可以做什麼
  • 報價：取得同鏈或跨鏈兌換的最佳報價，列出支援的鏈與代幣，解析代幣地址中繼資料，查詢 BTC 目的代幣涵蓋範圍與各交易場所的健康狀態。
  • 準備執行：把報價轉成可簽署的載荷（交易、簽章或存款三種類型），並為存款路線產生可直接簽署的比特幣 PSBT。
  • 提交與追蹤：提交已收集的簽章以下單，並輪詢兌換狀態直到最終結果。
適用情境
適合助理協助使用者在鏈與鏈之間或生態系之間轉移代幣（包含原生 BTC 與 SOL），且使用者自行保管私鑰並在本機簽署。也適合建立代幣選擇清單，或在提出兌換前確認哪些路線目前可用。
執行需求
遠端 streamable HTTP 端點 app.ravn.exchange；不需註冊、API 金鑰或付費即可開始。可選用免費金鑰透過 x-api-key 提高速率上限。匿名使用限制為每個 IP 每分鐘 30 次請求，另加每分鐘 120 次狀態輪詢。簽署或送出載荷需要錢包。
安裝前請注意
此伺服器會產生真正動用資金的交易：輸出必須由使用者錢包簽署或廣播，存款路線需要把資產送到指定地址。ERC-20 兌換可能需要先單獨送出並確認 approve()，否則交易會回滾或無聲地無法成交。金額為最小單位的字串。可選的整合方費用需依回傳結果支付，並向 status 回報兌換才能取得結算。有速率限制。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 RAVN，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable，透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式，或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南，先向你展示發布者、端點和登入方式，經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/exchange.ravn%2Fravn/install.md，並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前，先告訴我它的發布者、端點和登入方式，等我確認。不要把 API 金鑰寫進命令或我會提交的檔案；問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

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

來源：README.md，提交 56ceac9

工具

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.

輸入參數apiKeytimeoutMsinputToken必填onlyVenuesinputAmount必填outputToken必填rankingModeslippageBpsuserAddress必填confidentialinputChainId必填excludeVenues另有 4 個

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.

輸入參數apiKeyquoteToken必填refundAddressdestinationAddress

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.

輸入參數apiKeysignature必填quoteToken必填approvalSignature

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.

輸入參數ref必填apiKeytxHashquoteToken必填

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.

無需輸入參數。

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.

輸入參數apiKeychainId必填

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.

輸入參數apiKeyaddress必填chainId必填

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.

輸入參數apiKeychainId必填

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.

輸入參數apiKey

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

輸入參數networktoAddress必填amountSats必填feeAddressfromAddress必填feeAmountSatsfeeRateSatsPerVb

版本歷史

2
  1. v1.0.3最新Sep 25, 2026
  2. v1.0.2Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分