SDK 集成

LI.FI SDK 处理完整的 Composer 生命周期（授权检查、链切换、交易提交和状态跟踪），让您可以专注于应用逻辑。本指南展示如何通过 SDK 使用 Composer。

先决条件： 您应该已经安装并配置了 LI.FI SDK。如果没有，请参见安装 SDK 和配置 SDK。

快速示例

使用 SDK 将 USDC 存入 Base 上的 Morpho 金库：

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

// 1. 配置 SDK（在应用启动时一次）
createConfig({
  integrator: 'YourAppName',
});

// 2. 获取 Composer 报价
const quote = await getQuote({
  fromChain: 8453,                                              // Base
  toChain: 8453,                                                // Base
  fromToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',     // Base 上的 USDC
  toToken: '0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A',       // Morpho 金库代币
  fromAmount: '1000000',                                        // 1 USDC
  fromAddress: '0xYOUR_WALLET_ADDRESS',
});

// 3. 转换报价为路由并执行 - SDK 处理授权、提交和跟踪
const route = convertQuoteToRoute(quote);
const executedRoute = await executeRoute(route, {
  updateRouteHook(updatedRoute) {
    console.log('路由已更新：', updatedRoute);
  },
});

console.log('完成！', executedRoute);

就这样。SDK 内部管理：

授权检查和批准
交易数据检索（如果使用 /advanced/routes）
交易提交
状态跟踪和轮询
链切换（用于跨链流程）

分步指南

1. 配置 SDK

在应用启动时设置 SDK 一次。您必须为您想使用的链配置 EVM 提供者。

import { createConfig } from '@lifi/sdk';
import { createWalletClient, http } from 'viem';
import { base } from 'viem/chains';

createConfig({
  integrator: 'YourAppName',
  providers: [
    // 配置您的 EVM 提供者 - 完整设置请参见 SDK 文档
  ],
});

完整的提供者配置，请参见配置 SDK 提供者。

2. 请求 Composer 报价

使用 getQuote 获取单个最佳路由（包含交易数据）或 getRoutes 获取多个选项。

使用 `getQuote`

import { getQuote } from '@lifi/sdk';

const quote = await getQuote({
  fromChain: 8453,
  toChain: 8453,
  fromToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  toToken: '0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A',
  fromAmount: '1000000',
  fromAddress: '0xYOUR_WALLET_ADDRESS',
});

使用 `getRoutes`

import { getRoutes } from '@lifi/sdk';

const routes = await getRoutes({
  fromChain: 8453,
  toChain: 8453,
  fromToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  toToken: '0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A',
  fromAmount: '1000000',
  fromAddress: '0xYOUR_WALLET_ADDRESS',
});

// 选择最佳路由
const selectedRoute = routes.routes[0];

3. 转换并执行路由

SDK 提供了 convertQuoteToRoute 和 executeRoute 函数来处理整个执行流程。

import { convertQuoteToRoute, executeRoute } from '@lifi/sdk';

// 如果使用 getQuote
const route = convertQuoteToRoute(quote);

// 如果使用 getRoutes，直接使用选定的路由
const route = selectedRoute;

// 执行路由
const executedRoute = await executeRoute(route, {
  // 可选钩子
  updateRouteHook(updatedRoute) {
    console.log('路由更新：', updatedRoute);
  },
  onChainSwitch(chainId) {
    console.log('切换到链：', chainId);
  },
});

4. 处理执行事件

SDK 发出事件来跟踪执行进度：

const executedRoute = await executeRoute(route, {
  updateRouteHook(updatedRoute) {
    console.log('路由更新：', updatedRoute);
  },
  onChainSwitch(chainId) {
    console.log('切换到链：', chainId);
  },
  gasCosts: (gasCosts) => {
    console.log('Gas 成本：', gasCosts);
  },
});

console.log('执行完成：', executedRoute);

跨链 Composer

SDK 自动处理跨链 Composer 流程的复杂性：

const crossChainQuote = await getQuote({
  fromChain: 1,                                                 // Ethereum
  toChain: 8453,                                                // Base
  fromToken: '0x0000000000000000000000000000000000000000',       // ETH (原生)
  toToken: '0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A',       // Morpho 金库代币
  fromAmount: '100000000000000000',                             // 0.1 ETH
  fromAddress: '0xYOUR_WALLET_ADDRESS',
});

const route = convertQuoteToRoute(crossChainQuote);
const executedRoute = await executeRoute(route);

// SDK 自动处理：
// - 源链交易（兑换 + 跨链）
// - 等待跨链完成
// - 目标链交易（Composer 存款）
// - 状态跟踪

错误处理

SDK 提供结构化错误处理：

import { LiFiErrorCode } from '@lifi/sdk';

try {
  const executedRoute = await executeRoute(route);
} catch (error) {
  if (error.code === LiFiErrorCode.TransactionFailed) {
    console.error('交易失败：', error.message);
  } else if (error.code === LiFiErrorCode.InsufficientBalance) {
    console.error('余额不足');
  } else if (error.code === LiFiErrorCode.GasLimitChanged) {
    console.error('Gas 限制已更改，请重试');
  }
}

