/lifi — Cross-Chain Swaps & Bridges

LI.FI is a cross-chain bridge and DEX aggregation protocol. It finds optimal routes across 35+ blockchains, comparing dozens of bridges (Stargate, Hop, Across, etc.) and DEXes (Uniswap, SushiSwap, 1inch, etc.) to execute token swaps and cross-chain transfers.

Arguments: $ARGUMENTS

Parse the arguments:

• First positional arg: Action — swap, bridge, track, routes, zap, or a natural language request
• Remaining args: Details (token names, amounts, chains, tx hashes, etc.)

If no arguments are provided, ask the user what they want to do.

Key Concepts

• Base URL: https://li.quest/v1
• The API returns transactionRequest objects (to, data, value, gasLimit, gasPrice) ready to sign — provide these to the agent's wallet
• Native token address: 0x0000000000000000000000000000000000000000 (for ETH, MATIC, BNB, etc.)
• Amounts are always in the token's smallest unit (wei): 1 ETH = 1000000000000000000 (18 decimals), 1 USDC = 1000000 (6 decimals)
• Optional API key via x-lifi-api-key header for higher rate limits (not required)

API Reference

Discovery Endpoints

GET /v1/chains — List supported blockchains

curl -s "https://li.quest/v1/chains"
# Optional: ?chainTypes=EVM or ?chainTypes=SVM

GET /v1/tokens — List supported tokens

curl -s "https://li.quest/v1/tokens?chains=1,137"
# Optional: chainTypes, minPriceUSD

GET /v1/token — Get specific token details

curl -s "https://li.quest/v1/token?chain=1&token=USDC"
# chain (required): chain ID or name. token (required): address or symbol

GET /v1/connections — Check available swap routes

curl -s "https://li.quest/v1/connections?fromChain=1&toChain=137&fromToken=0x0000000000000000000000000000000000000000"
# Optional: toToken, chainTypes, allowBridges

GET /v1/tools — List available bridges and DEXes

curl -s "https://li.quest/v1/tools"
# Returns {bridges: [{key, name}], exchanges: [{key, name}]}

Quote & Swap Endpoints

GET /v1/quote — Get optimal route + transaction data

The primary endpoint for initiating any swap or bridge.

curl -s "https://li.quest/v1/quote?\
fromChain=1&toChain=137\
&fromToken=0x0000000000000000000000000000000000000000\
&toToken=0x0000000000000000000000000000000000000000\
&fromAddress=0xYOUR_WALLET\
&fromAmount=1000000000000000000\
&slippage=0.03"

Required: fromChain, toChain, fromToken, toToken, fromAddress, fromAmount Optional: toAddress, slippage (decimal, e.g. 0.03 = 3%), integrator, order (RECOMMENDED|FASTEST|CHEAPEST|SAFEST), allowBridges, allowExchanges

Returns: action, estimate (toAmount, fees, executionDuration), and transactionRequest (to, data, value, gasLimit).

GET /v1/status — Track cross-chain transfer

curl -s "https://li.quest/v1/status?txHash=0xTX_HASH"
# Optional: bridge, fromChain, toChain

Returns: status (NOT_FOUND, PENDING, DONE, FAILED), substatus (COMPLETED, PARTIAL, REFUNDED), source/destination tx details.

Advanced Routing

POST /v1/advanced/routes — Compare multiple route options

curl -s -X POST "https://li.quest/v1/advanced/routes" \
  -H "Content-Type: application/json" \
  -d '{
    "fromChainId": "1",
    "toChainId": "137",
    "fromTokenAddress": "0x0000000000000000000000000000000000000000",
    "toTokenAddress": "0x0000000000000000000000000000000000000000",
    "fromAddress": "0xYOUR_WALLET",
    "fromAmount": "1000000000000000000",
    "options": {"order": "RECOMMENDED"}
  }'

Required: fromChainId, toChainId, fromTokenAddress, toTokenAddress, fromAddress, fromAmount Optional: toAddress, slippage, options.order

Returns: routes[] array — each route has steps, estimated output, fees, and execution time.

POST /v1/advanced/stepTransaction — Get tx data for a route step

curl -s -X POST "https://li.quest/v1/advanced/stepTransaction" \
  -H "Content-Type: application/json" \
  -d '{ ...step object from routes response... }'

Pass the entire step object from a route. Returns transactionRequest ready to sign.

POST /v1/quote/contractCalls — Zaps (multi-action DeFi composition)

