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. `build-tx` WRITES a receipt row. NOT FOR a plain quote with no policy gate (use onchain_agent_route_swap instead), a token launch (use onchain_agent_route_launch), or a liquidity pool (use onchain_agent_route_lp). 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`: the ordinary case, not a finding against the address. 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 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 is a stablecoin or the chain's native asset (in Sato Hub's tables) the fee is taken on THAT side; otherwise on the leg `disclosure` names. They are part of the signed answer. `price_impact` is the venue's own reading (`reported_bps`, or `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, the reply names it and says why, and no other venue is tried. CROSS-CHAIN: `recipient` is the destination address (deBridge builds for it; Solana needs it); `recipient_owner: "self"` declares it yours (RCPT5). Native coin = 0x000…0. 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, chain_out, recipient, bridge ({ protocol, order_id, fix_fee_wei, take_amount, allowed_taker_dst }; null off a cross-chain deBridge order), 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 the chain's own native coin). Example: { chain_in: "Base", token_in: "USDC", token_out: "WETH", amount_in: "1000000", mode: "recommend" }