Soheil Router

Soheil Router

一次 API 调用即可获取最佳代币兑换价格，一笔交易即可完成兑换。 Soheil Router 会比较各网络上 DEX 和聚合器的价格，并通过自有合约执行交易：合约不可升级，已在区块浏览器上验证源码，且交易之间不会持有资金。

• 文档： https://soheil.fi/developers/docs/
• 免费 API 密钥： https://soheil.fi/developers/dashboard/
• OpenAPI 3.1： https://api.soheil.fi/v1/openapi.json
• 供 AI 助手使用： https://soheil.fi/developers/llms-full.txt · MCP 服务地址：https://api.soheil.fi/v1/mcp

费用

每笔兑换向路由器收取 0.1%（10 bps）。你可以添加自己的费用（最高 0.9%），并在同一笔交易中支付到你的钱包：无需另行领取。

安装

npm install github:soheil-fi/soheil-router

快速开始

import { COIN, SoheilRouter } from "@soheil-fi/router";

const router = new SoheilRouter({ apiKey: process.env.SOHEIL_ROUTER_KEY }); // keep the key on your server

const quote = await router.getQuote({
  fromChainId: 8453,                                       // Base
  fromToken: COIN,                                         // ETH
  toToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",   // USDC
  fromAmount: 10n ** 15n,                                  // 0.001 ETH, in wei
  fromAddress: "0xUserWallet",
  integratorBps: 30,                                       // your fee: 0.3%
});

// quote.approvalAddress → approve exactly quote.fromAmount first (null when selling the coin)
// quote.transactionRequest → have the user's wallet send it unchanged
const status = await router.waitForTrade(8453, txHash);     // DONE, REFUNDED, FAILED or NOT_OURS

使用 viem 完成的完整兑换示例见 examples/swap-viem.ts。

方法	密钥	返回值
getNetworks()	否	实时网络、我们的合约，以及交易可能调用的合约
getInfo()	否	费用、限制、文档
getQuote(request)	是	价格、最低到账金额、费用、授权地址、交易
getStatus(chainId, txHash)	是	PENDING、DONE、REFUNDED、FAILED、NOT_OURS 或 NOT_FOUND
waitForTrade(chainId, txHash)	是	持续调用 getStatus，直到交易完成

错误会以 SoheilRouterError 的形式抛出，其中包含 code（NO_ROUTE、RATE_LIMITED、UNAUTHORIZED……）、HTTP status 和可安全展示给用户的 message。

跨链到另一个网络

将 toChainId 设置为路由器支持的另一个网络。返回结果的 type 为 "bridge"，用户仍只需在源网络上签署一笔交易；几秒内，收款人就会在目标网络收到款项。

const quote = await router.getQuote({
  fromChainId: 8453,                                       // from Base
  toChainId: 42161,                                        // to Arbitrum
  fromToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
  toToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",   // USDC on Arbitrum
  fromAmount: 100_000_000n,                                // 100 USDC
  fromAddress: "0xUserWallet",
});
// quote.toAmount is what arrives; a transfer nobody fills is refunded to fromAddress on Base (status REFUND_PENDING until then)
const status = await router.waitForTrade(8453, txHash);     // DONE (status.receiving = the payout) or REFUNDED

fromToken 和 toToken 可以是任意代币：如果桥不支持转移某种代币，就会先在源网络上兑换，或在目标网络到账时购买（此时 toAmountMin 是该兑换的最低金额；如果价格变动超出该金额，收款人就会收到桥接代币，例如 USDC）。仍然只需一笔交易，费用仅收取一次。文档：https://soheil.fi/developers/docs/bridging/

通过 AI 助手使用（MCP）

该 API 也提供 MCP 服务（Streamable HTTP），包含 get_networks、get_api_info、get_quote 和 get_trade_status 工具。

claude mcp add --transport http soheil-router https://api.soheil.fi/v1/mcp \
  --header "Authorization: Bearer $SOHEIL_ROUTER_KEY"

{ "mcpServers": { "soheil-router": { "url": "https://api.soheil.fi/v1/mcp", "headers": { "Authorization": "Bearer sk_your_key" } } } }

需要了解的信息

• 金额是以代币最小单位表示的整数字符串；请使用 bigint，切勿使用 JavaScript 数字。
• 仅授权 fromAmount 的准确金额，切勿授权无限额度。
• 用户始终在自己的钱包中签署交易：API 从不持有密钥或资金。

由 Soheil.fi 构建。问题请联系：[email protected]

许可证

MIT