Skip to main content
Glama

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

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "chain": "<chain>",
      "token_in": "<token_in>",
      "token_out": "<token_out>",
      "amount": "<amount>"
    },
    "name": "onchain_agent_route_swap"
  }
}

Input Schema

NameRequiredDescriptionDefault
chainYesChain 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'.
takerNoThe address that would sign. Some venues only return calldata when it is given; nothing is ever signed here.
amountYesSell amount in the INPUT token's base units (e.g. 1000000 = 1 USDC at 6 decimals).
referrerNoOptional 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_inYesInput token: a contract address (or Solana mint), or a symbol for the well-known stablecoins.
token_outYesOutput token: a contract address (or Solana mint), or a symbol.
slippage_bpsNoSlippage tolerance in basis points. Passed through to the venue.
response_formatNoText format; structuredContent is JSON either way.markdown

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • 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'."
  2. Changed1 schema field changed
    • 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)."
  3. Changed1 schema field changed
    • 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"
      +}
  4. Changed1 schema field changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  5. Changed1 schema field changed
    • changedInput schema / properties / response_format / description
      Previous value: -"Output format: 'markdown' (default) or 'json'."New value: +"Text format; structuredContent is JSON either way."
  6. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds far more: it never signs or moves funds, quotes are recommendations rather than verdicts, the full fee schedule (3/15/75/25 bps with tier definitions), that fees ride inside the aggregator's calldata, and that failed/unsigned trades pay nothing. The "no adapter answered" shape and the disclosure-before-signing guarantee are precisely the behavioral traits annotations cannot express.

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?

Heavily front-loaded with USE WHEN / NOT FOR before any prose, and sectioned into RULE ENFORCED, NON-CUSTODIAL, THE FEE and RETURNS. It is dense and the ALL-CAPS emphasis plus near-redundant reassurances ("a quote is a quote, not a fill"; "Nothing here is called best, safe or guaranteed") cost it a point, but no section is filler for a financial tool.

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?

There is no output schema, so the description carries the full return contract and does so: the complete JSON shape, the degraded `unavailable`/`tried` shape, what each fee field means, and what `chosen_by` records with `checked_at`. For a quote tool with eight parameters, nothing an agent needs before calling is 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 chain, taker, amount, referrer, tokens and slippage thoroughly; baseline 3 applies. The description adds little parameter-specific detail beyond a single input example, though the RETURNS block implicitly clarifies that `referral` mirrors the referrer parameter and that sato_fee_tier reflects the fee schedule.

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?

"USE WHEN an agent wants a swap QUOTE with the venue chosen by liveness, verification and price and the fee disclosed" names a specific verb (quote), resource (swap route), and selection criteria. It explicitly differentiates from the three sibling routing tools (onchain_agent_swap, route_launch, route_lp) so an agent can route without opening either 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?

The USE WHEN / NOT FOR pair gives both the triggering condition and the alternatives with the exact sibling to use instead (verdict-checked swap, launch venue, liquidity pool). This is the explicit when/when-not/alternative structure at full strength.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.