curl -s -X POST "https://li.quest/v1/quote/contractCalls" \
  -H "Content-Type: application/json" \
  -d '{
    "fromChain": "1",
    "toChain": "137",
    "fromToken": "0x0000000000000000000000000000000000000000",
    "toToken": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "fromAddress": "0xYOUR_WALLET",
    "fromAmount": "1000000000000000000",
    "contractCalls": [
      {
        "toContractAddress": "0xTARGET_CONTRACT",
        "toContractCallData": "0xENCODED_FUNCTION_CALL",
        "toContractGasLimit": "200000"
      }
    ]
  }'

Required: fromChain, toChain, fromToken, toToken, fromAddress, fromAmount, contractCalls[] Optional: slippage

Gas Information

GET /v1/gas/prices — Gas prices across all chains

curl -s "https://li.quest/v1/gas/prices"

GET /v1/gas/suggestion/{chainId} — Recommended gas params for a chain

curl -s "https://li.quest/v1/gas/suggestion/1"

Guided Workflows

Workflow 1 — Swap or Bridge Tokens

Use this for any "swap X for Y" or "bridge tokens to chain" request.

1. Identify parameters from the user's request:

   • Source chain and token (e.g., "ETH on Ethereum")
   • Destination chain and token (e.g., "USDC on Polygon")
   • Amount in human-readable form (e.g., "1.5 ETH")
   • Wallet address (the agent's wallet or user-specified)

2. Look up token addresses if the user gave symbols:

   curl -s "https://li.quest/v1/token?chain=1&token=USDC"
   

   Extract address and decimals from the response.

3. Convert amount to smallest unit:

   • Multiply human amount by 10^decimals
   • 1.5 ETH (18 decimals) → 1500000000000000000
   • 100 USDC (6 decimals) → 100000000

4. Get a quote:

   curl -s "https://li.quest/v1/quote?fromChain=1&toChain=137&fromToken=0x0000000000000000000000000000000000000000&toToken=0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359&fromAddress=0xWALLET&fromAmount=1500000000000000000&slippage=0.03"
   

5. Present summary to user (REQUIRED before returning tx data):

   Swap: 1.5 ETH (Ethereum) → ~2,850 USDC (Polygon)
   Route: Stargate bridge → Uniswap V3
   Fees: ~$2.50 (gas) + $0.50 (bridge)
   Estimated time: ~2 minutes
   Slippage: 3%
   

6. If ERC20 token: Check if the LiFi contract has sufficient allowance. The spender address is transactionRequest.to from the quote response. If allowance < fromAmount, guide the user to approve the token first.

7. Return transactionRequest for signing by the agent's wallet.

8. If cross-chain: Explain that bridging is asynchronous — the source chain tx will confirm first, then the bridge delivers tokens to the destination. Offer to track with Workflow 3.

Workflow 2 — Compare Routes

Use when the user wants to see options or find the best deal.

1. Gather parameters (same as Workflow 1, steps 1-3).

2. Request multiple routes:

   curl -s -X POST "https://li.quest/v1/advanced/routes" \
     -H "Content-Type: application/json" \
     -d '{
       "fromChainId": "1",
       "toChainId": "137",
       "fromTokenAddress": "0x0000000000000000000000000000000000000000",
       "toTokenAddress": "0x0000000000000000000000000000000000000000",
       "fromAddress": "0xWALLET",
       "fromAmount": "1000000000000000000",
       "options": {"order": "RECOMMENDED"}
     }'
   

3. Present comparison table:

   #  Route                     Output       Fees     Time    Bridge
   1  Stargate → Uniswap V3    2,850 USDC   $3.00    2 min   Stargate
   2  Hop → SushiSwap          2,845 USDC   $2.80    5 min   Hop
   3  Across → 1inch           2,848 USDC   $3.20    3 min   Across
   

4. User picks a route. Extract the chosen route's steps.

5. Get transaction data for each step:

   curl -s -X POST "https://li.quest/v1/advanced/stepTransaction" \
     -H "Content-Type: application/json" \
     -d '{ ...step object... }'
   

6. Return transactionRequest for signing.

Workflow 3 — Track a Transfer

Use when the user wants to check status of a cross-chain transfer.

1. Get details from user: transaction hash, source chain, destination chain.

2. Check status:

   curl -s "https://li.quest/v1/status?txHash=0xTX_HASH&fromChain=1&toChain=137"
   

3. Interpret and report status:

   • NOT_FOUND — Transaction not yet indexed. Wait a minute and retry.
   • PENDING — Transfer in progress. Suggest polling every 30 seconds.
   • DONE with substatus COMPLETED — Transfer complete. Report destination tx hash.
   • DONE with substatus PARTIAL — User received the bridged token on the destination chain but NOT the final target token (e.g., got USDC.e instead of native USDC). The user may need to swap manually.
   • DONE with substatus REFUNDED — Transfer failed and funds were returned to the source address.
   • FAILED — Transfer failed. Report error details and advise the user to check the source chain tx on a block explorer.

