| name | lifi |
| description | LI.FI REST API for cross-chain and same-chain token swaps, bridging, DeFi deposits (Composer), yield discovery (Earn), and intent-based execution (Intents).
USE THIS SKILL WHEN USER WANTS TO:
- Swap tokens between different blockchains (e.g., "swap USDC on Ethereum to ETH on Arbitrum")
- Bridge tokens to another chain (e.g., "move my ETH from mainnet to Optimism")
- Swap tokens on the same chain with best rates (e.g., "swap ETH to USDC on Polygon")
- Find the best route or quote for a token swap across chains
- Deposit into DeFi vaults/lending/staking in one click, including cross-chain (Composer: Aave, Morpho, Pendle, EtherFi, Yearn, etc.)
- Discover yield opportunities, vault APY/TVL data, or track DeFi positions (Earn)
- Execute gasless or intent-based transfers via a solver network (LI.FI Intents)
- Move stablecoins cheaply with optimized defaults (stablecoin preset)
- Build multi-chain payment flows (accept any token, settle in specific token)
- Check supported chains, tokens, bridges, or gas prices
- Track status of a cross-chain transaction, recover from failed/partial transfers
- Query transfer history/analytics or withdraw collected integrator fees
- Build backends, bots, or AI agents (any language) that need cross-chain functionality
|
LI.FI API Integration
LI.FI aggregates bridges, DEXs, intent solvers, and DeFi protocols behind one API. This skill covers the full product surface:
| Product | Base URL | What it does |
|---|
| Core API (swaps & bridges) | https://li.quest/v1 | Quotes, routes, execution data, status tracking across 75+ chains |
| Composer (DeFi execution) | https://li.quest/v1 (same /quote endpoint) | One-click swap/bridge + deposit/withdraw into vaults, lending, staking |
| Earn (yield data) | https://earn.li.fi/v1 | Vault discovery, APY/TVL analytics, portfolio positions |
| Intents (solver marketplace) | https://order.li.fi | Intent-based orders filled by a competitive solver network |
For AI agents, LI.FI also offers an MCP server (https://mcp.li.quest/mcp) and a CLI (@lifi/cli). LI.FI recommends agents and backends use the REST API directly rather than the SDK.
Authentication & Rate Limits
API key is optional — it only raises rate limits. Header: x-lifi-api-key (get one at the LI.FI Partner Portal).
curl "https://li.quest/v1/chains" -H "x-lifi-api-key: YOUR_API_KEY"
| Tier | /quote, /advanced/routes | /advanced/stepTransaction | Other endpoints |
|---|
| Without API key | 75 req / 2 hours | 50 req / 2 hours | 100 req / minute |
| With API key (default) | 100 RPM (2-hour rolling window: 12,000 / 2h) | same | 100 RPM |
Responses include ratelimit-limit, ratelimit-remaining, ratelimit-reset (seconds) headers. 429 responses carry error code 1005. Never expose your API key in client-side code.
Quick Start — The Five-Call Recipe
The canonical flow for any swap/bridge:
1. GET /chains → discover chains (id, key, chainType, nativeToken)
2. GET /tokens → find tokens & decimals (?chains=1,42161)
3. GET /quote → get quote with ready-to-sign transactionRequest
4. [Execute] → if ERC-20: check allowance vs estimate.approvalAddress, approve if needed;
then sign & send transactionRequest
5. GET /status → poll until DONE or FAILED
curl "https://li.quest/v1/quote?\
fromChain=42161&toChain=10&\
fromToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&\
toToken=0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1&\
fromAmount=10000000&fromAddress=0xYourAddress&slippage=0.005"
curl "https://li.quest/v1/status?txHash=0xYourTxHash&fromChain=42161&toChain=10&bridge=across"
From the quote response, extract: transactionRequest (sign & send), estimate.approvalAddress (ERC-20 spender), estimate.toAmount/toAmountMin, estimate.executionDuration (basis for polling), and tool (pass as bridge to /status). Quotes go stale in ~60 seconds — re-fetch before signing if older (and always after a separate approval tx).
Core Endpoints
GET /quote
Single best route with transaction data ready for execution.
| Parameter | Type | Required | Description |
|---|
fromChain / toChain | string | Yes | Chain ID or key (same value = same-chain swap) |
fromToken / toToken | string | Yes | Token address or symbol |
fromAmount | string | Yes | Amount in smallest unit |
fromAddress | string | Yes | Sender wallet address |
toAddress | string | No | Recipient (defaults to fromAddress) |
slippage | number | No | 0.005 = 0.5% (default) |
order | string | No | FASTEST or CHEAPEST |
integrator | string | No | Your app ID (analytics + fee collection) |
fee | number | No | Integrator fee (0.02 = 2%) |
preset | string | No | Routing preset, e.g. stablecoin (see below) |
allowBridges / denyBridges / preferBridges | string[] | No | Tool keys from /tools, or all/none/default |
allowExchanges / denyExchanges / preferExchanges | string[] | No | Same |
allowDestinationCall | boolean | No | Default true |
maxPriceImpact | number | No | Default 0.10 (10%) |
fromAmountForGas | string | No | Amount converted to gas on destination |
skipSimulation | boolean | No | Faster response, less accurate gas limit |
svmPriorityFeeLevel | string | No | Solana priority fee: NORMAL/FAST/ULTRA |
swapStepTimingStrategies / routeTimingStrategies | string[] | No | e.g. minWaitTime-600-4-300 |
Variants:
- GET /quote/toAmount — pass
toAmount instead of fromAmount; API computes the required input.
- POST /quote/contractCalls — bridge + arbitrary destination-chain contract calls (manual calldata). For supported DeFi protocols, prefer Composer instead.
POST /advanced/routes + POST /advanced/stepTransaction
Multiple route options for comparison. Note the different naming: body uses fromChainId, fromTokenAddress (addresses only), with filters and preset inside options{}. Routes contain steps without transaction data — POST each step to /advanced/stepTransaction to populate transactionRequest.
Use /quote for simple transfers (1 call); use /advanced/routes when the user needs choices or price comparison (2+ calls).
GET /status
txHash (required — sending hash, receiving hash, or step id), plus optional fromChain (recommended, speeds up response), toChain, bridge.
Statuses: NOT_FOUND → PENDING → DONE | FAILED. On DONE, check substatus: COMPLETED, PARTIAL (different token received — full value preserved), or REFUNDED. See Status Recovery below.
Discovery & utility
- GET /chains —
?chainTypes=EVM,SVM,UTXO,MVM,TVM. If omitted, returns EVM only. Non-EVM: Solana (SVM), Bitcoin (UTXO), Sui (MVM), Tron (TVM).
- GET /tokens —
?chains=1,137&tags=stablecoin&minPriceUSD=0.01
- GET /token —
?chain=POL&token=DAI
- GET /tools — valid bridge/exchange keys for the
allow*/deny* filters
- GET /connections — available token-pair connections (at least one filter required)
- GET /gas/prices
, /gas/prices/{chainId}, /gas/suggestion/{chain}` — gas data; GET /gas/status — LIFuel tx status
- GET /calldata/parse (beta) —
?callData=0x...&chainId=1 decodes LI.FI calldata into named function calls
- Analytics:
GET /v1/analytics/transfers (filtered, max 1000), GET /v2/analytics/transfers (cursor-paginated), GET /v1/analytics/transfers/summary (cross-chain amounts received, 30-day max range)
- Integrator fees:
GET /integrators/{integratorId} (collected fee balances), GET /integrators/{integratorId}/withdraw/{chainId} (withdrawal transactionRequest)
Deprecated — do not use: /advanced/possibilities, /gas/refetch, /analytics/wallets/{address}.
Routing Presets
preset=stablecoin (on /quote, or options.preset on /advanced/routes) applies optimized defaults for stablecoin transfers: order=CHEAPEST, slippage=0.001, price impact capped at 2%, and a shortlist of stablecoin-friendly bridges (Glacis, Mayan, Celer, Eco, Relay, Across, Gaszip). Explicit request params always override preset defaults — but list overrides like denyBridges replace the preset's lists entirely. Find qualifying tokens with GET /tokens?tags=stablecoin. (commerce preset coming soon.)
Composer — One-Click DeFi Deposits & Withdrawals
Composer bundles swap + bridge + protocol interaction (deposit, stake, lend, withdraw) into a single atomic transaction. There is no dedicated endpoint — set toToken to a supported protocol's vault/staking/deposit token address on the standard GET /quote, and Composer activates automatically:
curl "https://li.quest/v1/quote?\
fromChain=42161&toChain=8453&\
fromToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&\
toToken=0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A&\
fromAmount=100000000&fromAddress=0xYou&toAddress=0xYou"
- Detection: same-chain deposit quotes show the zap tool as top-level
tool (e.g. composer, but the engine may route via other integrated zap tools such as fly); cross-chain quotes show the bridge as tool with the zap step in includedSteps. Don't hard-code on tool === "composer" — any quote with a vault address as toToken is a deposit route.
- Withdrawals: reverse it — vault token as
fromToken, desired token as toToken.
- Every quote is simulated on a fork before being returned; failures surface as API errors instead of reverting txs.
- Coverage: ~29 protocols (Aave V3, Morpho, Pendle, Spark, Euler, Fluid, Yearn, EtherFi, Kelp, Ethena, Maple, …) across 23 EVM chains. Some are deposit-only (Ethena, Kinetiq, Maple, Royco, USDai, Concrete, Ember) — withdraw via the protocol's own UI.
- Limitations: EVM only; tokenized positions only (the target must mint a token); cross-chain flows are eventually consistent, not atomic — a destination deposit can fail after a successful bridge, leaving the user with the bridged token (poll
/status, handle PARTIAL).
- Use higher slippage (e.g.
0.01) for cross-chain composer routes.
See references/REFERENCE.md for the full protocol list and error codes.
Earn — Yield Discovery & Portfolio Data
Earn is a read-only data API at https://earn.li.fi (separate host!) normalizing vaults from 20+ protocols. Unlike the core API, it requires the x-lifi-api-key header (401 without). Execution is delegated to Composer: take a vault's address and use it as toToken on li.quest/v1/quote.
| Endpoint | Purpose |
|---|
GET /v1/vaults | List vaults — filter by chainId, asset (symbol or address), protocol, minTvlUsd, isTransactional, isRedeemable, isComposerSupported; sort with sortBy=apy|tvl; cursor pagination (limit ≤ 100, follow nextCursor) |
GET /v1/vaults/{chainId}/{address} | Single vault detail |
GET /v1/chains / GET /v1/protocols | Filter dropdown data (Earn-scoped, not platform-wide) |
GET /v1/portfolio/{userAddress}/positions | User's DeFi positions with USD balances |
curl "https://earn.li.fi/v1/vaults?chainId=8453&asset=USDC&sortBy=apy&isComposerSupported=true&limit=10" \
-H "x-lifi-api-key: YOUR_API_KEY"
Gotchas: boolean filters are string literals ("true"/"false"); APY values are decimals (0.0534 = 5.34%); TVL/balances are strings; lpTokens is usually empty — use the vault's top-level address for execution; gate deposit/withdraw UI on isTransactional/isRedeemable; check timeLock, caps, kyc fields. Rate limit: 50 req/min per key. Vault data refreshes every 15 min (transactional flags every 2 min).
Discover → deposit recipe: GET earn.li.fi/v1/vaults → pick vault → GET li.quest/v1/quote with vault address as toToken → approve + send → poll /status.
LI.FI Intents — Solver Marketplace
A separate intent-based system at https://order.li.fi (dev: order-dev.li.fi). Users express desired outcomes; solvers pre-fund delivery on the destination chain against standing quotes. Foundation of the Open Intents Framework. Integrator endpoints need no API key.
| Endpoint | Purpose |
|---|
POST /quote/request | Quote an intent (swapType: exact-input/exact-output); returns quotes[] best-first with quoteId |
POST /orders/submit | Off-chain order submission (Compact/gasless flows) |
GET /orders/status | By onChainOrderId or catalystOrderId |
GET /orders | List/filter orders |
GET /chains/supported / GET /routes | Live coverage (EVM + Solana + Tron) |
Two funding models:
- Escrow (recommended default): approve → on-chain
open(order) on InputSettlerEscrow — no /orders/submit call needed, solvers detect the Open event.
- Compact (gasless): deposit once into The Compact, then sign EIP-712
BatchCompact orders off-chain and submit via /orders/submit.
Order lifecycle: Submitted/Open → Signed → Delivered → Settled (terminal). Refundable after expires if unfilled. Addresses use EIP-7930 interoperable format (chain ID embedded), not bare 0x addresses. Amounts in smallest units. See REFERENCE.md for StandardOrder structs, contract addresses, and signing details.
Note: the classic li.quest/v1/quote already aggregates intent-based bridges (Across, Relay, etc.) — only integrate order.li.fi directly when you want the order-server model itself (solver selection, resource locks, gasless submission).
Token Approvals
- Native token (
0x0000…0000) → no approval needed.
- Spender is always
quote.estimate.approvalAddress — never hardcode it (it varies by route).
- Check
allowance(fromAddress, approvalAddress); if < fromAmount, send approve and wait for confirmation before the main tx, then re-fetch the quote (gas estimates go stale).
- USDT quirk: if current allowance > 0, you must
approve(spender, 0) first, then approve the new amount.
- Prefer exact-amount approvals for agents; approval gas ≈ 50–100k.
Status Tracking & Recovery
Poll GET /status with backoff: 10s (first ~6 attempts) → 30s → 60s → 120s. Use estimate.executionDuration from the quote to set expectations. Same-chain swaps are atomic and usually instant.
| Result | Action |
|---|
NOT_FOUND / PENDING | Keep polling (NOT_FOUND just means not indexed yet) |
DONE + COMPLETED | Success |
DONE + PARTIAL | User received a different token (full value preserved, typically the bridge token on the destination). Optionally recover: quote a same-chain swap from receiving.token to the intended token; skip if gas > ~10% of value |
DONE + REFUNDED | Tokens returned on the source chain |
FAILED | Permanent — check substatus (SLIPPAGE_EXCEEDED, OUT_OF_GAS, NOT_PROCESSABLE_REFUND_NEEDED, …), inform user |
On timeout, never assume failure — save txHash and share lifiExplorerLink (https://explorer.li.fi/tx/<txHash>). Funds are non-custodial and end with the user; prevent PARTIAL by raising slippage for volatile tokens or targeting the bridge's native token directly.
Error Handling
| HTTP | Retry? | Action |
|---|
| 400 | No | Fix parameters |
404 / NO_POSSIBLE_ROUTE | Maybe | Different pair/amount/chains; try USDC/USDT/ETH as intermediary |
| 429 (code 1005) | Yes | Exponential backoff min(2^attempt × 1s, 30s) |
| 500/503 | Yes (1–2×) | Wait 2–10s, retry |
Common API error codes: 1002 NoQuote, 1007 Slippage (raise slippage to min(current×2, 0.03) or lower amount), 1011 Validation. Tool-level codes inside errors[]: NO_POSSIBLE_ROUTE, AMOUNT_TOO_LOW (Composer minimums run higher), INSUFFICIENT_LIQUIDITY, TOOL_TIMEOUT (retry immediately), FEES_HIGHER_THAN_AMOUNT. On execution reverted at send time: the quote was stale — fetch a fresh one (max ~2 retries). Full table in REFERENCE.md.
Integration Examples
Python
import requests
BASE_URL = "https://li.quest/v1"
HEADERS = {"x-lifi-api-key": "YOUR_API_KEY"}
def get_quote(from_chain, to_chain, from_token, to_token, amount, address, **kwargs):
params = {
"fromChain": from_chain, "toChain": to_chain,
"fromToken": from_token, "toToken": to_token,
"fromAmount": amount, "fromAddress": address,
"slippage": 0.005, "integrator": "your-app", **kwargs,
}
r = requests.get(f"{BASE_URL}/quote", params=params, headers=HEADERS)
r.raise_for_status()
return r.json()
def get_status(tx_hash, from_chain=None, to_chain=None, bridge=None):
params = {"txHash": tx_hash, "fromChain": from_chain,
"toChain": to_chain, "bridge": bridge}
return requests.get(f"{BASE_URL}/status", params=params, headers=HEADERS).json()
quote = get_quote(42161, 10,
"0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1",
"10000000", "0xYourAddress")
deposit = get_quote(8453, 8453,
"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A",
"100000000", "0xYourAddress")
tx = quote["transactionRequest"]
gas_limit = int(tx["gasLimit"], 16)
Node.js
const BASE_URL = 'https://li.quest/v1';
async function getQuote(params) {
const res = await fetch(`${BASE_URL}/quote?${new URLSearchParams(params)}`);
if (!res.ok) throw new Error(`Quote failed: ${res.status} ${await res.text()}`);
return res.json();
}
async function pollStatus(txHash, fromChain, toChain, bridge) {
const params = new URLSearchParams({ txHash, fromChain, toChain, bridge });
for (let attempt = 0; attempt < 60; attempt++) {
const data = await (await fetch(`${BASE_URL}/status?${params}`)).json();
if (data.status === 'DONE' || data.status === 'FAILED') return data;
const delay = attempt < 6 ? 10_000 : attempt < 12 ? 30_000 : 60_000;
await new Promise((r) => setTimeout(r, delay));
}
throw new Error('Status polling timed out — check explorer.li.fi');
}
const { data: vaults } = await (await fetch(
'https://earn.li.fi/v1/vaults?chainId=8453&asset=USDC&sortBy=apy&isComposerSupported=true&limit=5'
)).json();
const quote = await getQuote({
fromChain: 8453, toChain: 8453,
fromToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
toToken: vaults[0].address,
fromAmount: '100000000',
fromAddress: '0xYourAddress', toAddress: '0xYourAddress',
});
Best Practices
- Always pass
integrator — required for analytics, fee collection, and fee withdrawal.
- Re-fetch stale quotes — quotes expire in ~60s; always re-quote after an approval tx.
- Cache
/chains, /tokens, /tools — they change infrequently and polling burns rate limit.
- Pass
fromChain to /status — significantly faster responses.
- Use
preset=stablecoin for stable-to-stable transfers instead of hand-tuning slippage/bridges.
- Request
chainTypes explicitly on /chains if you need non-EVM (default is EVM-only).
- Amounts are strings in smallest units (
human × 10^decimals); transactionRequest.value/gasLimit/gasPrice are hex strings.
- Handle
PARTIAL completions — offer a same-chain recovery swap when worthwhile.
- For agents: consider the MCP server (
https://mcp.li.quest/mcp) or @lifi/cli for token-efficient access; machine-readable docs at https://docs.li.fi/llms.txt and https://docs.li.fi/openapi.yaml (any docs page is fetchable as markdown by appending .md).
See references/REFERENCE.md for complete endpoint documentation, response schemas, the Earn and Intents API references, error codes, chain IDs, and token addresses.
