prepare_swap
Prepare an unsigned swap or bridge transaction via LiFi aggregator. Supports same-chain DEX routes and cross-chain swaps to EVM, Solana, or TRON.
Instructions
Prepare an unsigned swap or bridge transaction via LiFi aggregator. Same-chain swaps use the best DEX route; cross-chain swaps use a bridge + DEX combo. Default is exact-in (amount = fromToken); set amountSide: "to" for exact-out (amount = target toToken output, e.g. "I want 100 USDC out"). Source chain is always EVM. Destination can be any EVM chain, Solana, or TRON. For non-EVM destinations pass toChain: "solana" / "tron" + an explicit toAddress in the destination chain's format; the user signs an EVM tx and the bridge protocol delivers tokens to the destination after confirmation. The destination-side decimals cross-check is dropped for non-EVM destinations (we can't read SPL/TRC-20 via EVM RPC); LiFi's reported decimals are the source of truth there. Exact-out is not supported for cross-chain-to-non-EVM. For Solana-source swaps and bridges use prepare_solana_lifi_swap. TRON-source LiFi is not yet wired. PROTOCOL ROUTING (issue #411): without exchanges / bridges, LiFi picks the best-output route across all aggregators. When the user explicitly names a DEX ("swap on 1inch", "use Sushi"), pass exchanges: ["1inch"] (or the named protocol) — without the filter LiFi may silently route via a different DEX. If no route satisfies the filter the call errors with a clear message; the agent can offer to retry without the filter. The unsigned tx's description includes "via " and notes whether the resolved tool matched the filter. DECODING DEFENSE: every cross-chain bridge calldata is parsed into its BridgeData tuple and the encoded destinationChainId + receiver are cross-checked against what the user requested — refuses on mismatch. Catches a compromised MCP that returns calldata routing to a different chain or recipient than the prepare receipt advertises. INTERMEDIATE-CHAIN BRIDGES: NEAR Intents (notably for ETH→TRON USDT routes) settles on NEAR and releases on the final chain via an off-chain relayer, so its on-chain destinationChainId is NEAR's pseudo-id (1885080386571452) rather than the user's requested chain. The defense allows this ONLY for an explicit hardcoded (bridge name, intermediate chain ID) pair held as a source-code constant — not loaded from env / config / LiFi response — so a compromised aggregator can't claim arbitrary chains as 'intermediate'. Receiver-side checks (non-EVM sentinel, etc.) still apply unchanged. The returned tx can be sent via send_transaction.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wallet | Yes | ||
| fromChain | Yes | ||
| toChain | Yes | ||
| fromToken | Yes | ||
| toToken | Yes | ||
| toAddress | No | Destination wallet. OMIT for same-chain-type swaps (defaults to the source wallet — LiFi behavior). REQUIRED when `toChain` is `"solana"` or `"tron"` because the source EVM hex wallet isn't a valid recipient on those chains. Format must match the destination chain (Solana base58 for `"solana"`, TRON base58 with T-prefix for `"tron"`, EVM hex otherwise). | |
| amount | Yes | Human-readable decimal amount, NOT raw wei/base units. Example: "1.5" for 1.5 USDC, "0.01" for 0.01 ETH. Interpreted as fromToken input by default; set `amountSide: "to"` to interpret as the toToken output amount (exact-out). The tool resolves decimals on-chain and converts internally. | |
| amountSide | No | Which side of the swap `amount` refers to. "from" (default) = exact-in: you spend exactly `amount` of fromToken and receive a variable output. "to" = exact-out: you receive exactly `amount` of toToken and the input is sized to hit that target. Exact-out uses LiFi's toAmount quote and skips the 1inch comparison (1inch has no exact-out endpoint). | |
| fromTokenDecimals | No | Optional decimals hint for fromToken if on-chain lookup fails (rare). Native is 18. | |
| toTokenDecimals | No | Optional decimals hint for toToken if on-chain lookup fails (rare). Only used when `amountSide: "to"`. Native is 18. | |
| slippageBps | No | Slippage tolerance in basis points (50 = 0.5%, 100 = 1%). Default ~50. Hard-capped at 500 (5%) — anything higher is almost always a sandwich-bait misconfiguration. If a legitimate thin-liquidity route genuinely needs >1%, also pass `acknowledgeHighSlippage: true`. | |
| acknowledgeHighSlippage | No | Opt-in flag required when slippageBps > 100 (1%). Forces the caller to state that an unusually-high slippage is intentional — the default rejects the tx to protect the user from MEV sandwich attacks. | |
| exchanges | No | Restrict LiFi routing to a specific set of DEX/exchange aggregators. Common values: "1inch", "sushiswap", "uniswap", "paraswap", "0x", "kyberswap", "odos", "openocean". When the user explicitly names a DEX ("swap on 1inch"), pass it here — without a filter, LiFi silently picks the best-output route regardless of what the user asked for. Multiple entries OR'd. If no route exists via the requested exchange(s) the call errors clearly; agent should offer to retry without the filter. | |
| bridges | No | Restrict cross-chain routing to a specific set of bridge protocols. Common values: "across", "stargate", "hop", "cbridge", "amarok", "polygon", "arbitrum-bridge". Mirrors `exchanges` but for bridge selection. Only applies to cross-chain routes; ignored for intra-chain swaps. | |
| excludeExchanges | No | Blocklist version of `exchanges` — DEXes/aggregators LiFi must avoid. Use when the user says "not via 1inch" or "avoid Sushiswap". Independent of `exchanges`: pass both to constrain to allowlist minus blocklist. Pass-through to LiFi's `denyExchanges`. | |
| excludeBridges | No | Blocklist version of `bridges` — bridge protocols LiFi must avoid on cross-chain routes. Pass-through to LiFi's `denyBridges`. | |
| order | No | Route ranking criterion. RECOMMENDED (default) — LiFi's mix of price + safety. CHEAPEST — pick the route with the highest output amount; use this for "best rate available" intent. FASTEST — minimize execution time (relevant for cross-chain bridges where settlement varies). SAFEST — prefer the most-vetted tool set. Pass-through to LiFi's `order`. |