Quote a swap, check it against a policy, and get an unsigned transaction
onchain_agent_swapUSE WHEN an agent is about to swap and wants the venue chosen, the fee disclosed, and the trade CHECKED before anything is signed. Two modes: recommend returns the choice, the fee sentence and the verdicts and NEVER a transaction; build-tx returns an UNSIGNED transaction, and only when the gate allowed it and a simulation did not revert.
NON-CUSTODIAL: this tool NEVER signs, holds, moves or broadcasts funds, and it never asks for a key. What comes back is an unsigned object the caller signs or discards. The response signature proves Sato Hub produced those bytes; it is not a claim that anyone authorised a transfer.
WHAT IS CHECKED, and under what: four targets — token_in, token_out, the venue endpoint, and the recipient — each with its own verdict, the rule id that produced it and the reason. Then the caller's policy (caps per trade and per period, allowed chains, tokens, venues, recipients, slippage and deadline). Manage policies at https://satohub.ai/api/swap/policies; with no stored policy the default applies.
UNKNOWN REFUSES BY DEFAULT. A target we could not read, or a simulation that could not run, WITHHOLDS the transaction unless the policy says otherwise — and the response says which lane could not be read. "We did not check" and "we checked and it is fine" never look alike. A refusal is an ANSWER: it is not an error, and retrying it unchanged will refuse again.
A COUNTERPARTY WITH NO PASSPORT IS no_record. That is the ordinary case and is not a finding against the address. A Passport is self-registered, and wallet_verified proves control of a key, never anything about the product behind it. There is no list of trusted counterparties here.
THE FEE: disclosed verbatim in disclosure, per venue, before anything is signed — a fee sentence has to be true for the venue it describes. A trade that is never signed pays nothing.
RECEIPT: a build-tx response is recorded and receipt_url points at the public record of what was checked, under which policy, at what instant. A receipt is not a claim the trade filled.
Returns (json): { mode, lane, route_id, venue, chain, token_in, token_out, amount_in, amount_out, sato_fee_bps, sato_fee_recipient, disclosure, chosen_by, alternatives, unavailable_venues, preflight, gate: { verdict, refusals, policy_id, policy_version }, gate_result: { allowed, verdicts, verdicts_digest, counterparty, policy }, simulation, tx | null, withheld: { reason, rule } | null, receipt_url, non_custodial, checked_at, caveat, meta: { signature } }. When no adapter answered: { unavailable, tried, checked_at, caveat }.
Example: { chain_in: "Base", token_in: "USDC", token_out: "WETH", amount_in: "1000000", mode: "recommend" }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | `recommend` (default) never returns a transaction, whatever the gate said. `build-tx` returns an unsigned one, and only when the gate allowed it AND the simulation did not revert. | |
| taker | No | The address that would sign. Some venues only return a transaction when it is given; nothing is ever signed here. | |
| chain_in | Yes | Source chain as the directory writes it, e.g. 'Base', 'Ethereum', 'Solana'. | |
| deadline | No | Unix seconds the quote should stay good until. Omit for the venue's own default. | |
| token_in | Yes | Input token: a contract address (or Solana mint), or a symbol for the well-known stablecoins. | |
| amount_in | Yes | Sell amount in the INPUT token's base units (1000000 = 1 USDC at 6 decimals). A string, because a uint256 does not survive a JSON number. | |
| chain_out | No | Destination chain. Omit, or repeat chain_in, for a same-chain swap. A different value is the cross-chain lane, and the two lanes are never compared with each other. | |
| recipient | No | Where the output goes. Omit to send to the taker. A recipient we hold no record of is `no_record` — an absence of evidence, and on its own never a refusal. | |
| 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. A policy may cap it, and then the refusal states the cap and the value. | |
| usd_notional | No | USD notional of amount_in, when YOU already hold a price. Omitted is unknown, never zero — a USD cap simply does not bite without it. | |
| response_format | No | Output format: 'markdown' (default) or 'json'. | markdown |