Concepts and Objects

This page provides consistent definitions for the core objects used across LI.FI’s API and SDK. Use these as the authoritative reference when building integrations.

Transfer Objects

Quote

A Quote is a single-step transfer plan with transaction data ready for immediate execution. Response from GET /quote:

interface Quote {
  id: string;                    // Unique quote identifier
  type: "lifi";                  // Quote type
  tool: string;                  // Bridge or DEX used (e.g., "stargateV2")
  action: Action;                // What happens in this transfer
  estimate: Estimate;            // Output amounts and fees
  transactionRequest: {          // Ready-to-sign transaction
    to: string;
    data: string;
    value: string;
    gasLimit: string;
    // ... other tx fields
  };
}

When to use: Request a Quote via /quote when you want the best single route with transaction data included. Ideal for simple transfers.

Get Quote API

Request a quote for token transfers

Route

A Route is a multi-step transfer plan that may require sequential transactions. Response from POST /advanced/routes (returns array of routes):

interface Route {
  id: string;                    // Unique route identifier
  fromChainId: number;           // Source chain
  toChainId: number;             // Destination chain
  fromToken: Token;              // Source token
  toToken: Token;                // Destination token
  fromAmount: string;            // Input amount (wei)
  toAmount: string;              // Expected output (wei)
  steps: Step[];                 // Array of steps to execute
}

When to use: Request Routes via /advanced/routes when you need multiple route options or want to compare alternatives. Each Step in a Route may require a separate transaction.

Get Routes API

Request multiple route options

Step

A Step is one atomic operation within a Route. Each Step represents a single transaction. Nested within Route response (also returned by POST /advanced/stepTransaction):

interface Step {
  id: string;                    // Unique step identifier
  type: "swap" | "cross" | "lifi" | "protocol";
  tool: string;                  // Bridge or DEX name
  toolDetails: ToolDetails;      // Logo, name, key
  action: Action;                // What this step does
  estimate: Estimate;            // Output estimates
  includedSteps?: Step[];        // Nested steps (for complex routes)
  transactionRequest?: {         // Transaction data (populated after stepTransaction call)
    to: string;
    data: string;
    value: string;
  };
}

Step types:

swap - Same-chain token swap via DEX
cross - Cross-chain bridge transfer
lifi - Combined swap + bridge in one transaction
protocol - Interaction with a DeFi protocol (deposit, stake, etc.)

Action

An Action describes what happens in a Step - the source and destination tokens, chains, and amounts. Nested within Quote/Step responses:

interface Action {
  fromChainId: number;           // Source chain ID
  toChainId: number;             // Destination chain ID
  fromToken: Token;              // Token being sent
  toToken: Token;                // Token being received
  fromAmount: string;            // Input amount (wei)
  slippage: number;              // Allowed slippage (e.g., 0.005 = 0.5%)
  fromAddress?: string;          // Sender address
  toAddress?: string;            // Recipient address (if different)
}

Reference Objects

Tool

A Tool is a bridge or exchange used to execute transfers. LI.FI aggregates 27 bridges and 31 exchanges. Use GET /tools for the current list. Response from GET /tools:

interface Tool {
  key: string;                   // Unique identifier (e.g., "stargateV2")
  name: string;                  // Display name (e.g., "Stargate")
  logoURI: string;               // Tool logo URL
  supportedChains: Chain[];      // Chains this tool supports
}

Popular bridges: stargateV2, across, relay, cbridge Popular DEXs: 1inch, paraswap, 0x, uniswap, sushiswap

Use GET /tools to get the current list of supported bridges and exchanges.

List Tools API

Get all available bridges and exchanges

Chain

A Chain represents a supported blockchain network. Response from GET /chains:

interface Chain {
  id: number;                    // Chain ID (e.g., 1 for Ethereum)
  key: string;                   // Short key (e.g., "eth")
  name: string;                  // Display name (e.g., "Ethereum")
  chainType: "EVM" | "SVM" | "UTXO" | "MVM";
  coin: string;                  // Native token symbol
  logoURI: string;               // Chain logo URL
  metamask?: {                   // MetaMask connection info
    chainId: string;
    chainName: string;
    nativeCurrency: {...};
    rpcUrls: string[];
  };
}

Chain types:

EVM - Ethereum Virtual Machine chains (Ethereum, Arbitrum, etc.)
SVM - Solana Virtual Machine
UTXO - Bitcoin and UTXO-based chains
MVM - Move Virtual Machine (SUI)

List Chains API

Get all supported chains

Token

A Token represents a supported cryptocurrency on a specific chain. Response from GET /tokens:

