lifi

LI.FI 跨链集成指南

当 Solana 应用、钱包、后端或 AI Agent 需要跨链代币转账、桥聚合、同链兑换、支付流程或转账状态跟踪时，请使用 LI.FI。LI.FI 通过 REST API、SDK、MCP 服务、CLI 和 Widget 提供相同的路由引擎。

概述

LI.FI 是一个面向兑换和跨链桥接的多链流动性聚合平台。对于 Agent 和后端集成，REST API 是依赖最少的默认选择。对于前端应用，建议使用 SDK，因为它能处理钱包、签名、执行跟踪和特定生态系统的交易处理。对于兼容 MCP 的 AI 主机，建议使用 LI.FI MCP 服务进行类型化工具发现。

核心功能：

• 报价：获取一笔可直接签名的最佳路线交易。
• 路线：比较多个路线选项并逐步执行。
• 状态跟踪：跟踪源链和目标链上的转账进度。
• 发现：在运行时查询支持的链、代币、桥和交易所。
• Solana 支持：通过 chainTypes=SVM 请求 Solana 专属的链和代币数据，并在 API 示例中使用 SOL 作为 Solana 链标识。

产品界面选择

选择与任务相符的最精简界面：

• REST API：后端服务、脚本和通用 AI Agent。通过简单的 HTTP 调用，无需运行时依赖。
• SDK (@lifi/sdk)：前端或完整执行流程。可处理钱包连接器、签名、路线执行和更新钩子。
• MCP 服务：适用于 Claude、Cursor 或 Windsurf 等兼容 MCP 的 AI 主机。当支持类型化工具发现时使用。
• CLI：面向代币效率的 Agent 工作流；与原始 JSON 相比，更适合采用简洁易读的输出。
• Widget：当用户需要嵌入式兑换/跨链桥接体验，而非自定义集成时，使用现成的 UI。

不要强行让每种集成都通过 SDK 实现。对于报价查询、路线比较或状态检查，API 往往更简单，也更便于审计。

基础 URL 和身份验证

Production API: https://li.quest/v1
Staging API:    https://staging.li.quest/v1
Docs:           https://docs.li.fi
OpenAPI:        https://docs.li.fi/openapi.yaml
LLM overview:   https://docs.li.fi/llms.txt

LI.FI API 无需 API 密钥即可使用。若需提高速率限制或使用经过身份验证的合作伙伴功能，请使用 API 密钥。请在 LI.FI Partner Portal 注册集成以获取 API 密钥：https://portal.li.fi/

对于直接 REST 调用，请在 x-lifi-api-key 标头中传入密钥：

curl 'https://li.quest/v1/chains?chainTypes=EVM,SVM' \
  --header 'accept: application/json' \
  --header 'x-lifi-api-key: YOUR_API_KEY_IF_AVAILABLE'

在生产环境中使用之前，请在服务端测试密钥：

curl 'https://li.quest/v1/keys/test' \
  --header 'x-lifi-api-key: YOUR_API_KEY'

切勿在浏览器代码、公开代码仓库或 Widget 直接配置中暴露 x-lifi-api-key。如果在后端或可信运行时中使用 SDK，请通过 createConfig({ apiKey: '...' }) 传入密钥；如果在前端使用 Widget，请勿传入 API 密钥。

集成工作流

1. 明确转账意图

   • 源链、目标链、源代币、目标代币。
   • 以代币最小单位表示的金额。
   • 发送方地址，以及在不同的情况下提供接收方地址。
   • 用户希望获取单个最佳路线，还是比较多条路线。

2. 查询支持情况，而不是写死配置

   • 使用 /chains 验证链。
   • 使用 /tokens 或 /token 验证代币地址和小数位数。
   • 使用 /tools 列出当前支持的桥和交易所。
   • 不要假设所有代币、桥或链对都可用。

3. 选择报价还是路线

   • 对于只需获取最佳可执行路线的简单转账，使用 GET /quote。
   • 当需要比较方案，或用户要求选择路线、了解成本、速度、工具允许列表或多个步骤时，使用 POST /advanced/routes。
   • 执行高级路线时，使用 POST /advanced/stepTransaction 为各个路线步骤填充交易数据。

4. 向用户说明他们将要签署的内容

   • 总结源链、目标链、源代币、目标代币、金额、预估输出、工具/桥、费用、接收方和滑点。
   • 切勿要求用户在没有易读摘要的情况下签署不透明的交易数据。

