> ## Documentation Index
> Fetch the complete documentation index at: https://docs.li.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts and Objects

> Canonical definitions for LI.FI API and SDK 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`:**

```typescript theme={"system"}
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.

<Card title="Get Quote API" icon="arrow-right" href="/api-reference/get-a-quote-for-a-token-transfer">
  Request a quote for token transfers
</Card>

### Route

A **Route** is a multi-step transfer plan that may require sequential transactions.

**Response from `POST /advanced/routes`** (returns array of routes):

```typescript theme={"system"}
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.

<Card title="Get Routes API" icon="arrow-right" href="/api-reference/advanced/get-a-set-of-routes-for-a-request-that-describes-a-transfer-of-tokens">
  Request multiple route options
</Card>

### 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`):

```typescript theme={"system"}
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:**

```typescript theme={"system"}
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`:**

```typescript theme={"system"}
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`

<Tip>
  Use `GET /tools` to get the current list of supported bridges and exchanges.
</Tip>

<Card title="List Tools API" icon="arrow-right" href="/api-reference/get-available-bridges-and-exchanges">
  Get all available bridges and exchanges
</Card>

### Chain

A **Chain** represents a supported blockchain network.

**Response from `GET /chains`:**

```typescript theme={"system"}
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)

<Card title="List Chains API" icon="arrow-right" href="/api-reference/get-information-about-all-currently-supported-chains">
  Get all supported chains
</Card>

### Token

A **Token** represents a supported cryptocurrency on a specific chain.

**Response from `GET /tokens`:**

```typescript theme={"system"}
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
}
```

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

<Card title="List Tokens API" icon="arrow-right" href="/api-reference/fetch-all-known-tokens">
  Get all supported tokens
</Card>

## 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                                          |

<Note>
  For the complete and authoritative status documentation, see the [Status Tracking Guide](/introduction/user-flows-and-examples/status-tracking).
</Note>

<Card title="Status Tracking Guide" icon="arrow-right" href="/introduction/user-flows-and-examples/status-tracking">
  Complete guide to monitoring transfers
</Card>

### 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:**

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

<Card title="Intermediate Tokens Guide" icon="arrow-right" href="/guides/intermediate-tokens">
  Understanding PARTIAL status and intermediate tokens
</Card>

### 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:**

1. Check for `substatus === "REFUNDED"`
2. Read `refund` object from status response for details
3. Inform user their funds were returned

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

## 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`           |