---

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

# 3. Quote (fromToken/toToken accept addresses OR symbols)
curl "https://li.quest/v1/quote?\
fromChain=42161&toChain=10&\
fromToken=0xaf…[redacted]&\
toToken=0xDA…[redacted]&\
fromAmount=10000000&fromAddress=0xYourAddress&slippage=0.005"

# 5. Status (pass fromChain to speed it up; bridge = quote's `tool`)
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:

# 100 USDC on Arbitrum → Morpho Spark USDC vault on Base, one signature
curl "https://li.quest/v1/quote?\
fromChain=42161&toChain=8453&\
fromToken=0xaf…[redacted]&\
toToken=0x7B…[redacted]&\
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 |

# Top USDC vaults on Base by APY, depositable via Composer
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