5. 通过相应的钱包路径执行

   • 使用 GET /quote 时，响应中已包含 transactionRequest；处理好授权/许可后，使用源链钱包提交该交易。
   • 使用 POST /advanced/routes 时，先选择路线，再使用 POST /advanced/stepTransaction 为每个步骤填充数据，然后执行。
   • EVM 交易请求通常包含 to、data、value 和 gas 相关字段。
   • 源自 Solana 的转账会将 Solana 交易数据以 base64 格式返回在 transactionRequest.data 中；请对其反序列化、签名，并通过用户的 Solana 钱包或 SDK 路径发送。
   • 对于生产环境中的多步骤执行，优先使用 SDK executeRoute，因为它会处理授权和余额检查、链切换、交易数据获取、交易提交及状态跟踪。
   • 收到 LI.FI 返回的数据后，切勿修改 transactionRequest.data、calldata、接收方、退款信息、memo 或特定桥的载荷。

6. 提交源链交易后跟踪状态

   • 每隔 10-30 秒轮询 /status，直到状态进入终止状态。
   • 如果报价中有 fromChain、toChain 和 bridge，请一并提供，以加快查询。
   • 源链确认仅代表跨链转账开始，并不能证明最终交付已完成。

最小端点集合

获取报价

用于获取单个最佳路线及其交易数据。

curl --request GET \
  --url 'https://li.quest/v1/quote?fromChain=ARB&toChain=SOL&fromToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&toToken=7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs&fromAddress=YOUR_EVM_WALLET&toAddress=YOUR_SOL_WALLET&fromAmount=1000000000' \
  --header 'accept: application/json'

必需参数：

• fromChain：源链 ID 或键。
• toChain：目标链 ID 或键。
• fromToken：源代币符号或地址。
• toToken：目标代币符号或地址。
• fromAmount：以最小单位表示的金额。
• fromAddress：发送方钱包地址。
• toAddress：接收方钱包地址；当其与发送方不同时，或跨生态系统桥接时必填。

获取多条路线

当用户要求比较路线，或应用需要选择路线时使用。

curl --request POST \
  --url 'https://li.quest/v1/advanced/routes' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "fromChainId": "ARB",
    "toChainId": "SOL",
    "fromTokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "toTokenAddress": "7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs",
    "fromAmount": "1000000000",
    "fromAddress": "YOUR_EVM_WALLET",
    "toAddress": "YOUR_SOL_WALLET"
  }'

检查转账状态

curl --request GET \
  --url 'https://li.quest/v1/status?txHash=SOURCE_TX_HASH&fromChain=ARB&toChain=SOL&bridge=BRIDGE_KEY' \
  --header 'accept: application/json'

状态处理：

• NOT_FOUND：交易可能尚未被索引或挖出。如果已知 fromChain 和桥，请使用它们重试。
• PENDING：继续轮询。
• DONE + COMPLETED：最终交付成功。
• DONE + PARTIAL：操作成功，但输出代币可能不同，同时保留价值语义。
• DONE + REFUNDED：转账失败，但资金已退款。
• FAILED：停止轮询并显示错误/子状态。

列出支持的链

curl --request GET \
  --url 'https://li.quest/v1/chains?chainTypes=EVM,SVM' \
  --header 'accept: application/json'

仅限 Solana：

curl --request GET \
  --url 'https://li.quest/v1/chains?chainTypes=SVM' \
  --header 'accept: application/json'

列出 Solana 代币

curl --request GET \
  --url 'https://li.quest/v1/tokens?chains=SOL&chainTypes=SVM' \
  --header 'accept: application/json'

列出桥和交易所

curl --request GET \
  --url 'https://li.quest/v1/tools' \
  --header 'accept: application/json'

Solana 专属指南

只要转账任一端是 Solana，就使用本节指南。

• 查询 Solana 链支持情况时，使用 chainTypes=SVM。
• 在 API 示例中，使用 SOL 作为 Solana 链的键。
• 从 EVM 链桥接到 Solana 时，始终传入 Solana toAddress；发送方的 EVM 地址不是有效的 Solana 收款地址。
• 对于 SOL -> EVM 转账，transactionRequest.data 中应包含经 base64 编码的 Solana 交易数据，而非 EVM calldata。
• 使用 Solana 钱包适配器或 LI.FI SDK 反序列化、签名并提交 Solana 交易。除非确切流程的文档要求，否则不要手动重建交易。
• 通过 /tokens 或 /token 验证代币精度；不要假设同一代币的 EVM 和 Solana 版本具有相同的精度或地址。
• 如果状态查询较慢，请传入源交易哈希，以及报价中的 fromChain、toChain 和桥接/工具键。