高级配置

自定义提供者

为不同链配置特定提供者：

import { createConfig } from '@lifi/sdk';
import { createWalletClient, http } from 'viem';
import { mainnet, base, arbitrum } from 'viem/chains';

createConfig({
  integrator: 'YourAppName',
  providers: [
    createWalletClient({
      chain: mainnet,
      transport: http('https://mainnet.infura.io/v3/YOUR_PROJECT_ID'),
      account: 'YOUR_WALLET_ADDRESS',
    }),
    createWalletClient({
      chain: base,
      transport: http('https://mainnet.base.org'),
      account: 'YOUR_WALLET_ADDRESS',
    }),
    createWalletClient({
      chain: arbitrum,
      transport: http('https://arbitrum.infura.io/v3/YOUR_PROJECT_ID'),
      account: 'YOUR_WALLET_ADDRESS',
    }),
  ],
});

执行选项

自定义执行行为：

const executedRoute = await executeRoute(route, {
  // 控制执行
  executeInBackground: false,  // 在前台执行
  
  // 钩子
  updateRouteHook(updatedRoute) {
    // 路由更新时的回调
  },
  onChainSwitch(chainId) {
    // 链切换时的回调
  },
  
  // 选项
  gasCosts: (gasCosts) => {
    // Gas 成本估算
  },
  infiniteApproval: true,  // 无限授权
});

完整示例

这是一个完整的 Composer SDK 集成示例：

import { 
  createConfig, 
  getQuote, 
  convertQuoteToRoute, 
  executeRoute,
  LiFiErrorCode 
} from '@lifi/sdk';
import { createWalletClient, http } from 'viem';
import { base, mainnet } from 'viem/chains';

// 1. 配置 SDK
createConfig({
  integrator: 'YourAppName',
  providers: [
    createWalletClient({
      chain: base,
      transport: http('https://mainnet.base.org'),
      account: '0xYOUR_WALLET_ADDRESS',
    }),
    createWalletClient({
      chain: mainnet,
      transport: http('https://mainnet.infura.io/v3/YOUR_PROJECT_ID'),
      account: '0xYOUR_WALLET_ADDRESS',
    }),
  ],
});

// 2. Composer 执行函数
async function executeComposerDeposit() {
  try {
    // 获取报价
    const quote = await getQuote({
      fromChain: 1,                                                 // Ethereum
      toChain: 8453,                                                // Base
      fromToken: '0x0000000000000000000000000000000000000000',       // ETH
      toToken: '0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A',       // Morpho 金库
      fromAmount: '100000000000000000',                             // 0.1 ETH
      fromAddress: '0xYOUR_WALLET_ADDRESS',
    });

    console.log('收到报价，工具：', quote.tool);

    // 转换并执行
    const route = convertQuoteToRoute(quote);
    const executedRoute = await executeRoute(route, {
      updateRouteHook(updatedRoute) {
        console.log('路由更新：', updatedRoute.steps.length, '步骤');
      },
      onChainSwitch(chainId) {
        console.log('切换到链：', chainId);
      },
    });

    console.log('执行完成！');
    console.log('最终状态：', executedRoute.status);
    
  } catch (error) {
    console.error('执行失败：', error);
    
    if (error.code === LiFiErrorCode.TransactionFailed) {
      console.error('交易失败，请重试');
    } else if (error.code === LiFiErrorCode.InsufficientBalance) {
      console.error('余额不足');
    }
  }
}

// 执行
executeComposerDeposit();

下一步

API 集成

直接 REST API 集成

Widget 集成

使用 LI.FI Widget

跨链模式

跨链 Composer 流程

SDK 文档

完整 SDK 参考

入门指南

集成指南

配方示例

参考文档

协议团队

快速示例

分步指南

1. 配置 SDK

2. 请求 Composer 报价

使用 `getQuote`

使用 `getRoutes`

3. 转换并执行路由

4. 处理执行事件

跨链 Composer

错误处理

高级配置

自定义提供者

执行选项

完整示例

下一步

API 集成

Widget 集成

跨链模式

SDK 文档

入门指南

集成指南

配方示例

参考文档

协议团队

​快速示例

​分步指南

​1. 配置 SDK

​2. 请求 Composer 报价

​使用 getQuote

​使用 getRoutes

​3. 转换并执行路由

​4. 处理执行事件

​跨链 Composer

​错误处理

​高级配置

​自定义提供者

​执行选项

​完整示例

​下一步

API 集成

Widget 集成

跨链模式

SDK 文档

快速示例

分步指南

1. 配置 SDK

2. 请求 Composer 报价

使用 `getQuote`

使用 `getRoutes`

3. 转换并执行路由

4. 处理执行事件

跨链 Composer

错误处理

高级配置

自定义提供者

执行选项

完整示例

下一步