How does Sato Swap decide, and what does it hand back?

1. What is checked

Four targets, each with its own verdict — go, caution, no or unknown. They are reported separately and never blended into a single score, because the thing you need to know is which one did not clear.

Unknown is never zero. It means we hold no record, or a lane could not be read. It is not a finding against the target — and under the default policy it refuses, which is the product: an agent should not trade on a reading nobody made.

2. The policy model

A policy is an operator’s standing answer to what a given caller may swap, how much, and what happens when we hold no record. It is pure — no clock but the one passed in, no network — so the HTTP lane and the MCP lane cannot drift apart. Policies are managed at /api/swap/policies.

• Strict on unknown, permissive on empty. An empty allowlist means “any, subject to the verdict” — an operator who has not listed tokens has not thereby refused every token. But unknown_verdict defaults to refuse. That asymmetry is deliberate.
• Caution allows by default. A caution is the normal state of most of the long tail; refusing it out of the box would refuse nearly every real trade while telling the operator nothing new. Set caution_verdict to refuse for the stricter posture, and the refusal then says it was your rule.
• It never prices a token. Caps are in base units of a named token. A USD cap bites only when the caller hands us a price it already holds; with no price the notional is unknown and is resolved by unknown_verdict, never silently as zero.
• It never refuses on a missing Passport alone. require_passport defaults to false. No record is no record.
• Every refusal names its rule. The rule id, the limit and the observed value travel with it, so a refusal can be argued with rather than only obeyed.

3. Execution modes

4. Simulation, and what “not simulated” means

Before build-tx hands back a transaction, a node is asked what would happen if it were sent — without sending it. Which lane ran is always reported.

A simulation that did not revert says one thing only: at that block, from that address, this call did not revert. It is not a prediction of the fill, the price or the outcome.

5. The fee, per venue

3 bps when both legs are stablecoins Sato Hub recognises, 15 bps when either leg is volatile. The fee is a parameter on the venue’s own quote — taken inside the swap transaction by that venue’s router, to the Sato fee address 0xcEE53Eb001d4d1743EF9df333Dcf45bC38622bE9. It is stated on every quote before anything is signed. A failed, reverted or unsigned trade pays nothing.

On several venues the flat sentence is not the whole truth: the venue keeps a share, charges a different leg, or pays later and only conditionally. Each qualifier below is quoted from that venue’s own documentation, and is sent with the quote rather than kept here. None of these numbers is observed by us — what actually lands is a separate on-chain reading, and a receivable is never recorded as received.

6. Venues and lanes

Derived from the adapter set when this page was rendered — each adapter’s declared lanes and its own supports() answer. A same-chain quote and a cross-chain quote are different products and are never ranked against each other: different settlement, different finality, different failure mode. The other lane comes back as a separate offer.

A chain listed here is one the adapter will attempt. The venue’s own error is better evidence of its coverage than our guess, so an unconfirmed chain is asked rather than pre-refused — and whatever the API says is reported as the reading it is.

7. The ladder

Inside a lane, venues are ranked by: retired and dormant excluded outright; then whether the venue answered with a quote at all; then liveness; then the observed success rate of Sato Hub’s own daily checks over at least fourteen days; then verification state; then quoted output; then name, so the same data always yields the same route. Price ranks below liveness on purpose — a venue that quotes a better number and then does not answer is worth less than one that answers.

The observed success rate is the share of our checks that succeeded. It is never called uptime: a failure can be on our side. The whole ladder travels back in chosen_by, each signal with the field it was read from, so a route can be re-derived instead of trusted.

8. What a receipt binds

Version 2 of the quote binding (Sato Swap, 2026-09-15) adds what was checked to what was returned. The version travels in the row and inside the signed message, so a holder rebuilds exactly one construction and checks it against /.well-known/jwks.json. Rows minted before the change keep verifying under version 1 forever.

Everything that can change after the quote — status, tx hash, props — is deliberately outside the signature. A signature over a mutable row would fail on the first honest update and teach people to ignore it. A receipt is evidence of what we said and what we checked; it is not evidence that a fee landed, a trade settled, or that anyone authorised a transfer.

9. Non-custodial, by construction

Every response is an unsigned object. No module in the path holds a key, signs a transaction or broadcasts one. The Ed25519 signature on a response proves who said it — never that anyone authorised a transfer.

10. What Sato Swap does not do

11. Licence notes — venues not offered

A venue is absent for a reason, and the reason is written down. In every case below the blocker is permission or attribution, not an opinion about the venue.

Reading it from an agent

• POST /api/swap/quote — mode recommend or build-tx, signed response, shape published at /schemas.
• onchain_agent_swap over the MCP server — the same code, write-labelled because build-tx produces something signable.
• GET /api/swap/receipts/<id> — the public receipt, and /swap renders it.
• /api/openapi.json — the machine contract for the public operations.