4. If PENDING: Offer to poll periodically. Wait 30 seconds between checks.

Workflow 4 — Zap (Contract Call Composition)

Use for multi-step DeFi operations like "bridge ETH to Polygon and deposit into Aave" or "swap to USDC and stake in a vault."

1. Understand the multi-step operation — identify:

   • Source chain/token/amount
   • Destination chain/token (the intermediate token before contract calls)
   • Target contract and function to call on the destination

2. Gather contract call data:

   • toContractAddress: The destination contract (e.g., Aave lending pool)
   • toContractCallData: ABI-encoded function call (e.g., deposit(address,uint256,address,uint16))
   • toContractGasLimit: Gas limit for the contract call (e.g., "200000")

3. Request zap quote:

   curl -s -X POST "https://li.quest/v1/quote/contractCalls" \
     -H "Content-Type: application/json" \
     -d '{
       "fromChain": "1",
       "toChain": "137",
       "fromToken": "0x0000000000000000000000000000000000000000",
       "toToken": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
       "fromAddress": "0xWALLET",
       "fromAmount": "1000000000000000000",
       "contractCalls": [{
         "toContractAddress": "0xTARGET",
         "toContractCallData": "0xENCODED_CALL",
         "toContractGasLimit": "200000"
       }]
     }'
   

4. Present summary showing all operations in the zap (bridge + swap + deposit/stake/etc.).

5. Return transactionRequest for signing.

Workflow 5 — Discovery

Use when the user asks "what chains are supported?", "what tokens can I swap?", "what bridges are available?", etc.

1. Determine what the user wants to know:

   • Supported chains → GET /v1/chains
   • Tokens on a chain → GET /v1/tokens?chains={chainId}
   • Token details → GET /v1/token?chain={chainId}&token={symbol}
   • Available routes → GET /v1/connections?fromChain={id}&toChain={id}
   • Available bridges/DEXes → GET /v1/tools
   • Gas prices → GET /v1/gas/prices or GET /v1/gas/suggestion/{chainId}

2. Call the appropriate endpoint.

3. Present results in a readable table format. For large responses (e.g., all tokens), summarize the most relevant results and offer to filter further.

Safety Protocol

These rules are mandatory — never skip them.

Address Validation

• ALWAYS verify fromAddress is a valid hex address: starts with 0x, 42 characters total, valid hex characters
• NEVER send to the zero address (0x0000000000000000000000000000000000000000) as toAddress — this burns funds permanently. The zero address is ONLY valid as a fromToken/toToken to represent native tokens.

Amount Validation

• ALWAYS convert human-readable amounts to the token's smallest unit before calling the API
  • Check the token's decimals field (ETH=18, USDC=6, WBTC=8, DAI=18)
  • Formula: amount_wei = human_amount × 10^decimals
• Amounts must be positive integers (no decimals, no negatives, no zero)
• Maximum 78 digits (uint256 max)
• If the user says "1 ETH", send 1000000000000000000, NOT 1

Slippage Validation

• Default to 0.03 (3%) if the user doesn't specify
• WARN the user if slippage > 3% — explain they may receive significantly fewer tokens
• REJECT slippage > 50% (0.5) — this is almost certainly an error
• Slippage must be between 0 and 1 (0% to 100%)

ERC20 Token Approvals

• ALWAYS check token allowance before executing ERC20 swaps
• If allowance < fromAmount, guide the user to approve the token first
• NEVER approve unlimited amounts (MaxUint256 / 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff) unless the user explicitly requests it — approve only the needed amount
• The spender address is transactionRequest.to from the quote response

Transaction Presentation

• ALWAYS present a human-readable summary before returning any transactionRequest data
• The summary must include: tokens and amounts, route/bridge used, estimated fees, estimated time, slippage setting
• NEVER return raw transaction data without explanation

Cross-Chain Safety

• Explain that cross-chain bridges are non-atomic — funds may be in transit for minutes to hours
• After submitting a source chain tx, always offer to track the transfer status
• If a transfer shows PARTIAL status, explain the user received bridged tokens but not the final target token

No Route Found

• If a quote returns no route: suggest trying different tokens, a smaller amount, or an alternative chain pair
• Use GET /v1/connections to verify the route is supported before retrying

Error Handling

Chain Quick Reference

For the full list of supported chains, call GET /v1/chains.

Native token address on all EVM chains: 0x0000000000000000000000000000000000000000