Choose a venue for a swap, with the fee disclosed
onchain_agent_route_swapUSE WHEN an agent needs to execute a swap and wants the venue chosen by liveness, verification and price, with the fee disclosed. Asks every aggregator adapter that quotes on the chain, in parallel, and returns the chosen venue's quote and calldata.
RULE ENFORCED: a route is a RECOMMENDATION, not a verdict and not an assurance. chosen_by names every field it was chosen on — liveness, the observed record of Sato Hub's OWN daily checks (never "uptime"), verification state, then quoted price — with the field each was read from and checked_at. Nothing here is called best, safe or guaranteed. A quote is a quote, not a fill.
NON-CUSTODIAL: this tool NEVER signs, holds, moves or broadcasts funds. It returns calldata the caller may sign. THE FEE: Sato Route swaps cost 3 bps stable-to-stable, 15 bps between majors (a chain's native coin such as ETH or SOL, its wrapped form, or a stablecoin), 75 bps with any other token and 25 bps cross-chain (75 bps when either side is any other token), taken as a parameter on the aggregator's own quote inside the transaction you sign; a failed, reverted or unsigned trade pays nothing. A token launch carries a disclosed share of the creator's LP fee, stated as fee.bps on every launch response, including when it is 0. Sato OS charges 3 / 15 bps on its own spot swap rail and a 3 bps perp builder fee, with no cross-chain tier. Some venues keep a share or pay later, and every quote says which. It is stated in disclosure before anything is signed.
Returns (json): { route: { slug, name, listed, sato_url, liveness, observed_success_pct, install_verified }, quote: { venue, amount_in, amount_out, token_in, token_out, chain, calldata, tx, source_url }, sato_fee_bps, sato_fee_recipient, sato_fee_side ("in" | "out" | null: the leg the fee is taken on), sato_fee_token, sato_fee_tier ("stable" | "major" | "token" | "cross_chain" | null: the schedule tier the rate came from), referral ({ referrer, share_of_fee_bps, payout } when a referrer was named and recorded, else null), price_impact, disclosure, chosen_by: [{ signal, value, source_field }], checked_at, alternatives, caveat, preflight, unavailable_venues, rules }. When no adapter answered: { unavailable, tried: [{ venue, reason }], checked_at, caveat }.
Example: { chain: "Solana", token_in: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", token_out: "So11111111111111111111111111111111111111112", amount: "1000000" }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chain | Yes | Chain display name as the directory writes it, e.g. 'Base', 'Ethereum', 'Solana'. | |
| taker | No | The address that would sign. Some venues only return calldata when it is given; nothing is ever signed here. | |
| amount | Yes | Sell amount in the INPUT token's base units (e.g. 1000000 = 1 USDC at 6 decimals). | |
| referrer | No | Optional referral: a payout address (a Base 0x address or a Solana address) that earns 30% of the Sato fee on this swap, paid weekly in USDC once Sato Hub has read the fee onchain. It needs the taker (the address that will sign) to be named too, and it applies to same-chain swaps only: without a taker the answer carries referral null. The trade and the fee address do not change. A bad address is refused as referrer_invalid; one of Sato Hub's own fee addresses is ignored. The answer's `referral` echoes what was recorded (null when none). | |
| token_in | Yes | Input token: a contract address (or Solana mint), or a symbol for the well-known stablecoins. | |
| token_out | Yes | Output token: a contract address (or Solana mint), or a symbol. | |
| slippage_bps | No | Slippage tolerance in basis points. Passed through to the venue. | |
| response_format | No | Text format; structuredContent is JSON either way. | markdown |