LI.FI SDK

The SDK is split into two main layers to optimize bundle size and maintain clean separation of concerns:

1. @lifi/sdk (Core SDK): Contains shared functionality, actions, and the central execution logic.
2. Provider Packages: Ecosystem-specific packages (e.g., @lifi/sdk-provider-ethereum) that handle wallet interactions and transaction execution for specific blockchain types.

This allows developers to install only the providers they need, reducing bundle size and allowing the use of ecosystem-specific libraries optimized for each blockchain.

To initialize the SDK, use createClient. You must provide an integrator string and an array of providers. Each provider is initialized with a configuration object that typically includes a function to retrieve a wallet or client (e.g., getWalletClient).

Example for EVM chains using viem:

import { createClient } from '@lifi/sdk'
import { EthereumProvider } from '@lifi/sdk-provider-ethereum'
import { createWalletClient, http } from 'viem'
import { mainnet } from 'viem/chains'

// You must construct your own wallet client
const walletClient = createWalletClient({
  account,
  chain: mainnet,
  transport: http(),
})

const client = createClient({
  integrator: 'Your dApp/company name',
  providers: [
    EthereumProvider({
      getWalletClient: () => Promise.resolve(walletClient),
    }),
  ],
})

Install the core SDK package which contains the shared functionality, actions, and execution logic. This is required for all implementations.

pnpm add @lifi/sdk
# or
npm install --save @lifi/sdk

The LI.FI SDK uses a modular architecture. You must install the specific provider packages for the blockchain ecosystems you want to support. Note that most providers require you to install the underlying ecosystem library alongside the provider so you can construct and pass the wallet/client objects yourself.

# EVM Chains (Ethereum, Polygon, Arbitrum, Optimism, etc.)
pnpm add @lifi/sdk-provider-ethereum viem

# Solana
pnpm add @lifi/sdk-provider-solana @wallet-standard/base

# Bitcoin
pnpm add @lifi/sdk-provider-bitcoin @bigmi/core

# Sui
pnpm add @lifi/sdk-provider-sui @mysten/sui

# Tron
pnpm add @lifi/sdk-provider-tron @tronweb3/tronwallet-abstract-adapter

# Stellar
pnpm add @lifi/sdk-provider-stellar

To run the example scripts in the lifi-sdk-node-sample directory, follow these steps:

1. Configure Environment Variables: Copy the template to a .env file and add your private key.

   cp .env-template .env

2. Install Dependencies: Use pnpm to install the required packages.

   pnpm install

3. Wallet Preparation: Ensure your wallet contains small amounts of tokens on the chains used in the examples (e.g., Optimism, Arbitrum, Polygon).

⚠️ Safety Warning: These examples execute REAL transactions on mainnet chains. Use a dedicated test wallet with minimal funds and review all route details before confirming.

Use pnpm to execute the E2E harness. By default, the command performs a dry run. To perform real swaps on mainnet, you must explicitly set the E2E_EXECUTE environment variable to true.

Safety Notes:

• Only E2E_EXECUTE=true triggers real swaps. Values like 1, yes, or TRUE are treated as dry runs.
• The standard pnpm test command excludes E2E spec files (**/*.e2e.spec.ts). To run all specs including E2E, you must use vitest --run.
• Legs run sequentially.
• MAX_SPEND_USD is checked against the total planned run at collection time, before any test execution begins.

# Dry run (no real money spent)
pnpm --filter @lifi/sdk-provider-solana test:e2e

# Real swaps (spends real money)
E2E_EXECUTE=true pnpm --filter @lifi/sdk-provider-solana test:e2e

The SDK tracks the progress of a transaction through an Execution object.

Execution Statuses:

• ACTION_REQUIRED: User intervention is needed (e.g., signing a permit).
• PENDING: The transaction is in progress.
• FAILED: The execution encountered an error.
• DONE: The execution completed successfully.

Execution Actions: An Execution contains an array of ExecutionAction objects. Each action has a type (e.g., SWAP, CROSS_CHAIN, PERMIT, CHECK_ALLOWANCE) and a status (e.g., STARTED, MESSAGE_REQUIRED, CANCELLED). Actions also provide metadata like txHash, txLink, and error details if they fail.

If you need to receive a specific amount of tokens on the destination chain, use getContractCallsQuote with the toAmount parameter. The SDK will automatically calculate the required input amount.

Key SDK features:

• getContractCallsQuote({ toAmount }): Performs a reverse quote calculation.
• Token allowance checking and setting.

Run command:

pnpm example:toAmount

For complex bridging scenarios involving multiple intermediate chains, use getContractCallsQuote to chain bridges and contract calls together. This pattern requires manual transaction execution and status polling.

Workflow:

1. Use getQuote() for single-step quotes.
2. Use getContractCallsQuote() to create a quote that includes destination contract calls (e.g., bridging to a chain AND executing a second bridge leg).
3. Manually send the transaction.
4. Use getStatus() to poll for the transaction status.

Run command:

pnpm example:multihop

The SDK allows you to execute arbitrary contract calls on the destination chain as part of a bridge transaction. This is useful for DeFi integrations like carbon offsetting or vault deposits.

Workflow:

1. Encode the target function call (e.g., using retireExactCarbonDefault for Klima DAO or deposit for Yearn).
2. Create a quote using getContractCallsQuote({ contractCalls }) that includes the bridge and the encoded call.
3. Execute and monitor the transaction.

Examples:

• Klima DAO: klimaRetireExactCarbon.ts (Optimism → Polygon)
• Polynomial: polynomialDeposit.ts (Arbitrum → Optimism)
• Yearn: yearnDeposit.ts (Arbitrum → Polygon)

Run commands:

pnpm example:klima
pnpm example:polynomial
pnpm example:yearn