Sato Hub: Build Onchain & Crypto Agents

Choose a venue for a swap, with the fee disclosed

onchain_agent_route_swap

Read-onlyIdempotent

USE WHEN an agent wants a swap QUOTE with the venue chosen by liveness, verification and price and the fee disclosed. Asks every aggregator adapter that quotes on the chain, in parallel, and returns the chosen venue's quote and calldata. NOT FOR a swap checked against token, venue and recipient verdicts and a spending policy, with a simulated unsigned transaction and a receipt (use onchain_agent_swap instead), a launch venue (use onchain_agent_route_launch), or a liquidity pool (use onchain_agent_route_lp).

RULE ENFORCED: a route is a RECOMMENDATION, not a verdict and not an assurance. chosen_by names every field it was chosen on — liveness, the observed record of Sato Hub's OWN daily checks (never "uptime"), verification state, then quoted price — with the field each was read from and checked_at. Nothing here is called best, safe or guaranteed. A quote is a quote, not a fill.

NON-CUSTODIAL: this tool NEVER signs, holds, moves or broadcasts funds. It returns calldata the caller may sign. THE FEE: Sato Route swaps cost 3 bps stable-to-stable, 15 bps between majors (a chain's native coin such as ETH or SOL, its wrapped form, or a stablecoin), 75 bps with any other token and 25 bps cross-chain (75 bps when either side is any other token), taken as a parameter on the aggregator's own quote inside the transaction you sign; a failed, reverted or unsigned trade pays nothing. A token launch carries a disclosed share of the creator's LP fee, stated as fee.bps on every launch response, including when it is 0. Sato OS charges 3 / 15 bps on its own spot swap rail and a 3 bps perp builder fee, with no cross-chain tier. Some venues keep a share or pay later, and every quote says which. It is stated in disclosure before anything is signed.

RETURNS (json): { route: { slug, name, listed, sato_url, liveness, observed_success_pct, install_verified }, quote: { venue, amount_in, amount_out, token_in, token_out, chain, calldata, tx, source_url }, sato_fee_bps, sato_fee_recipient, sato_fee_side ("in" | "out" | null: the leg the fee is taken on), sato_fee_token, sato_fee_tier ("stable" | "major" | "token" | "cross_chain" | null: the schedule tier the rate came from), referral ({ referrer, share_of_fee_bps, payout } when a referrer was named and recorded, else null), price_impact, disclosure, chosen_by: [{ signal, value, source_field }], checked_at, alternatives, caveat, preflight, unavailable_venues, rules }. When no adapter answered: { unavailable, tried: [{ venue, reason }], checked_at, caveat }.

Example: { chain: "Solana", token_in: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", token_out: "So11111111111111111111111111111111111111112", amount: "1000000" }

Input Schema

Name	Required	Description	Default
`chain`	Yes	Chain display name as the directory writes it. Swapped for the agent bots: Base, BNB Chain, Arbitrum, Polygon and Solana. A short spelling ('bnb', 'bsc', 'matic', 'arbitrum one') is read as the same chain; other chains the venues quote work by their display name, e.g. 'Ethereum'.
`taker`	No	The address that would sign. Some venues only return calldata when it is given; nothing is ever signed here.
`amount`	Yes	Sell amount in the INPUT token's base units (e.g. 1000000 = 1 USDC at 6 decimals).
`referrer`	No	Optional referral: a referral name (like sunny-otter) or a payout address (a Base 0x address or a Solana address) that earns 30% of the Sato fee on this swap, paid weekly in USDC once Sato Hub has read the fee onchain. It needs the taker (the address that will sign) to be named too, and it applies to same-chain swaps only: without a taker the answer carries referral null. The trade and the fee address do not change. A bad address or a name Sato Hub has no record of is refused as referrer_invalid; one of Sato Hub's own fee addresses is ignored, and so is a retired name (referral null). The answer's `referral` echoes what was recorded (null when none).
`token_in`	Yes	Input token: a contract address (or Solana mint), or a symbol for the well-known stablecoins.
`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.
`response_format`	No	Text format; structuredContent is JSON either way.	markdown

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 12, 2026

changedInput schema / properties / chain / description

Previous value: -"Chain display name as the directory writes it, e.g. 'Base', 'Ethereum', 'Solana'."New value: +"Chain display name as the directory writes it. Swapped for the agent bots: Base, BNB Chain, Arbitrum, Polygon and Solana. A short spelling ('bnb', 'bsc', 'matic', 'arbitrum one') is read as the same chain; other chains the venues quote work by their display name, e.g. 'Ethereum'."

Changed1 schema field changedOct 12, 2026

changedInput schema / properties / referrer / description

Previous value: -"Optional referral: a payout address (a Base 0x address or a Solana address) that earns 30% of the Sato fee on this swap, paid weekly in USDC once Sato Hub has read the fee onchain. It needs the taker (the address that will sign) to be named too, and it applies to same-chain swaps only: without a taker the answer carries referral null. The trade and the fee address do not change. A bad address is refused as referrer_invalid; one of Sato Hub's own fee addresses is ignored. The answer's `referral` echoes what was recorded (null when none)."New value: +"Optional referral: a referral name (like sunny-otter) or a payout address (a Base 0x address or a Solana address) that earns 30% of the Sato fee on this swap, paid weekly in USDC once Sato Hub has read the fee onchain. It needs the taker (the address that will sign) to be named too, and it applies to same-chain swaps only: without a taker the answer carries referral null. The trade and the fee address do not change. A bad address or a name Sato Hub has no record of is refused as referrer_invalid; one of Sato Hub's own fee addresses is ignored, and so is a retired name (referral null). The answer's `referral` echoes what was recorded (null when none)."

Changed1 schema field changedOct 10, 2026

addedInput schema / properties / referrer

Added value: +{
+  "description": "Optional referral: a payout address (a Base 0x address or a Solana address) that earns 30% of the Sato fee on this swap, paid weekly in USDC once Sato Hub has read the fee onchain. It needs the taker (the address that will sign) to be named too, and it applies to same-chain swaps only: without a taker the answer carries referral null. The trade and the fee address do not change. A bad address is refused as referrer_invalid; one of Sato Hub's own fee addresses is ignored. The answer's `referral` echoes what was recorded (null when none).",
+  "maxLength": 64,
+  "type": "string"
+}

Changed1 schema field changedOct 8, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedSep 30, 2026

changedInput schema / properties / response_format / description

Previous value: -"Output format: 'markdown' (default) or 'json'."New value: +"Text format; structuredContent is JSON either way."

AddedSep 11, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/non-destructive/idempotent, and the description adds substantial non-obvious behavior: it never signs, holds, moves or broadcasts funds; it returns calldata the caller may sign; a failed, reverted or unsigned trade pays nothing; the fee schedule (3/15/75/25 bps) and where in the transaction it is taken; and that a route is a recommendation, not an assurance. This is well beyond what annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured and front-loaded with USE WHEN / NOT FOR / RULE ENFORCED / NON-CUSTODIAL / THE FEE / RETURNS headings, and the RETURNS section legitimately substitutes for a missing output schema. However, the sentences about token-launch creator LP shares and Sato OS perp builder fees are tangential to this specific tool and could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully documents the return shape (route, quote, fee fields, referral, chosen_by, unavailable fallback) and the non-custodial contract, plus an example invocation. For an 8-param routing tool with meaningful behavioral nuance, nothing an agent needs to call it correctly appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly (including referral fallbacks and taker semantics). The description adds little parameter-level meaning beyond a concrete example using chain/token_in/token_out/amount, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — obtain a swap QUOTE with the venue chosen by liveness, verification and price — and explicitly distinguishes itself from onchain_agent_swap, onchain_agent_route_launch and onchain_agent_route_lp by name. An agent can identify this tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'USE WHEN' clause plus a 'NOT FOR' clause naming three sibling alternatives and the conditions that select each. Nothing about when to pick this vs. a verdict-checked swap is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Sato Hub: Build Onchain & Crypto Agents tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Choose a venue for a swap, with the fee disclosed

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources