/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 \x3C 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 \x3C 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