API Integration

倾向于显式编写多步 flow？ 参见 Composer API，它记录了显式的 Flow 编写 API。

本指南带你直接通过 LI.FI REST API 集成 Composer。这种方式让你对请求/响应流程拥有完全控制，非常适合后端服务、自定义前端，或任何你希望自行管理交易的环境。

已经在使用 LI.FI SDK 或 Widget？ Composer 会自动生效。请改为参见 SDK 指南或 Widget 指南。

Authentication

LI.FI API 是开放的，无需 API key。你可以立即开始发起请求。

integrator（可选查询参数）：一个在分析与链上事件中标识你应用的字符串。省略时默认为 "lifi-api"。必须为字母数字，可含连字符、下划线或点，最长 23 个字符。
x-lifi-api-key（可选头）：当你在 LI.FI 合作伙伴门户中创建集成时会自动生成一个 API key。附上它可获得更高的速率限制。没有 key 时，适用未认证限制：/quote 与 /advanced/routes 每两小时 75 次请求，/advanced/stepTransaction 每两小时 50 次请求，其他端点每分钟 100 次请求。有 API key 时，所有端点默认为每分钟 100 次请求。

完整细节参见 Authentication。

Overview

Composer 不需要专用端点。将 toToken 设置为受支持的协议代币地址，LI.FI 便会从标准端点返回一条 Composer 路由。集成流程：

请求报价，通过 GET /v1/quote 或 POST /v1/advanced/routes
设置代币授权，即授权 LI.FI Diamond 合约花费你的代币
发送交易，使用报价响应中的 transactionRequest
跟踪状态，对跨链转移轮询 GET /v1/status

Request a Composer Quote

Using `GET /quote` (Recommended)

获取 Composer 交易的最简单方式。返回单个最优路由，并包含交易数据。

curl -X GET 'https://li.quest/v1/quote?fromChain=8453&toChain=8453&fromToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&toToken=0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A&fromAddress=0xYOUR_WALLET_ADDRESS&toAddress=0xYOUR_WALLET_ADDRESS&fromAmount=1000000'

import axios from 'axios';

const getQuote = async (params: {
  fromChain: number;
  toChain: number;
  fromToken: string;
  toToken: string;
  fromAmount: string;
  fromAddress: string;
  slippage?: number;
  integrator?: string;
}) => {
  const result = await axios.get('https://li.quest/v1/quote', {
    params: {
      ...params,
      toAddress: params.fromAddress,
    },
  });
  return result.data;
};

const quote = await getQuote({
  fromChain: 8453,                                              // Base
  toChain: 8453,                                                // Base (same-chain)
  fromToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',     // USDC on Base
  toToken: '0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A',       // Morpho vault token
  fromAmount: '1000000',                                        // 1 USDC (6 decimals)
  fromAddress: '0xYOUR_WALLET_ADDRESS',
  slippage: 0.005,                                              // 0.5% slippage tolerance
  integrator: 'your-app-name',
});

import requests

response = requests.get('https://li.quest/v1/quote', params={
    'fromChain': 8453,
    'toChain': 8453,
    'fromToken': '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    'toToken': '0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A',
    'fromAmount': '1000000',
    'fromAddress': '0xYOUR_WALLET_ADDRESS',
    'toAddress': '0xYOUR_WALLET_ADDRESS',
    'slippage': 0.005,
    'integrator': 'your-app-name',
})

quote = response.json()

Slippage

slippage 参数是一个小数值，表示可接受的最大价格差异。例如，0.005 表示 0.5%。若省略，API 默认为 0.005。跨链路由涉及更多步骤，因此对跨链 flow 可考虑 0.01（1%）或更高。

Value	Meaning
`0.005`	0.5%（默认）
`0.01`	1%
`0.03`	3%

Using `POST /advanced/routes`

返回多个路由选项。当你想向用户呈现选择，或需要对路由选择有更多控制时很有用。

const getRoutes = async (params: {
  fromChainId: number;
  toChainId: number;
  fromTokenAddress: string;
  toTokenAddress: string;
  fromAmount: string;
  fromAddress: string;
}) => {
  const result = await axios.post('https://li.quest/v1/advanced/routes', {
    ...params,
    toAddress: params.fromAddress,
  });
  return result.data;
};