执行模式

直接 API 执行

当你自行控制钱包/提供程序层时，使用直接 API 执行。/quote 会立即返回可执行的交易数据；/advanced/routes 会返回路线选项，并要求对每个选定步骤调用 POST /advanced/stepTransaction。

对于源链为 EVM 的报价，典型流程如下：

1. 当源代币不是原生代币时，检查 quote.estimate.approvalAddress 的代币授权额度。
2. 提交授权，或在所选流程需要时使用 Permit/Permit2。
3. 通过 EVM 钱包发送 quote.transactionRequest。
4. 使用源交易哈希、quote.tool、源链和目标链轮询 /status。

对于源链为 Solana 的报价，不要将 transactionRequest.data 视为 calldata。它是经 base64 编码的 Solana 交易数据；请使用 SDK 或 Solana 钱包适配器/web3.js 路径对其进行反序列化、签名并提交。

SDK 执行

构建前端，或当 Agent 需要完整的路线执行能力而不只是查询报价/状态时，优先使用 SDK。截至 @lifi/[email protected]，@lifi/sdk 导出了 createConfig、getQuote、getRoutes、executeRoute、EVM、Solana 和 KeypairWalletAdapter。

npm install @lifi/sdk

仅查询报价：

import { createConfig, getQuote } from '@lifi/sdk'

createConfig({
  integrator: 'YourAppName',
  // Backend/trusted runtime only. Do not expose this in browsers.
  apiKey: process.env.LIFI_API_KEY,
})

const quote = await getQuote({
  fromChain: 'ARB',
  toChain: 'SOL',
  fromToken: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
  toToken: '7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs',
  fromAmount: '1000000000',
  fromAddress: 'YOUR_EVM_WALLET',
  toAddress: 'YOUR_SOL_WALLET',
})

console.log(quote.estimate.toAmount, quote.tool, quote.transactionRequest)

使用 SDK 执行路线：

import { createConfig, EVM, executeRoute, getRoutes } from '@lifi/sdk'
import type { Chain } from 'viem'
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { arbitrum, mainnet, optimism } from 'viem/chains'

const privateKey = process.env.PRIVATE_KEY as `0x${string}` // backend/testing only
const account = privateKeyToAccount(privateKey)
const chains = [arbitrum, mainnet, optimism]

const client = createWalletClient({
  account,
  chain: arbitrum,
  transport: http(),
})

createConfig({
  integrator: 'YourAppName',
  providers: [
    EVM({
      getWalletClient: async () => client,
      switchChain: async (chainId) =>
        createWalletClient({
          account,
          chain: chains.find((chain) => chain.id === chainId) as Chain,
          transport: http(),
        }),
    }),
  ],
})

const result = await getRoutes({
  fromChainId: 42161,
  toChainId: 10,
  fromTokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
  toTokenAddress: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
  fromAmount: '10000000',
  fromAddress: 'YOUR_EVM_WALLET',
})

const executedRoute = await executeRoute(result.routes[0], {
  updateRouteHook(route) {
    console.log(route)
  },
  async acceptExchangeRateUpdateHook() {
    // In a UI, ask the user before accepting.
    return false
  },
})

console.log(executedRoute)

设置 Solana 提供程序：

import { createConfig, KeypairWalletAdapter, Solana } from '@lifi/sdk'

const walletAdapter = new KeypairWalletAdapter('PRIVATE_KEY') // backend/testing only

createConfig({
  integrator: 'YourAppName',
  providers: [
    Solana({
      getWalletAdapter: async () => walletAdapter,
    }),
  ],
})

对于面向用户的 Solana 应用，请使用 @solana/wallet-adapter-react，并在运行时根据已连接的钱包适配器设置 Solana({ getWalletAdapter })。不要在前端代码中嵌入私钥。

错误处理

同时处理 HTTP 状态码和 LI.FI API 错误码。

常见 API 错误码：

• 1002 NoQuoteError：未找到报价。请尝试其他代币、金额、目标地址或路线限制条件。
• 1005 RateLimitError：暂停后重试；如有可用的 API 密钥，请使用它以提高限额。
• 1007 SlippageError：增加滑点前先征求用户同意。
• 1008 ThirdPartyError：桥接/交易所/工具发生故障。请稍后重试，或请求其他路线。
• 1009 TimeoutError：采用退避策略重试，或通过比较路线寻找其他工具。
• 1011 ValidationError：检查链 ID、代币地址、金额单位和地址格式。
• 1012 RpcFailure：稍后重试，或在适用时通过 SDK 配置更可靠的 RPC。

