USE 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. sato_fee_side ("in" or "out") and sato_fee_token say which leg the fee is taken on and in what token: on KyberSwap, Jupiter and 0x, when exactly one side of the trade is a stablecoin or the chain's native asset (in Sato Hub's tables) the fee is taken on THAT side; on other venues, or when neither side is, it is taken on the leg disclosure names, in the token sato_fee_token names. They are part of the signed answer. price_impact is the venue's own reading of how far the output sits from the input (reported_bps where the venue reports one, usd_value_gap_bps from its USD valuations, which include fees); null is unknown.

PINNING A VENUE: pass venue to quote one venue only. If it cannot answer, is not offered on the chain or is refused, the answer names it and says why; no other venue is ever tried in its place.

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, pinned_venue (only when venue was set), venue, chain, token_in, token_out, amount_in, amount_out, sato_fee_bps, sato_fee_recipient, sato_fee_side, sato_fee_token, sato_fee_tier, referral, price_impact, 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, code? } (code "fee_side_unavailable" when neither side is a stablecoin or the native coin: swap through USDC or ETH/SOL).

Example: { chain_in: "Base", token_in: "USDC", token_out: "WETH", amount_in: "1000000", mode: "recommend" }