const routesResponse = await getRoutes({
  fromChainId: 8453,
  toChainId: 8453,
  fromTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  toTokenAddress: '0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A',
  fromAmount: '1000000',
  fromAddress: '0xYOUR_WALLET_ADDRESS',
});

// Select the best route
const route = routesResponse.routes[0];

使用 /advanced/routes 时，交易数据不包含在响应中。你必须调用 POST /v1/advanced/stepTransaction 来为每个步骤获取 transactionRequest。使用 /quote 时，交易数据直接包含在内。

Getting transaction data for a route step

TypeScript

const getStepTransaction = async (step: any) => {
  const result = await axios.post('https://li.quest/v1/advanced/stepTransaction', step);
  return result.data;
};

const route = routesResponse.routes[0];
const stepWithTx = await getStepTransaction(route.steps[0]);
// stepWithTx.transactionRequest now contains the ready-to-sign transaction

如需详细对比，参见 Difference between Quote and Route。

Quote Response Structure

Composer 报价响应包含路由细节、预估输出以及一笔可直接签名的交易。以下是关键字段：

显示 Example response (annotated)

{
  "id": "0x...",
  "type": "lifi",
  "tool": "composer",
  "toolDetails": {
    "key": "composer",
    "name": "Composer",
    "logoURI": "https://..."
  },
  "action": {
    "fromToken": {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "symbol": "USDC",
      "decimals": 6,
      "chainId": 8453
    },
    "toToken": {
      "address": "0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A",
      "symbol": "sparkUSDC",
      "decimals": 18,
      "chainId": 8453
    },
    "fromAmount": "1000000",
    "fromChainId": 8453,
    "toChainId": 8453,
    "slippage": 0.005
  },
  "estimate": {
    "toAmount": "946832715862427",
    "toAmountMin": "942098552283115",
    "approvalAddress": "0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE",
    "executionDuration": 0,
    "feeCosts": [...],
    "gasCosts": [...]
  },
  "integrator": "lifi-api",
  "transactionRequest": {
    "to": "0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE",
    "data": "0x...",
    "value": "0x0",
    "gasLimit": "0x5f45bc",
    "gasPrice": "0x1b0875",
    "chainId": 8453,
    "from": "0xYOUR_WALLET_ADDRESS"
  },
  "includedSteps": [
    {
      "type": "protocol",
      "tool": "feeCollection",
      "toolDetails": { "key": "feeCollection", "name": "Integrator Fee" },
      "action": {...},
      "estimate": {...}
    },
    {
      "type": "protocol",
      "tool": "composer",
      "toolDetails": { "key": "composer", "name": "Composer" },
      "action": {...},
      "estimate": {...}
    }
  ]
}

Key fields

Field	Description
`tool`	同链 Composer 路由为 `"composer"`。对于跨链路由，这是桥接的名称（例如 `"stargateV2"`）。检查 `includedSteps` 中是否有 `tool: "composer"` 以确认路由中含有 Composer。
`action.fromToken` / `action.toToken`	带有 `address`、`symbol`、`decimals` 与 `chainId` 的代币对象。
`action.slippage`	应用于此报价的滑点容差。
`estimate.toAmount`	以 `toToken` 最小单位计的预估输出。
`estimate.toAmountMin`	计入滑点后的最小输出。
`estimate.approvalAddress`	需要授权其花费代币的合约地址（见下文）。
`estimate.executionDuration`	以秒计的预估执行时间。
`transactionRequest`	可直接签名的 EVM 交易。字段（`value`、`gasLimit`、`gasPrice`）为十六进制编码字符串。
`estimate.feeCosts`	费用条目数组。每条 Composer 路由都包含一个 `feeCollection` 步骤，收取一小笔百分比费用。检查此数组以向用户呈现费用详情。
`includedSteps`	路由将执行的有序步骤列表。通常包含一个 `feeCollection` 步骤，其后是 `composer` 步骤。

十六进制编码值： transactionRequest 的 value、gasLimit 与 gasPrice 字段为十六进制字符串（例如 "0x5f45bc"）。chainId 字段是普通数字。手动构建交易时（例如在 Python 中），用 int(value, 16) 解析十六进制字段。

Contract addresses

estimate.approvalAddress 与 transactionRequest.to 都指向 LI.FI Diamond 合约，这是一份部署在所有受支持链上的、经过验证和审计的智能合约。

