back
loading skill details...
Cross-chain token swaps and bridges via the LI.FI protocol. Get quotes, execute transfers, track progress, and compose DeFi operations across 35+ blockchains.
---
name: lifi
description: Cross-chain token swaps and bridges via the LI.FI protocol. Get quotes, execute transfers, track progress, and compose DeFi operations across 35+ blockchains.
user-invocable: true
argument-hint: "[swap|bridge|track|routes|zap] <details>"
metadata: {"openclaw":{"emoji":"🔗","requires":{"bins":["curl"]},"primaryEnv":"LIFI_API_KEY"}}
---
# /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
```bash
curl -s "https://li.quest/v1/chains"
# Optional: ?chainTypes=EVM or ?chainTypes=SVM
```
#### GET /v1/tokens — List supported tokens
```bash
curl -s "https://li.quest/v1/tokens?chains=1,137"
# Optional: chainTypes, minPriceUSD
```
#### GET /v1/token — Get specific token details
```bash
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
```bash
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
```bash
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.
```bash
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
```bash
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
```bash
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
```bash
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)
```bash
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
```bash
curl -s "https://li.quest/v1/gas/prices"
```
#### GET /v1/gas/suggestion/{chainId} — Recommended gas params for a chain
```bash
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:
```bash
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**:
```bash
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**:
```bash
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:
```bash
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**:
```bash
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**:
```bash
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
| Error | Cause | Action |
|-------|-------|--------|
| HTTP 429 | Rate limited | Wait 30s, retry with exponential backoff (30s → 60s → 120s). Suggest user set `LIFI_API_KEY` for higher limits. |
| No route found | Route unsupported or amount too small/large | Check `/v1/connections` for valid pairs. Suggest different tokens, smaller amount, or alternative chains. |
| Slippage error | Price moved beyond tolerance | Increase slippage (e.g., 0.03 → 0.05) and retry. Warn user about the trade-off. |
| Insufficient balance | Wallet lacks funds | Report the shortfall amount. Check balance with the agent's wallet tools. |
| Transaction reverted | Price moved, liquidity drained, or gas too low | Explain possible causes. Suggest retrying with higher slippage or gas. |
| PARTIAL completion | Bridge delivered token but not final swap | User has the bridged asset on the destination chain. They can swap it manually or retry. |
| REFUNDED | Bridge failed, funds returned | Confirm refund on source chain. Suggest trying a different bridge via `allowBridges`. |
| Invalid address | Malformed hex address | Verify address format: `0x` prefix, 42 characters, valid hex. |
---
## Chain Quick Reference
| Chain | ID | Native Token |
|-------|----|-------------|
| Ethereum | 1 | ETH |
| Polygon | 137 | MATIC |
| Arbitrum One | 42161 | ETH |
| Optimism | 10 | ETH |
| BSC | 56 | BNB |
| Base | 8453 | ETH |
| Avalanche | 43114 | AVAX |
| Fantom | 250 | FTM |
| zkSync Era | 324 | ETH |
| Gnosis | 100 | xDAI |
| Scroll | 534352 | ETH |
| Linea | 59144 | ETH |
| Blast | 81457 | ETH |
| Mode | 34443 | ETH |
| Solana | 1151111081099710 | SOL |
For the full list of supported chains, call `GET /v1/chains`.
Native token address on all EVM chains: `0x0000000000000000000000000000000000000000`
don't have the plugin yet? install it then click "run inline in claude" again.