RAVN

RAVN の使用例

RAVN のクロスチェーンスワップ API の実際に動作するコードです。ラップド BTC ではない、ネイティブ Bitcoin も含まれます。

1 つの統合で EVM チェーン、ネイティブ Bitcoin、Solana に対応します。すべての見積もりで、稼働中のすべての実行先を並列で競わせ、最も高い実質受取額を選びます。RAVN はすべてのルートで 0 bps です。 ノンカストディアルです。RAVN が資金を預かることはなく、独自のスマートコントラクトも作成しません。

登録不要です。以下のすべての例は匿名で実行できます。

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

使用例

	内容
src/health.ts	10 秒のスモークテスト — 現在競争中の実行先を確認します。まずはこちらから。
src/btc-out.ts	Base 上の USDC → ネイティブ BTC。SDK の executeAndTrack によるエンドツーエンドの実行で、手数料とステータスの報告も含みます。ほとんどのスワップ API ではできないことです。ウォレットなしでドライランできます。
src/agent-swap.ts	Claude のツール呼び出しループです。モデルがスワップを選び、鍵はコードが管理します。
src/x402-client.ts	x402 による呼び出しごとの支払い — キーもアカウントも不要です。
src/ravn.ts	共通クライアントです。公式の @ravnexchange/sdk（依存関係ゼロ、型付き）と金額ヘルパーを提供します。
MCP.md	Claude または Cursor をホスト型 MCP サーバーに接続します。設定は 3 行です。

契約

呼び出しは 4 回で、順序は常に同じです。

POST /quote   → best route + an opaque quoteToken
POST /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)

返された quoteToken の execute、その statusRef（ない場合はスワップの tx ハッシュ）、および txHash に、スワップと合わせて送信した手数料支払いのハッシュを指定して /status をポーリングし、ステータスが確定するまで続けます。ただし、2 段階ルート（TRANSACTION に statusRef が含まれる場合）では、txHash にスワップ自体の tx ハッシュを指定します。 quoteToken は数十キロバイトになることがあり、長い値を GET のクエリー文字列に含めると失敗するため、POST を使用してください。

処理の分岐は 1 つのフィールド で決まります。

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
}

注意が必要な点

ERC-20 のスワップは、実際には 2 つのトランザクションです。コントラクトがトークンを移動する前に、別途オンチェーンの許可である approve() に署名する必要があります。必要な場合、TRANSACTION と SIGNATURE のペイロードには、送信準備が整った許可が approval として含まれます。

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

許容量がマイニングされる前にスワップをブロードキャストすると、transferFrom が失敗し、ユーザーはガス代を失います。ガスレスの実行先（CoW、Bebop）では、より気付きにくく、さらに悪いことになります。注文は受け付けられるものの、エラーもなく一切約定しません。ネイティブコインの売却と DEPOSIT ルートには approval は含まれません。

RAVN は /execute でユーザーの許容量をオンチェーンで確認し、すでに必要額を満たしていれば approval を省略します。この確認に失敗した場合は approval が含まれるため、approval.spender の許容量を自分で確認し、approval.amount を満たしていればスキップしてください（btc-out.ts では executeAndTrack の hasAllowance を通じて処理します）。RAVN の確認で参照されるのは最新ブロックのみなので、トークンと spender の組み合わせごとに、一度に 1 件のスワップだけを実行してください。approval.reset（Ethereum USDT に部分的な許容量が設定されている場合）は、approve(spender, 0) を送信して先にマイニングする必要があります。これは executeAndTrack が処理します。

0x Gasless からは approvalData が返されることもあります。これはトークンをガスレスで許可するための 2 つ目の typed-data 署名で、approvalSignature として /submit-signature に送信します。executeAndTrack が代わりに署名します。

手数料の受け取り

キーに手数料が設定されている場合、次の2つの操作を行ったときにのみ、スワップの手数料を受け取れます。

1. execution.fee が返された場合は、その内容どおりに正確に支払います（Rift、プライベートスワップ、Eco Routes、Layerswap、紹介料が支払われないMayanルート）。EVM：スワップの成功後に fee.transaction を送信するか、ERC-20の手数料をスワップとまとめて送信します。Bitcoin：手数料は入金トランザクション自体の2つ目の出力です。Solana：送金は入金トランザクション自体に含めます。
2. スワップが確定するまで /status に報告し、すべてのポーリングで手数料支払いのハッシュを txHash として指定します（2段階のルートでは、スワップ自体のハッシュを指定します）。同一チェーンの取引所では、RAVNはポーリングからしかスワップの発生を認識できません。報告されなければ、手数料も支払われません。

TRANSACTION の場合、executeAndTrack が手数料を支払い、ポーリングに使うハッシュ（statusTxHash）を渡します。SDK 0.2.0以降では、内部ポーリングも expired と not_found の状態まで実行され、ステータス呼び出しが失敗した場合は再試行します。DEPOSIT の処理はユーザーに委ねられます。btc-out.ts は入金と手数料を送信し、その後、1つのループですべてをポーリングします。詳細なチェックリスト：https://docs.ravn.exchange/collecting-your-fee

unlimitedRecommended: true（CoW）は、スワップのたびに承認のガス代を支払うより、一度の承認で大きな金額を承認することを取引所が推奨していることを意味します。data には引き続き正確な金額がエンコードされます。金額を増やすかどうかは任意です。

金額

常に文字列で、トークンの最小単位（wei、lamports、satoshis）を使います。浮動小数点数は使わないでください。 src/ravn.ts の toBaseUnits() / fromBaseUnits() で安全に変換できます。

エコシステム間のスワップ

EVMで売却してBTCまたはSOLを受け取るには、destinationAddress が必要です。受取側のチェーンは、EVMアドレスを認識できません。

レート制限

キーなし	IPあたり30リクエスト/分、さらに /status のポーリングは120回/分
無料キー、即時発行、審査なし	120リクエスト/分、さらに /status のポーリングは480回/分

ステータスのポーリングには、独自の上限（通常の制限の4倍）があります。レート制限されたレスポンスにはすべて X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（エポック秒）が含まれ、429 には Retry-After が追加されます。キーは x-api-key として渡してください。すべてのエンドポイントでCORSが有効なため、ブラウザー側のdappやウォレットウィジェットから、サーバー側のプロキシを介さずにAPIを直接呼び出せます。

エラー

メッセージではなく、安定した code に基づいて分岐してください。

INVALID_REQUEST（未対応のチェーンもこれに該当します） · 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。レスポンスがまったく返ってこなかった場合、SDKは NETWORK_ERROR を追加します。完全な一覧：https://docs.ravn.exchange/errors

すべてのレスポンスには x-request-id が含まれます。不適切な見積もりを報告する際は、この値をお知らせください。問題の特定に使用します。

リンク

• ドキュメント — https://docs.ravn.exchange
• アプリ — https://app.ravn.exchange
• MCP サーバー — https://app.ravn.exchange/api/mcp
• OpenAPI仕様（Postman / Insomniaへのインポート用） — https://app.ravn.exchange/openapi.json
• パートナーシップ — [email protected] · @ravnexchange

MITライセンスです。Issueやプルリクエストを歓迎します。