Chain	LI.FI Diamond Address
All EVM chains	`0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE`

Composer 链上 VM（执行编译后字节码者）是一份由 Diamond 在内部调用的独立合约。如需审计报告与合约验证，参见 Security and Audits。

报价反映当前市场状况，可能会过期。如果用户查看某个报价超过 30 秒，请在签名前重新获取，以取得最新的定价与模拟结果。

Morpho vault naming

Morpho vault 以其**策展人（curator）**命名，而非以 Morpho 本身命名。例如，地址 0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A 返回 symbol: "sparkUSDC"，因为它是一个由 Spark 策展的 Morpho vault。这是预期行为：Morpho 提供 vault 基础设施，而像 Spark 这样的策展人在其上创建策略。

Set Token Allowance

执行之前，LI.FI Diamond 合约需要获得授权以花费你的代币。授权地址在报价响应的 estimate.approvalAddress 中返回。

如果 fromToken 是原生代币（例如 ETH），跳过此步骤。原生代币无需授权。

本指南面向后端/服务端签名，因此假定 walletClient 是用本地账户创建的（例如通过 privateKeyToAccount），这使 walletClient.account 始终有定义。如果你驱动的是浏览器注入的钱包，请用 walletClient.getAddresses()（或 requestAddresses()）而非 walletClient.account 来解析地址。

import { erc20Abi, zeroAddress, type Address } from 'viem';
import type { Account, Chain, PublicClient, Transport, WalletClient } from 'viem';

const ensureAllowance = async (
  publicClient: PublicClient,
  walletClient: WalletClient<Transport, Chain | undefined, Account>,
  tokenAddress: Address,
  approvalAddress: Address,
  amount: bigint
) => {
  if (tokenAddress === zeroAddress) return; // Native token

  const currentAllowance = await publicClient.readContract({
    address: tokenAddress,
    abi: erc20Abi,
    functionName: 'allowance',
    args: [walletClient.account.address, approvalAddress],
  });

  if (currentAllowance < amount) {
    const hash = await walletClient.writeContract({
      address: tokenAddress,
      abi: erc20Abi,
      functionName: 'approve',
      args: [approvalAddress, amount],
      account: walletClient.account,
      chain: walletClient.chain,
    });
    await publicClient.waitForTransactionReceipt({ hash });
  }
};

await ensureAllowance(
  publicClient,
  walletClient,
  quote.action.fromToken.address as Address,
  quote.estimate.approvalAddress as Address,
  BigInt(quote.action.fromAmount)
);

from web3 import Web3

ERC20_ABI = [
    {
        "name": "approve",
        "type": "function",
        "inputs": [
            {"name": "spender", "type": "address"},
            {"name": "amount", "type": "uint256"}
        ],
        "outputs": [{"name": "", "type": "bool"}]
    },
    {
        "name": "allowance",
        "type": "function",
        "inputs": [
            {"name": "owner", "type": "address"},
            {"name": "spender", "type": "address"}
        ],
        "outputs": [{"name": "", "type": "uint256"}]
    }
]

def ensure_allowance(w3, account, token_address, approval_address, amount):
    token = w3.eth.contract(address=token_address, abi=ERC20_ABI)
    current = token.functions.allowance(account.address, approval_address).call()

    if current < int(amount):
        tx = token.functions.approve(approval_address, int(amount)).build_transaction({
            'from': account.address,
            'nonce': w3.eth.get_transaction_count(account.address),
        })
        signed = account.sign_transaction(tx)
        tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
        w3.eth.wait_for_transaction_receipt(tx_hash)

ensure_allowance(
    w3,
    account,
    quote['action']['fromToken']['address'],
    quote['estimate']['approvalAddress'],
    quote['action']['fromAmount']
)

如果发送了授权交易，请在执行前重新获取报价。transactionRequest 包含 gas 预估，可能在授权确认时已过期。用相同参数再次调用 GET /v1/quote，并使用新的 transactionRequest。

Send the Transaction

提交报价响应中的 transactionRequest。这是一笔标准的 EVM 交易。

import { type Address, type Hex } from 'viem';

