Swap
Swap quotes and builds a route between two tokens, same-chain or cross-chain, and fails closed when no route exists.
Swap exchanges one token for another. It resolves both sides of the trade to their real on-chain addresses, quotes a route through a bridge-aggregated router, and only then builds the operation you sign.
Resolving tokens and quoting a route
Native ETH is resolved through a sentinel address; every other token is resolved by its own address,
or by a small built-in registry for the most common stablecoins. Once both sides are resolved, the
route is quoted through Botanary's route-aggregation provider. If no route exists between the two
tokens, the build fails closed with a route_unavailable reason rather than returning something that
would fail on-chain - the same build-time decline described in
Decline reasons.
TODO: the intended scope of Swap (arbitrary token pairs versus a narrower, stablecoin-focused design) is not settled - the platform's public API contract and the live route-building behavior agree on "any token to any token, same-chain or cross-chain," but this needs sign-off from engineering before it's treated as a permanent guarantee rather than today's observed behavior.
Cross-chain swaps
A swap's destination isn't required to be the same chain it started on - if the token you're swapping into specifies a different chain, the route is quoted and built to land there instead. The bridge leg of a cross-chain swap is tracked separately from the operation you signed, by the source transaction's own hash, since that leg can still be in flight after your signed operation is already mined.
One signature, even with an approval
A swap that needs a token approval batches that approval and the router call into a single operation
- one signature covers both, the same way a USDT-gassed send batches its own approval in.
Pre-graduation launchpad tokens
A launchpad token that hasn't graduated yet - still trading on a bonding curve rather than a DEX pool
- can't be routed through the aggregator. Swap detects this case and builds a direct bonding-curve buy or sell instead, with a price-derived floor on the amount you receive. See Launchpad for what graduation means.
Slippage protection
The minimum amount you'll accept out of a swap is baked directly into the router call itself, and it's enforced on-chain by the router contract - not by a separate check Botanary performs at build time. There's no distinct "slippage exceeded" decline reason in this version; if a route can't meet your floor, the swap simply won't execute on-chain.
Quoting without building
Getting a quote doesn't build anything and needs no signature. If a route genuinely doesn't exist for a pair, the quote endpoint still responds normally - it just reports the pair as unsupported, rather than returning an error.