onchain_agent_swap

ai.satohub/onchain-agents · Verify this server

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. 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" }