MCP and agents

Connect

The endpoint is https://api.tide.ad/mcp (Streamable HTTP, stateless). Each client below starts with the keyless setup, which needs no account. The keyed setup under it adds your key for higher limits and sql.

Claude Code

claude mcp add --transport http tide https://api.tide.ad/mcp

claude mcp add --transport http tide https://api.tide.ad/mcp --header "Authorization: Bearer YOUR_API_KEY"

Claude Desktop

In Settings, open Connectors, choose Add custom connector and paste https://api.tide.ad/mcp. Or add it to claude_desktop_config.json:

{
  "mcpServers": {
    "tide": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.tide.ad/mcp"]
    }
  }
}

{
  "mcpServers": {
    "tide": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.tide.ad/mcp", "--header", "Authorization: Bearer YOUR_API_KEY"]
    }
  }
}

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

{
  "mcpServers": {
    "tide": { "url": "https://api.tide.ad/mcp" }
  }
}

{
  "mcpServers": {
    "tide": {
      "url": "https://api.tide.ad/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

VS Code

Add this to .vscode/mcp.json.

{
  "servers": {
    "tide": { "type": "http", "url": "https://api.tide.ad/mcp" }
  }
}

{
  "servers": {
    "tide": {
      "type": "http",
      "url": "https://api.tide.ad/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

A header left as Bearer YOUR_API_KEY, or an empty Bearer, is treated as keyless, so a pasted keyed snippet still works before you have a key.

Then ask in plain words, for example What does example.sui hold, and who funded it? or Is DEEP safe to buy?

Keyless and keyed

Get a free key with the Get an API key link at the top of this page. An agent can get its own by signing one message with any Sui key: keys for agents. initialize and tools/list are free; each tool call costs the flat credits below.

Tools

The answer tools come first. Each one answers a whole question in one call.

Specialist tools cover the rest of the chain.

Every tool is read only: tide never signs and never sends a transaction. The build tools return unsigned bytes that your own wallet signs. Wallets take a 0x address, a name.sui or an @name. Coins take a coin type like 0x2::sui::SUI or a symbol like DEEP; verified coins win ties.

Act: build, check, sign

An agent can go from a goal to a transaction its own wallet signs. tide finds the options, builds the transaction with each protocol's own Move calls (package ids follow the protocol's upgrades), picks your gas coins, sets the budget, dry-runs the exact bytes on current mainnet state and runs the pre-sign check on them. You get the bytes and the verdict together. tide never signs and never holds keys.

• Amounts are whole coins: 1.5 means 1.5 USDC. tide resolves the decimals.
• steps runs several actions in one transaction. A step without amount takes the previous step's output, so a swap into USDC and a supply to NAVI happen together or not at all.
• If the dry run fails, or the check says danger, there are no bytes: the tool returns the reason (would_fail or unsafe) with the check. A caution verdict still returns bytes; read the findings first.
• Sign tx_bytes soon. Gas coins and quotes are current when built; build again if the wallet changed.

Worked example: $5,000 at about 6%, low risk

1. Ask what pays about 6% at low risk.

{ "asset": "USDC", "max_tier": 2, "sort": "apy" }

2. Ask for a plan for the amount, and have tide build the top option for your wallet.

{ "amount_usd": 5000, "asset": "USDC", "target_apy": 6, "max_risk_tier": 2,
  "build": true, "sender": "0xYOUR_WALLET" }

{
  "summary": "For $5,000 in USDC: 6 options. Best fit is USDC supply on NAVI at 5.89% (risk tier 1), about $295 over 365 days.",
  "built": [{
    "rank": 1, "name": "USDC supply on NAVI",
    "description": "Supplies 5,000 USDC to NAVI. The wallet's NAVI account earns the supply rate; withdraw any time while the market has idle cash.",
    "verdict": "safe",
    "tx_bytes": "AAAJ...",
    "spends": [{ "coin": "USDC", "amount": 5000 }],
    "gas": { "budgetSui": 0.0137, "estimateSui": 0.0114, "coins": 1 },
    "check": { "verdict": "safe", "headline": "No red flags found in the 1 coin, 1 package this transaction touches.",
               "balanceChanges": [{ "coin": "USDC", "amount": -5000 }, { "coin": "SUI", "amount": -0.0114 }] }
  }],
  "sign": "Sign tx_bytes with the sender's own wallet and submit it. tide never signs."
}

3. If the wallet holds SUI instead, pass asset: "SUI": the built transaction swaps SUI to USDC through the Aftermath router (0.5% slippage, enforced on chain) and supplies the output to NAVI in one transaction. For a single action, call build_transaction:

{ "sender": "0xYOUR_WALLET", "action": "supply", "protocol": "navi", "asset": "USDC", "amount": 5000 }

4. Check again just before signing if time has passed: explain_unsigned { tx_bytes } runs the same check on any bytes. 5. Your agent's own wallet signs tx_bytes and submits it. Later, withdraw_plan { wallet, exit: "all" } lists the positions and builds the exits.

After signing: confirm it landed

Submitting returns the transaction digest. Call explain_transaction { digest } with it: once the transaction is in a checkpoint (usually within a second or two) you get its status, what moved and the fee, and you can compare that to the spends and receives the build promised. If it says not found, wait a second and ask again.

Over REST the same calls are POST /v1/tx/build, POST /v1/yield/plan with build: true and POST /v1/yield/withdraw-plan. Credits follow your plan; keyless works at the keyless rate.

Agent Pass

A Sui Agent Pass lets an owner give an agent a budget and rules: which coins it may swap, on which pools, how much per trade and per day, the worst price it may accept, and until when. Sui enforces them; the agent signs with its own key and never holds the owner's coins. Give build_transaction the pass id and tide builds inside those rules:

• The coins come from the owner's budget through the pass's own calls; the output goes straight to the owner.
• Only the pools the owner listed are used. For a swap without min_out, tide dry-runs each listed route, keeps the best fill and sets the minimum 1% below it (slippage_pct changes that).
• Every step is checked against the live pass first: status, expiry, per trade and per day caps, budget left, route and price floor. If the pass would refuse it, you get unsafe with each rule and no bytes.
• The bytes come back with a signed receipt: what will move, what Sui enforces and a pass or fail verdict, with a page your human can open.

{ "pass": "0x03c7bd6a3d4910f56fea05dedb632efd9824c82f22ef274180b7b8756ce47bac",
  "action": "swap", "from": "USDC", "to": "SUI", "amount": 0.2 }

{
  "summary": "PASS under pass Buy SUI daily: Swaps 0.2 USDC from the owner's budget for at least 0.215 SUI on Cetus USDC/SUI; the SUI goes to the owner.",
  "sender": "0xb569f5371380e339038c0cdce2729621d36bfc89e740c28e3976bf04357edab6",
  "tx_bytes": "AAAD...", "digest": "HiiwVEbERkF5B4Rv3yvFbR4eBg1gR9HL7Fy7kCThJb7Q",
  "pass_checks": [
    "ok: Active. The agent can act until 2026-11-06.",
    "ok: 0.2 USDC against a limit of 0.5 USDC per action.",
    "ok: 0.2 USDC against 0.5 USDC left today (daily cap 0.5 USDC).",
    "ok: Allowed routes: DeepBook SUI/USDC; Cetus USDC/SUI (listed by the owner).",
    "ok: 0.2 USDC against 2.5 USDC left of the owner's USDC budget."
  ],
  "receipt": { "id": "11e497b2f981575a04dd95a124f71cbf", "url": "https://tide.ad/proof/11e497b2f981575a04dd95a124f71cbf", "verdict": "pass" },
  "next": "After sending, call confirm_execution with the digest and this receipt id."
}

Under a pass the sender is always the pass's agent, so sender can be left out. The actions are the ones a pass allows: swap, supply (NAVI), stake (with the validator address) and transfer (to a recipient name the owner listed). Each step names its own amount, since outputs go to the owner rather than to the next step. yield_plan with build: true takes pass the same way. Before building, agent_pass_precheck answers whether one action would pass, and agent_pass_report shows a pass's rules, spend and history. After sending, confirm_execution compares what happened with the receipt. Over REST it is POST /v1/tx/build with pass.

What a tool returns

Every result is one JSON object, sent as text and as structured content. It starts with summary, one or two plain sentences an agent can quote, then compact facts, then link, the tide.ad page to share.

{
  "summary": "Swapped 39.7 SUI for 36.67 USDC ($36.67) on Bluefin, Aftermath and FlowX, through the Aftermath Router.",
  "status": "success",
  "type": "SWAP",
  "time": "2026-11-04T21:07:54.000Z",
  "checkpoint": 341685636,
  "fee": { "sui": 0.002751 },
  "steps": ["Swapped 39.7 SUI for 36.67 USDC through Aftermath Router, over 2 pools on Bluefin.", "...", "Sent the USDC to 0x0069...e4fa."],
  "balanceChanges": [{ "owner": "0x0069...e4fa", "sentence": "Net: -39.7 SUI ($36.67), +36.67 USDC ($36.67) after 0.0028 SUI gas.", "changes": [...] }],
  "link": "https://tide.ad/tx/DdfuBiVPRZ8VCKfGs8ZgGYXUTXecfbRNx9g6rJjwwA75",
  "asOf": { "checkpoint": 341690112, "time": "2026-11-04T21:25:10.402Z", "fresh": "live: about 1 s behind the chain" }
}

• Amounts are whole coins (SUI, not MIST) unless a field ends in Raw. USD values come with the time of their price.
• Lists are short by default: 10 holdings, 10 holders, 15 flows, 10 history rows. A result says how many more exist, and paged tools return a cursor to pass back.
• When a part of a composite answer is slow, the rest still comes back, with missing naming the part to ask for again.

How fresh it is

Every result ends with asOf: the checkpoint and time the answer reflects, and fresh, how fresh that tool's data is. Over REST and JSON-RPC the same asOf sits in the response.

What it covers and what it does not

• Sui mainnet only. No testnet, no other chains.
• History since genesis: every transaction, event, object version and balance change, for history, past balances and SQL.
• Building: native staking, liquid staking (afSUI, haSUI, vSUI, sSUI, stSUI and other SpringSui coins), lending supply and withdraw on Suilend, NAVI and Scallop, and swaps through the Aftermath router.
• Not built yet: liquidity positions and vault deposits. yield_options still lists them with rates and risk; use the protocol's app to enter them.
• tide reads and builds. It never signs, never sends and never holds keys.

Errors

A failed call returns isError: true with one line that says what went wrong and what to do next: fix an argument, wait a number of seconds, narrow the range, or add a key. For example:

invalid_params: digest must be a base58 transaction digest (43 or 44 characters). Fix the arguments and call explain_transaction again.
rate_limited: wait 1 s and call wallet_profile again. Without a key the limit is 2 calls a second per IP; a free key at https://tide.ad/developers/keys allows 15.
unauthorized: sql needs an API key. Get a free one in a minute at https://tide.ad/developers/keys, then connect with the header Authorization: Bearer YOUR_KEY.

Out of credits

When credits run out, the tool error explains both ways to pay: top up credits with USDC, or pay per call in USDC. See Pay with USDC.

• billing_status shows your credits.
• billing_topup takes usd and optional address and gas. It returns unsigned tx_bytes for you to sign and send.

{ "usd": 5, "address": "0xYOUR_WALLET" }

Skill for coding agents

tide.ad/skills/tide/SKILL.md tells a coding agent when to reach for tide and which tool or REST method answers what. Drop it into your agent's skills folder, for example .claude/skills/tide/SKILL.md.

mkdir -p .claude/skills/tide && curl -so .claude/skills/tide/SKILL.md https://tide.ad/skills/tide/SKILL.md

Machine docs