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

# Data Schemas

> Type definitions, formats, and enums for LI.FI API

This page documents the data types, formats, and validation rules for LI.FI API parameters and responses. Use this as a reference for building robust integrations.

## Core Types

### Chain

Represents a blockchain network.

```typescript theme={"system"}
interface Chain {
  id: number;              // Chain ID (e.g., 1 for Ethereum)
  key: string;             // Short identifier (e.g., "eth")
  name: string;            // Display name (e.g., "Ethereum")
  chainType: ChainType;    // "EVM" | "SVM" | "UTXO" | "MVM"
  coin: string;            // Native token symbol (e.g., "ETH")
  mainnet: boolean;        // true if mainnet
  logoURI: string;         // Chain logo URL
  metamask?: MetaMaskConfig;
}

type ChainType = "EVM" | "SVM" | "UTXO" | "MVM";
```

| Field       | Type    | Required | Description             |
| ----------- | ------- | -------- | ----------------------- |
| `id`        | integer | Yes      | Unique chain identifier |
| `key`       | string  | Yes      | Short key (lowercase)   |
| `name`      | string  | Yes      | Human-readable name     |
| `chainType` | enum    | Yes      | Blockchain type         |
| `coin`      | string  | Yes      | Native token symbol     |
| `mainnet`   | boolean | Yes      | Is production network   |

### Common Chain IDs

| Chain     | ID                 | Type |
| --------- | ------------------ | ---- |
| Ethereum  | `1`                | EVM  |
| Arbitrum  | `42161`            | EVM  |
| Optimism  | `10`               | EVM  |
| Polygon   | `137`              | EVM  |
| Base      | `8453`             | EVM  |
| Avalanche | `43114`            | EVM  |
| BSC       | `56`               | EVM  |
| Solana    | `1151111081099710` | SVM  |

***

### Token

Represents a cryptocurrency token.

```typescript theme={"system"}
interface Token {
  address: string;         // Contract address
  symbol: string;          // Token symbol (e.g., "USDC")
  name: string;            // Full name (e.g., "USD Coin")
  decimals: number;        // Decimal places (e.g., 6)
  chainId: number;         // Chain this token is on
  priceUSD?: string;       // Current USD price
  logoURI?: string;        // Token logo URL
}
```

| Field      | Type    | Required | Format                | Description      |
| ---------- | ------- | -------- | --------------------- | ---------------- |
| `address`  | string  | Yes      | Hex (0x...) or native | Contract address |
| `symbol`   | string  | Yes      | 2-10 chars            | Trading symbol   |
| `decimals` | integer | Yes      | 0-18                  | Decimal places   |
| `chainId`  | integer | Yes      |                       | Parent chain ID  |
| `priceUSD` | string  | No       | Decimal string        | USD price        |

### Native Token Address

```
0x0000000000000000000000000000000000000000
```

This address represents the native token (ETH, MATIC, etc.) on any EVM chain.

### Common Token Decimals

| Token | Decimals | 1 Token in Wei        |
| ----- | -------- | --------------------- |
| USDC  | 6        | `1000000`             |
| USDT  | 6        | `1000000`             |
| DAI   | 18       | `1000000000000000000` |
| WETH  | 18       | `1000000000000000000` |
| WBTC  | 8        | `100000000`           |

***

### Quote

Response from `/quote` endpoint.

```typescript theme={"system"}
interface Quote {
  id: string;                    // Unique quote identifier
  type: "lifi";                  // Always "lifi"
  tool: string;                  // Bridge/DEX used
  toolDetails: ToolDetails;      // Tool metadata
  action: Action;                // Transfer details
  estimate: Estimate;            // Cost and output estimates
  transactionRequest: TxRequest; // Ready-to-sign transaction
}
```

***

### Action

Describes what the quote will do.

```typescript theme={"system"}
interface Action {
  fromChainId: number;       // Source chain
  toChainId: number;         // Destination chain
  fromToken: Token;          // Source token
  toToken: Token;            // Destination token
  fromAmount: string;        // Input amount (smallest unit)
  slippage: number;          // Slippage tolerance (decimal)
  fromAddress: string;       // Sender address
  toAddress: string;         // Recipient address
}
```

| Field         | Type    | Format           | Constraints             |
| ------------- | ------- | ---------------- | ----------------------- |
| `fromChainId` | integer |                  | Must be supported chain |
| `toChainId`   | integer |                  | Must be supported chain |
| `fromAmount`  | string  | Integer string   | > 0, in smallest unit   |
| `slippage`    | number  | Decimal          | 0 \< slippage \< 1      |
| `fromAddress` | string  | 0x... (42 chars) | Valid address           |

***

### Estimate

Cost and output estimates.

```typescript theme={"system"}
interface Estimate {
  fromAmount: string;           // Input amount
  toAmount: string;             // Expected output amount
  toAmountMin: string;          // Minimum guaranteed (slippage)
  approvalAddress: string;      // Spender for token approval
  executionDuration: number;    // Estimated seconds
  feeCosts: FeeCost[];          // Protocol fees
  gasCosts: GasCost[];          // Gas costs
}
```

| Field               | Type    | Description                         |
| ------------------- | ------- | ----------------------------------- |
| `toAmount`          | string  | Expected output (optimistic)        |
| `toAmountMin`       | string  | Guaranteed minimum (after slippage) |
| `approvalAddress`   | string  | Use for ERC20 `approve()`           |
| `executionDuration` | integer | Estimated time in seconds           |

***

### TransactionRequest