interface Token {
  address: string;               // Contract address (or native token identifier)
  chainId: number;               // Chain this token is on
  symbol: string;                // Token symbol (e.g., "USDC")
  name: string;                  // Full name (e.g., "USD Coin")
  decimals: number;              // Decimal places (e.g., 6 for USDC)
  logoURI?: string;              // Token logo URL
  priceUSD?: string;             // Current USD price
  coinKey?: string;              // Canonical token identifier across chains
}

The same token (e.g., USDC) has different addresses on each chain. Use coinKey to identify the same asset across chains.

List Tokens API

Get all supported tokens

Status Objects

Status

Status indicates the current state of a cross-chain transfer.

Status	Description
`NOT_FOUND`	Transaction not yet indexed or invalid hash
`INVALID`	Transaction failed validation
`PENDING`	Transfer is in progress
`DONE`	Transfer completed (check substatus for details)
`FAILED`	Transfer failed (check substatus for reason)

Substatus

Substatus provides detailed information within each Status.

PENDING Substatuses

Substatus	Description
`WAIT_SOURCE_CONFIRMATIONS`	Waiting for source chain confirmations
`WAIT_DESTINATION_TRANSACTION`	Bridge is processing, waiting for destination
`BRIDGE_NOT_AVAILABLE`	Bridge temporarily unavailable
`CHAIN_NOT_AVAILABLE`	Chain RPC issues
`REFUND_IN_PROGRESS`	Refund is being processed
`UNKNOWN_ERROR`	Temporary error, keep polling

DONE Substatuses

Substatus	Description
`COMPLETED`	Transfer successful, user received exact requested tokens
`PARTIAL`	Transfer successful, user received different token than requested
`REFUNDED`	Transfer failed but tokens were refunded to sender

FAILED Substatuses

Substatus	Description
`NOT_PROCESSABLE_REFUND_NEEDED`	Cannot complete, manual refund required
`OUT_OF_GAS`	Transaction ran out of gas
`SLIPPAGE_EXCEEDED`	Received amount too low (price moved beyond allowed slippage)
`INSUFFICIENT_ALLOWANCE`	Token approval insufficient
`INSUFFICIENT_BALANCE`	Not enough tokens or gas
`EXPIRED`	Transaction expired
`UNKNOWN_ERROR`	Unknown or invalid state
`REFUNDED`	Tokens were refunded

For the complete and authoritative status documentation, see the Status Tracking Guide.

Status Tracking Guide

Complete guide to monitoring transfers

Partial

A transfer is Partial when it completes successfully but the user receives a different token than originally requested. Why this happens:

Destination chain swap failed after bridging
Insufficient liquidity for final swap
Price impact too high for destination swap

What the user receives:

The bridged token (e.g., USDC.e instead of native USDC)
Full value is preserved, just in a different token

How to handle:

Check substatus === "PARTIAL" when status === "DONE"
Read receiving.token from status response for actual received token
Inform user they received equivalent value in different token

Intermediate Tokens Guide

Understanding PARTIAL status and intermediate tokens

Refunded

A transfer is Refunded when it fails but the user’s tokens are returned to their wallet. When refunds happen:

Bridge execution failed
Destination chain issues
Transfer expired

Refund location:

Usually returned to sender on the source chain
Some bridges refund on destination chain (check status response)

How to handle:

Check for substatus === "REFUNDED"
Read refund object from status response for details
Inform user their funds were returned

Not all failed transfers are automatically refundable. Some bridges require manual claiming. Check the status response refund field for instructions.

Quick Reference

Object	Description	API Endpoint
Quote	Single-step transfer with tx data	`GET /quote`
Route	Multi-step transfer plan	`POST /advanced/routes`
Step	One operation in a route	Part of Route response
Action	Transfer details (from/to)	Part of Step
Tool	Bridge or DEX	`GET /tools`
Chain	Blockchain network	`GET /chains`
Token	Cryptocurrency	`GET /tokens`
Status	Transfer state	`GET /status`

​Transfer Objects

​Quote

Get Quote API

​Route

Get Routes API

​Step

​Action

​Reference Objects

​Tool

List Tools API

​Chain

List Chains API

​Token

List Tokens API

​Status Objects

​Status

​Substatus

​PENDING Substatuses

​DONE Substatuses

​FAILED Substatuses

Status Tracking Guide

​Partial

Intermediate Tokens Guide

​Refunded

​Quick Reference

Transfer Objects

Quote

Route

Step

Action

Reference Objects

Tool

Chain

Token

Status Objects

Status

Substatus

PENDING Substatuses

DONE Substatuses

FAILED Substatuses

Partial

Refunded

Quick Reference