const hash = await walletClient.sendTransaction({
  account: walletClient.account,
  to: quote.transactionRequest.to as Address,
  data: quote.transactionRequest.data as Hex,
  value: BigInt(quote.transactionRequest.value),
  gas: BigInt(quote.transactionRequest.gasLimit),
  gasPrice: BigInt(quote.transactionRequest.gasPrice),
  chain: walletClient.chain,
});
console.log('Transaction hash:', hash);

const receipt = await publicClient.waitForTransactionReceipt({ hash });
console.log('Confirmed in block:', receipt.blockNumber);

tx = {
    'to': quote['transactionRequest']['to'],
    'data': quote['transactionRequest']['data'],
    'value': int(quote['transactionRequest']['value'], 16),
    'gas': int(quote['transactionRequest']['gasLimit'], 16),
    'gasPrice': int(quote['transactionRequest']['gasPrice'], 16),
    'nonce': w3.eth.get_transaction_count(account.address),
    'chainId': int(quote['transactionRequest']['chainId']),
}

signed = account.sign_transaction(tx)
tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
print(f"Confirmed: {receipt['transactionHash'].to_0x_hex()}")

Track Status

对于同链 Composer 交易，一旦交易确认，操作即完成。对于跨链 Composer flow，轮询 /status 端点直到转移完成：

const getStatus = async (txHash: string, fromChain: number, toChain: number) => {
  const result = await axios.get('https://li.quest/v1/status', {
    params: { txHash, fromChain, toChain },
  });
  return result.data;
};

const pollStatus = async (txHash: string, fromChain: number, toChain: number) => {
  let status;
  do {
    status = await getStatus(txHash, fromChain, toChain);
    console.log(`Status: ${status.status} (${status.substatus || ''})`);

    if (status.status !== 'DONE' && status.status !== 'FAILED') {
      await new Promise((r) => setTimeout(r, 5000));
    }
  } while (status.status !== 'DONE' && status.status !== 'FAILED');

  return status;
};

// Only needed for cross-chain
if (quote.action.fromChainId !== quote.action.toChainId) {
  const finalStatus = await pollStatus(
    tx.hash,
    quote.action.fromChainId,
    quote.action.toChainId
  );
  console.log('Final:', finalStatus.status);
}

如需包含 substatus 值在内的完整状态参考，参见 Transaction Status Tracking。

Error Handling

使用 Composer 时的常见错误：

Error	Cause	Resolution
`No routes found`	vault 代币不受支持或流动性不足	核实 vault 代币地址正确，且该协议受支持
`Simulation failed`	Composer 执行在链上会失败	检查代币余额、授权，以及该 vault 是否正在接受存入
`Insufficient allowance`	代币授权未设置或过低	用正确的 `approvalAddress` 与金额调用 `approve()`

如需完整错误参考，参见 Error Codes。

Next Steps

Cross-Chain Patterns

高级跨链 Composer flow 与模式

Withdrawals Guide

实现同链与跨链取出

Vault Deposit Recipes

Morpho、Aave、Euler 等的可复制粘贴 recipe

SDK Integration

带有钩子、事件与自动重试的托管式执行

Supported Protocols

受支持协议与能力的完整列表

简介

通过 Composer API 集成

通过 LI.FI API 集成

资源

API Integration

Authentication

Overview

Request a Composer Quote

Using `GET /quote` (Recommended)

Slippage

Using `POST /advanced/routes`

Getting transaction data for a route step

Quote Response Structure

Key fields

Contract addresses

Morpho vault naming

Set Token Allowance

Send the Transaction

Track Status

Error Handling

Next Steps

Cross-Chain Patterns

Withdrawals Guide

Vault Deposit Recipes

SDK Integration

Supported Protocols

​Authentication

​Overview

​Request a Composer Quote

​Using GET /quote (Recommended)

​Slippage

​Using POST /advanced/routes

​Getting transaction data for a route step

​Quote Response Structure

​Key fields

​Contract addresses

​Morpho vault naming

​Set Token Allowance

​Send the Transaction

​Track Status

​Error Handling

​Next Steps

Cross-Chain Patterns

Withdrawals Guide

Vault Deposit Recipes

SDK Integration

Supported Protocols

Authentication

Overview

Request a Composer Quote

Using `GET /quote` (Recommended)

Slippage

Using `POST /advanced/routes`

Getting transaction data for a route step

Quote Response Structure

Key fields

Contract addresses

Morpho vault naming

Set Token Allowance

Send the Transaction

Track Status

Error Handling

Next Steps