swap_build
Build a signable/sendable plan for a swap. This is the tool that does the work — an agent that only knows this tool can execute a swap end to end. Quotes and builds the best route in one call when quoteId is omitted (recommended): a route with GAIN first, re-quoting up to 3 rounds total before accepting one without gain, the same rule as Invoice; pass quoteId from a prior swap_quote to build exactly that route instead. No API key required: pass the wallet that will sign. A machine credential is optional and only raises your limit from the per-IP cap to the credential budget. Four things to hold onto: 1. steps[] are ORDERED and REQUIRED. Skipping an approve step guarantees a revert. 2. If simulation.status is "approval_required", sign/send only the approve step(s), do not report them as the swap execution, then call swap_build again with quoteId set to the quote.id of that build (the approved route; without it a fresh quote may pick another provider whose spender you never approved). If it is "incomplete", do not sign anything: the transaction was never independently verified. 3. If a step has type "signature", there is no transaction and never will be one for that step — what exists afterward is the uid from report_execution, not a hash. 4. If the provider is cowswap and the token sold is the chain's native asset, the transaction only REGISTERS the order — a successful receipt is not a successful swap. Use swap_status, not the receipt, to know what actually happened. 5. routeSwitch, when present, means the route you asked for refused to build (it hit its request limit) and the plan was built with another provider instead: {from, to, reason}. The quote in the plan is the route that will actually be signed. If the user picked that route themselves, say which provider replaced it before they sign.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Human decimal amount, e.g. "100". Use this OR amountRaw, not both. | |
| wallet | Yes | Wallet that will sign. Required for builds and EVM execution/history calls. On an anonymous EVM quote, pass it to make the returned quoteId executable; without it the quote is indicative. | |
| chainId | Yes | EVM: integer from GET /v1/chains (1, 10, 56, 100, 137, 8453, 42161, 43114, 130). Solana: string from GET /v1/svm/chains ("solana-mainnet"). | |
| quoteId | No | Optional: build exactly this route from a prior swap_quote, instead of quoting fresh. | |
| tokenIn | No | Contract address (Solana: mint), or symbol (case-insensitive). A symbol matching more than one token on this chain fails with ambiguous_token and every candidate — pick the address you meant and retry. On Solana only VERIFIED tokens resolve by symbol, because there anyone can mint a token using another one's symbol; an unverified token has to be named by its mint. | |
| receiver | No | Optional: deliver the output to this address instead of the signing wallet. Only providers with supportsReceiver true on the resulting quote honor it — others are left out of quotes[] entirely rather than risk sending to the wrong address. supportsReceiver is present on Solana quotes too, so read it instead of assuming. On Solana, selling into native SOL with a separate destination is refused on every provider (receiver_native_sol_unsupported): closing the wrapped-SOL account sends balance and rent to whoever signs. Ask for wSOL instead. Building with a receiver needs the paying wallet's signed authorization first (destination_challenge, then destination_authorize), or the build fails with destination_not_authorized. | |
| tokenOut | No | Contract address, or symbol. | |
| amountRaw | No | Raw integer string in tokenIn's smallest unit. | |
| slippageBps | No | Optional, a sane per-pair default applies when omitted. | |
| maxSlippageBps | No | Optional ceiling, 0-10000, enforced on every future refresh of this build — once set it never loosens. |