常见工具错误码：

• NO_POSSIBLE_ROUTE：所请求操作没有受支持的路径。
• INSUFFICIENT_LIQUIDITY：减少金额，或选择其他代币/路径。
• TOOL_TIMEOUT：重试；如果 API 请求支持工具限制条件，则排除超时工具。
• AMOUNT_TOO_LOW / AMOUNT_TOO_HIGH：调整金额。
• FEES_HIGHER_THAN_AMOUNT：金额不具备经济性；请增加转账金额或选择其他路线。
• DIFFERENT_RECIPIENT_NOT_SUPPORTED：在要求的情况下使用相同的发送方/收款方，或选择其他工具。
• CANNOT_GUARANTEE_MIN_AMOUNT：说明风险，并在继续操作前征求用户同意。

指南

• 务必在提供集成建议前查询实时链、代币和工具。
• 务必使用 /quote 进行简单执行，使用 /advanced/routes 进行比较。
• 务必在签名前展示预估输出、费用、桥接／交易工具、接收方和滑点。
• 务必针对跨链转账轮询 /status，直至达到终止状态。
• 务必原样保留 LI.FI 返回的交易数据。
• 务必在需要更高速率限制时前往 LI.FI Partner Portal 注册以获取 API 密钥，并将密钥保留在服务端。
• 切勿硬编码过时的桥接列表、代币列表或链支持信息。
• 切勿将源链确认视为跨链转账已最终完成。
• 切勿在未经用户明确同意的情况下增加滑点、更改接收方或修改交易数据。
• 切勿存储或索取私钥。请使用钱包签名流程。
• 切勿在 API 或 SDK 更合适时，将 Widget 作为唯一集成方式。

常见错误

错误：未找到路由

**原因：**链／代币组合不受支持、流动性不足、金额过小或过大，或路由选项限制过严。

**解决方案：**检查 /chains、/tokens 和 /tools；尝试使用标准代币地址；调整金额；请求 /advanced/routes 获取替代方案。

错误：将 Solana 交易数据当作 EVM calldata 处理

**原因：**源链为 SOL 的报价会在 transactionRequest.data 中返回 base64 格式的 Solana 交易数据，而不是 EVM to/data/value 调用。

**解决方案：**使用 Solana 钱包／SDK 路径对交易进行反序列化、签名和提交。不要通过 EVM provider 发送该交易。

错误：状态端点返回 NOT_FOUND

**原因：**交易尚未编入索引、源交易哈希错误、缺少 fromChain，或桥接／工具筛选条件错误。

**解决方案：**采用退避策略重试，并根据报价传入 fromChain、toChain 和桥接工具。确认哈希是源链交易哈希。

错误：金额因小数位数而不正确

**原因：**金额未换算为源代币的最小单位，或在不同生态系统中错误假设了代币小数位数。

**解决方案：**从 /tokens 或 /token 获取代币元数据，并在请求报价前换算金额。

错误：不支持不同的接收方

**原因：**某些工具不支持将资产发送给与发送方不同的接收方。

**解决方案：**请求其他路由／工具，或在用户接受时使用相同的接收方。

参考资料

• Agent 集成概述：https://docs.li.fi/agents/overview
• Agent 概念和对象定义：https://docs.li.fi/agents/concepts
• 面向 LLM 的文档：https://docs.li.fi/llms.txt
• OpenAPI 规范：https://docs.li.fi/openapi.yaml
• 报价 API：https://docs.li.fi/api-reference/get-a-quote-for-a-token-transfer
• Routes API：https://docs.li.fi/api-reference/advanced/get-a-set-of-routes-for-a-request-that-describes-a-transfer-of-tokens
• Status API：https://docs.li.fi/api-reference/check-the-status-of-a-cross-chain-transfer
• Solana 交易执行：https://docs.li.fi/introduction/user-flows-and-examples/solana-tx-execution
• 错误代码：https://docs.li.fi/api-reference/error-codes
• API 简介和身份验证：https://docs.li.fi/api-reference/introduction
• 速率限制和 API 身份验证：https://docs.li.fi/api-reference/rate-limits
• 获取 API 密钥的 Partner Portal：https://portal.li.fi/
• SDK provider 配置：https://docs.li.fi/sdk/configure-sdk-providers
• SDK 路由请求：https://docs.li.fi/sdk/request-routes
• SDK 路由执行：https://docs.li.fi/sdk/execute-routes