Build unsigned swap transaction
build_swap_txRead-only
Build the UNSIGNED transaction for the best (or chosen) route, plus any ERC-20 approval needed first and an eth_call simulation when an RPC is configured. Never signs, never holds keys or funds, never asks for keys: hand the result to the user's wallet (broadcast_tx can then relay the signed bytes unchanged). Swap-chan packs the bag; you carry it through the gate. Result includes display markdown with chan images and a swapchan.com link: show it to the user. How to combine this with the other tools: swapchan_playbook (workflows: find-money, best-swap, rebalance, revoke-approvals, bridge-stuck, token-safety, recover-old-wallet).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"fromChainId": "<fromChainId>",
"toChainId": "<toChainId>",
"fromToken": "<fromToken>",
"toToken": "<toToken>",
"taker": "<taker>"
},
"name": "build_swap_tx"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Alias of `partner`. | |
| taker | Yes | Wallet address that will sign and send the transaction | |
| amount | No | Human-readable amount of fromToken to sell, e.g. "1.5". Provide this OR amountBaseUnits. | |
| partner | No | Optional SwapChan partner/affiliate id (from swapchan.com/partners). Quotes are attributed to it and the swapUrl carries ?ref= so the partner earns 5 bp (half of SwapChan's fee). Agent builders: register via POST https://api.swapchan.com/partners with the operator's payout address. | |
| quoteId | No | Reuse a quoteId from get_quote/compare_routes (still re-quotes if it expired) | |
| toToken | Yes | Token address. Native gas token: 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE on EVM chains (ETH, POL...), 11111111111111111111111111111111 for SOL, bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8 for BTC, T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb for TRX, ltc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqp9ysmq for LTC, D596YFweJQuHY1BbjazZYmAbt8jJPbKehC for DOGE, qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqfnhks603 for BCH. SPL mints and TRC-20 addresses work as-is (e.g. Solana USDC EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v, Tron USDT TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t). | |
| provider | No | Force a specific provider from compare_routes instead of the best route | |
| fromToken | Yes | Token address. Native gas token: 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE on EVM chains (ETH, POL...), 11111111111111111111111111111111 for SOL, bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8 for BTC, T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb for TRX, ltc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqp9ysmq for LTC, D596YFweJQuHY1BbjazZYmAbt8jJPbKehC for DOGE, qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqfnhks603 for BCH. SPL mints and TRC-20 addresses work as-is (e.g. Solana USDC EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v, Tron USDT TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t). | |
| recipient | No | Address that receives the output on toChainId. Required for real execution when the destination is a different VM (e.g. EVM -> Solana/Bitcoin/Tron); omitted = indicative quote only. | |
| toChainId | Yes | Destination chain id. Same as fromChainId for a same-chain swap; different for a cross-chain route. | |
| fromChainId | Yes | Chain id: 1 Ethereum, 8453 Base, 42161 Arbitrum, 10 Optimism, 137 Polygon, 56 BNB Chain, 43114 Avalanche, 59144 Linea, 534352 Scroll, 792703809 Solana, 8253038 Bitcoin, 728126428 Tron, plus THORChain-only 2000000002 Litecoin, 2000000003 Dogecoin, 2000000145 Bitcoin Cash (either side, THORChain only; sending them needs the native coin and returns an unsigned PSBT on /build or a deposit address from POST /utxo/deposit with the required memo). Non-EVM chains route via Relay, LI.FI and THORChain. | |
| slippageBps | No | Max slippage in basis points (50 = 0.5%). Default 50, cap 300. | |
| amountBaseUnits | No | Exact amount in the token's smallest unit (wei). Provide this OR amount. | |
| allowForeignRecipient | No | Same-chain only: set true to pay out to `recipient` when it is not the taker. Off by default; the payout is pinned to the taker and a different recipient is refused. |