RAVN

RAVN 示例

RAVN 跨链兑换 API 的可运行代码示例——包括原生 Bitcoin，而非封装版 BTC。

一次集成即可覆盖 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 服务。只需三行配置。

调用约定

始终按相同顺序调用 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)

使用 /execute 返回的 quoteToken，以及它的 statusRef（否则使用兑换的交易哈希），并将你在兑换旁发送的费用支付哈希作为 txHash 传入 /status 进行轮询；对于双步骤路线（TRANSACTION 中包含 statusRef），则将兑换本身的交易哈希作为 txHash，直到状态最终确定。 使用 POST：quoteToken 可能达到几十 KB，过长的内容放在 GET 查询字符串中会导致请求失败。

一切都由一个字段决定：

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 兑换实际上需要两笔交易。在任何合约能转移你的代币之前，你必须先签署一笔独立的链上授权——即 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 回滚，用户还得承担 Gas 费。在免 Gas 场所（CoW、Bebop），情况更隐蔽，也更糟：订单会被接受，却永远不会成交，并且没有错误提示。原生币卖出和 DEPOSIT 路线都不会携带 approval。

RAVN 会在 /execute 时读取用户链上的授权额度，如果额度已覆盖兑换金额，就不会返回 approval。如果读取失败，则仍会包含 approval，因此你需要自行检查 approval.spender 的授权额度；如果额度已覆盖 approval.amount，则跳过授权（btc-out.ts 会通过 executeAndTrack 的 hasAllowance 完成这项检查）。RAVN 只读取最新区块，因此同一代币和 spender 同一时间只能执行一笔兑换。如果返回 approval.reset（Ethereum 上的 USDT 存在部分授权额度），则需要先发送 approve(spender, 0) 并等待其上链确认；executeAndTrack 会处理这一流程。

0x Gasless 也可能返回 approvalData：用于免 Gas 授权代币的第二个类型化数据签名，并作为 approvalSignature 发送到 /submit-signature。executeAndTrack 会为你完成签名。

收取你的费用

如果你的密钥设置了费用，只有完成以下两件事，兑换才会向你支付费用：

1. 按 execution.fee 返回的内容准确支付，如果有该字段（Rift、私人兑换、Eco Routes、Layerswap、Mayan 不支付推荐费的路线）。EVM：兑换成功后发送 fee.transaction，或将 ERC-20 费用与兑换打包发送。Bitcoin：费用是存款交易自身的第二个输出。Solana：转账包含在存款交易自身中。
2. 持续向 /status 报告兑换状态，直到交易最终确认，每次轮询都将该笔费用支付的哈希（两步路线中，则使用兑换本身的哈希）作为 txHash。对于同链交易平台，RAVN 只能通过你的轮询得知兑换已发生：从未报告，就从未支付。

对于 TRANSACTION，executeAndTrack 会支付费用，并将供你轮询的哈希（statusTxHash）交给你；从 SDK 0.2.0 起，它自身的轮询也会持续到 expired 和 not_found，并在状态调用失败时重试。DEPOSIT 则由你处理：btc-out.ts 会发送存款和费用，然后在一个循环中轮询所有交易。完整检查清单：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 次请求，另加每分钟 120 次 /status 轮询
免费密钥，即时获取，无需审核	每分钟 120 次请求，另加每分钟 480 次 /status 轮询

状态轮询有独立的额度（为你的限制的 4 倍）。每个受速率限制的响应都包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset（Unix 时间戳秒数）；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。如果要报告有问题的报价，请附上该 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 许可。欢迎提交问题和 PR。