li-fi-sdk — Инструменты для кросс-чейн и он-чейн свопов

--- name: li-fi-sdk description: | TypeScript/JavaScript SDK for cross-chain and same-chain token swaps, bridging, and DeFi operations. USE THIS SKILL TO: - Swap tokens between different blockchains (e.g., "swap USDC on Ethereum to ETH on Arbitrum") - Bridge tokens to another chain (e.g., "transfer my ETH from mainnet to Base") - Swap tokens on the same chain with best DEX rates (e.g., "swap ETH to DAI on Polygon") - Get quotes or compare routes for token swaps across any chains - Execute 1-click DeFi workflows (zap into LP, bridge+swap+deposit, cross-chain yield entry) - Build a dApp, wallet, or frontend that supports multi-chain token operations - Create payment flows that accept any token and convert to a specific token - Build React, Next.js, Vue, or Node.js apps with cross-chain swap functionality - Handle cross-chain transaction lifecycle (status tracking, retries, refunds) - Find available bridges, DEXs, chains, or tokens for cross-chain operations --- # LI.FI SDK Integration The LI.FI SDK (`@lifi/sdk`) is a TypeScript/JavaScript toolkit for cross-chain and on-chain swaps and bridging. It provides complete functionality from obtaining routes/quotes to executing transactions across 30+ blockchain networks. ## Installation ```bash # Using yarn yarn add @lifi/sdk # Using npm npm install @lifi/sdk # Using pnpm pnpm add @lifi/sdk # Using bun bun add @lifi/sdk ``` ## Quick Start ### 1. Configure the SDK ```typescript import { createConfig } from '@lifi/sdk'; createConfig({ integrator: 'YourAppName', // Required: identifies your application }); ``` ### 2. Request a Quote ```typescript import { getQuote } from '@lifi/sdk'; const quote = await getQuote({ fromChain: 42161, // Arbitrum toChain: 10, // Optimism fromToken: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', // USDC on Arbitrum toToken: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1', // DAI on Optimism fromAmount: '10000000', // 10 USDC (6 decimals) fromAddress: '0xYourWalletAddress', }); ``` ### 3. Execute the Transfer ```typescript import { executeRoute, convertQuoteToRoute } from '@lifi/sdk'; const route = convertQuoteToRoute(quote); const executedRoute = await executeRoute(route, { updateRouteHook(updatedRoute) { console.log('Route updated:', updatedRoute); }, }); ``` ## Core Concepts ### Routes vs Quotes - **`getQuote()`**: Returns single best option with transaction data ready. Use for simple transfers. - **`getRoutes()`**: Returns multiple options for comparison. Use when presenting choices to users. See [references/REFERENCE.md](references/REFERENCE.md) for chain IDs, token addresses, and parameter tables. ## SDK Configuration ### Basic Configuration ```typescript import { createConfig } from '@lifi/sdk'; createConfig({ integrator: 'YourAppName', apiKey: 'your-api-key', // Optional: for higher rate limits }); ``` ### Advanced Configuration ```typescript import { createConfig, ChainType } from '@lifi/sdk'; createConfig({ integrator: 'YourAppName', apiKey: 'your-api-key', rpcUrls: { 1: ['https://your-ethereum-rpc.com'], 137: ['https://your-polygon-rpc.com'], }, chains: { allow: [1, 10, 137, 42161], // Only allow specific chains }, preloadChains: true, // Preload chain data for faster initial requests }); ``` ## Requesting Routes and Quotes ### Get Multiple Routes ```typescript import { getRoutes, RoutesRequest } from '@lifi/sdk'; const routesRequest: RoutesRequest = { fromChainId: 42161, toChainId: 10, fromTokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', toTokenAddress: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1', fromAmount: '10000000', fromAddress: '0xYourAddress', // Optional for routes options: { slippage: 0.005, // 0.5% slippage order: 'CHEAPEST', // or 'FASTEST' }, }; const result = await getRoutes(routesRequest); const routes = result.routes; ``` ### Get Single Best Quote ```typescript import { getQuote, QuoteRequest } from '@lifi/sdk'; const quoteRequest: QuoteRequest = { fromChain: 42161, toChain: 10, fromToken: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', toToken: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1', fromAmount: '10000000', fromAddress: '0xYourAddress', // Required for quotes slippage: 0.005, }; const quote = await getQuote(quoteRequest); ``` ### Route Options ```typescript const options = { slippage: 0.005, // 0.5% slippage tolerance order: 'CHEAPEST', // 'CHEAPEST' or 'FASTEST' maxPriceImpact: 0.3, // Hide routes with >30% price impact allowSwitchChain: true, // Allow 2-step routes integrator: 'YourApp', fee: 0.03, // 3% integrator fee (requires verification) // Bridge/exchange preferences bridges: { allow: ['stargate', 'hop'], // Only use these bridges deny: ['multichain'], // Never use these bridges prefer: ['stargate'], // Prefer if available }, exchanges: { allow: ['1inch', 'uniswap'], deny: ['sushiswap'], }, }; ``` ## Executing Transactions ### Basic Execution ```typescript import { executeRoute } from '@lifi/sdk'; const executedRoute = await executeRoute(route, { updateRouteHook(updatedRoute) { // Called on every route state change console.log('Status:', updatedRoute.steps[0]?.execution?.status); }, }); ``` ### Execution with All Hooks ```typescript import { executeRoute } from '@lifi/sdk'; const executedRoute = await executeRoute(route, { // Track route updates updateRouteHook(updatedRoute) { const step = updatedRoute.steps[0]; const process = step?.execution?.process; const latestProcess = process?.[process.length - 1]; console.log('Status:', latestProcess?.status); console.log('TX Hash:', latestProcess?.txHash); }, // Handle exchange rate changes (important!) acceptExchangeRateUpdateHook(toToken, oldAmount, newAmount) { const oldValue = parseFloat(oldAmount); const newValue = parseFloat(newAmount); const percentChange = ((newValue - oldValue) / oldValue) * 100; // Accept if change is less than 2% if (Math.abs(percentChange) < 2) { return Promise.resolve(true); } // Prompt user for larger changes return promptUserToAccept(percentChange); }, // Handle chain switching (for 2-step routes) async switchChainHook(chainId) { await walletClient.switchChain({ id: chainId }); return walletClient; }, // Modify transaction before sending (advanced) async updateTransactionRequestHook(txRequest) { return { ...txRequest, gas: txRequest.gas ? BigInt(txRequest.gas) * 120n / 100n : undefined, }; }, }); ``` ### Execute a Quote ```typescript import { getQuote, convertQuoteToRoute, executeRoute } from '@lifi/sdk'; // Get quote const quote = await getQuote(quoteRequest); // Convert to route for execution const route = convertQuoteToRoute(quote); // Execute const result = await executeRoute(route); ``` ## Managing Execution Lifecycle ### Resume Interrupted Execution ```typescript import { resumeRoute } from '@lifi/sdk'; // Resume from the last saved route state const resumedRoute = await resumeRoute(savedRoute, { updateRouteHook(route) { console.log('Resumed execution:', route); }, }); ``` ### Background Execution ```typescript import { executeRoute, updateRouteExecution } from '@lifi/sdk'; // Start execution const routePromise = executeRoute(route, { updateRouteHook(route) { saveRouteState(route); // Persist state }, }); // Move to background (e.g., user navigates away) updateRouteExecution(route, { executeInBackground: true }); // Later: resume in foreground const resumedRoute = await resumeRoute(savedRoute, { executeInBackground: false, }); ``` ### Stop Execution ```typescript import { stopRouteExecution } from '@lifi/sdk'; // Stop execution (already-sent transactions will complete on-chain) const stoppedRoute = stopRouteExecution(route); ``` ### Get Active Routes ```typescript import { getActiveRoutes, getActiveRoute } from '@lifi/sdk'; // Get all active routes const activeRoutes = getActiveRoutes(); // Get specific active route const activeRoute = getActiveRoute(routeId); ``` ## Chain and Token Discovery ### Get Available Chains ```typescript import { getChains, ChainType } from '@lifi/sdk'; // Get all chains const allChains = await getChains(); // Get only EVM chains const evmChains = await getChains({ chainTypes: [ChainType.EVM] }); ``` ### Get Available Tokens ```typescript import { getTokens, getToken } from '@lifi/sdk'; // Get all tokens for a chain const tokens = await getTokens({ chains: [1, 137] }); // Get specific token const usdc = await getToken(1, '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'); ``` ### Get Available Tools (Bridges/DEXs) ```typescript import { getTools } from '@lifi/sdk'; const tools = await getTools(); console.log('Bridges:', tools.bridges); console.log('Exchanges:', tools.exchanges); ``` ### Get Connections ```typescript import { getConnections } from '@lifi/sdk'; // Find all possible routes from ETH on Ethereum const connections = await getConnections({ fromChain: 1, fromToken: '0x0000000000000000000000000000000000000000', // Native ETH }); ``` ## Multi-VM Provider Setup ### EVM Provider (Viem) ```typescript import { createConfig, EVM } from '@lifi/sdk'; import { createWalletClient, http } from 'viem'; import { mainnet } from 'viem/chains'; const walletClient = createWalletClient({ chain: mainnet, transport: http(), }); createConfig({ integrator: 'YourApp', providers: [ EVM({ getWalletClient: () => Promise.resolve(walletClient) }), ], }); ``` ### Solana Provider ```typescript import { createConfig, Solana } from '@lifi/sdk'; createConfig({ integrator: 'YourApp', providers: [ Solana({ getWalletAdapter: () => Promise.resolve(walletAdapter) }), ], }); ``` ## Contract Calls (Composer) Execute contract calls on the destination chain after bridging: ```typescript import { getContractCallsQuote } from '@lifi/sdk'; const contractCallQuote = await getContractCallsQuote({ fromAddress: '0xYourAddress', fromChain: 10, // Optimism fromToken: '0x0000000000000000000000000000000000000000', toAmount: '8500000000000', toChain: 8453, // Base toToken: '0x0000000000000000000000000000000000000000', contractCalls: [{ fromAmount: '8500000000000', fromTokenAddress: '0x0000000000000000000000000000000000000000', toContractAddress: '0xTargetContract', toContractCallData: '0x...', // Encoded function call toContractGasLimit: '210000', }], }); ``` ## Error Handling ```typescript import { executeRoute } from '@lifi/sdk'; try { const result = await executeRoute(route, { acceptExchangeRateUpdateHook: () => Promise.resolve(true), }); } catch (error) { if (error.message.includes('Exchange rate has changed')) { // Handle rate change rejection } else if (error.message.includes('insufficient funds')) { // Handle balance issues } else if (error.message.includes('user rejected')) { // Handle user cancellation } else { // Handle other errors console.error('Execution failed:', error); } } ``` ## Best Practices 1. **Always implement `acceptExchangeRateUpdateHook`** - Exchange rates can change during execution. Without this hook, execution fails on rate changes. 2. **Persist route state** - Use `updateRouteHook` to save route state for recovery after page refreshes or app restarts. 3. **Handle chain switching** - For cross-chain routes, implement `switchChainHook` to handle wallet chain switches. 4. **Use appropriate slippage** - Default 0.5% (0.005) works for most cases. Increase for volatile tokens or low-liquidity pairs. 5. **Set integrator name** - Always configure `integrator` for analytics and potential monetization. 6. **Check token allowances** - The SDK handles allowances automatically, but you may want to show approval UI to users. 7. **Monitor gas prices** - Use `updateTransactionRequestHook` to adjust gas if needed. See [references/REFERENCE.md](references/REFERENCE.md) for detailed parameter tables and TypeScript interfaces.