Ready-to-sign transaction data.

```typescript theme={"system"}
interface TransactionRequest {
  to: string;           // Contract address
  data: string;         // Encoded call data
  value: string;        // Native token amount (hex)
  gasLimit: string;     // Gas limit (hex)
  gasPrice?: string;    // Suggested gas price (hex)
  chainId: number;      // Chain ID for signing
}
```

| Field      | Type    | Format           | Description             |
| ---------- | ------- | ---------------- | ----------------------- |
| `to`       | string  | 0x... (42 chars) | Destination contract    |
| `data`     | string  | 0x... (hex)      | Encoded function call   |
| `value`    | string  | 0x... (hex)      | Wei amount (hex string) |
| `gasLimit` | string  | 0x... (hex)      | Gas units (hex)         |
| `chainId`  | integer |                  | EIP-155 chain ID        |

### Converting Hex Values

```javascript theme={"system"}
// Hex to decimal
const gasLimit = parseInt(tx.gasLimit, 16);
const value = BigInt(tx.value);

// Decimal to hex
const hexValue = '0x' + amount.toString(16);
```

***

### Status

Transfer status response.

```typescript theme={"system"}
interface Status {
  transactionId: string;      // Unique transfer ID
  sending: TransferInfo;      // Source chain info
  receiving?: TransferInfo;   // Destination chain info
  status: StatusType;         // Current status
  substatus?: SubstatusType;  // Detailed status (when DONE)
  tool: string;               // Bridge used
  error?: string;             // Error message (if failed)
}

type StatusType = "NOT_FOUND" | "PENDING" | "DONE" | "FAILED";
type SubstatusType = "COMPLETED" | "PARTIAL" | "REFUNDED";
```

### Status State Machine

```
NOT_FOUND → PENDING → DONE (COMPLETED | PARTIAL | REFUNDED)
                   ↘ FAILED
```

| Status      | Substatus   | Meaning                       |
| ----------- | ----------- | ----------------------------- |
| `NOT_FOUND` | -           | Transaction not indexed yet   |
| `PENDING`   | -           | Transfer in progress          |
| `DONE`      | `COMPLETED` | Success - got requested token |
| `DONE`      | `PARTIAL`   | Success - got different token |
| `DONE`      | `REFUNDED`  | Failed - tokens returned      |
| `FAILED`    | -           | Permanent failure             |

***

## Enums

### Order

Route ordering preference.

```typescript theme={"system"}
type Order = "FASTEST" | "CHEAPEST";
```

| Value      | Description           |
| ---------- | --------------------- |
| `FASTEST`  | Lowest execution time |
| `CHEAPEST` | Lowest total fees     |

### ChainType

Blockchain architecture type.

```typescript theme={"system"}
type ChainType = "EVM" | "SVM" | "UTXO" | "MVM";
```

| Value  | Description              | Examples                    |
| ------ | ------------------------ | --------------------------- |
| `EVM`  | Ethereum Virtual Machine | Ethereum, Arbitrum, Polygon |
| `SVM`  | Solana Virtual Machine   | Solana                      |
| `UTXO` | Bitcoin-style            | Bitcoin                     |
| `MVM`  | Move Virtual Machine     | Sui                         |

***

## Request Parameter Formats

### Address Format

```
Pattern: ^0x[a-fA-F0-9]{40}$
Example: 0x552008c0f6870c2f77e5cC1d2eb9bdff03e30Ea0
```

### Amount Format

Amounts are always in the smallest unit (wei for ETH, 6 decimals for USDC):

```
Format: String containing non-negative integer
Example: "10000000" (10 USDC)
```

### Slippage Format

Decimal between 0 and 1:

```
Format: Number (decimal)
Example: 0.005 (0.5%)
Range: 0.001 to 0.5
```

### Transaction Hash Format

```
Pattern: ^0x[a-fA-F0-9]{64}$
Example: 0xabc123...def456 (66 characters total)
```

***

## Validation Rules

### Quote Request

```javascript theme={"system"}
const quoteValidation = {
  fromChain: {
    type: 'integer',
    required: true,
    min: 1
  },
  toChain: {
    type: 'integer', 
    required: true,
    min: 1
  },
  fromToken: {
    type: 'string',
    required: true,
    pattern: /^(0x[a-fA-F0-9]{40}|[A-Z0-9]+)$/  // Address or symbol
  },
  toToken: {
    type: 'string',
    required: true,
    pattern: /^(0x[a-fA-F0-9]{40}|[A-Z0-9]+)$/
  },
  fromAmount: {
    type: 'string',
    required: true,
    pattern: /^[0-9]+$/,  // Positive integer string
    min: '1'
  },
  fromAddress: {
    type: 'string',
    required: true,
    pattern: /^0x[a-fA-F0-9]{40}$/
  },
  slippage: {
    type: 'number',
    required: false,
    default: 0.005,
    min: 0.001,
    max: 0.5
  }
};
```

***

## OpenAPI Reference

Full OpenAPI specification is available at:

* **Spec URL**: `https://li.quest/v1/docs-json`
* **Swagger UI**: `https://apidocs.li.fi/`

Download and parse the spec for complete schema definitions:

```bash theme={"system"}
curl "https://li.quest/v1/docs-json" > lifi-openapi.json
```

***

## Related Pages

* [Endpoint Specifications](/agents/reference/endpoint-specs) - API endpoints
* [Concepts](/agents/concepts) - Core concept definitions
* [Five-Call Recipe](/agents/quick-start/five-call-recipe) - Example usage