MCP tool reference

The TONNode MCP server (@tonnode/mcp) exposes 16 tools — no more, no fewer. This page documents every one of them: arguments, types, defaults, a real call and a real response.

Everything here was read off the running server (tools/list handshake plus live tools/call responses against TON mainnet). Sample responses are genuine captures; the numbers in them were true at the moment of capture and will have moved since.

TONNode ships two things: this MCP server and liteserver node access (see the liteserver documentation). There is no REST API and no mempool stream — if you see either mentioned anywhere, it is not shipped.

Connecting

The paid product is the hosted endpoint https://mcp.tonnode.io/mcp. The key travels in a header — nothing to install. The exact config differs per client.

Cursor (.cursor/mcp.json) and Claude Code (.mcp.json) speak to a remote MCP server directly:

{
  "mcpServers": {
    "ton": {
      "url": "https://mcp.tonnode.io/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) — its config file launches local processes and has no field for a remote URL, so the remote server is bridged with mcp-remote. The header is passed as a single argument with no space after the colon:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://mcp.tonnode.io/mcp",
        "--header", "Authorization:Bearer <your key>"
      ]
    }
  }
}

VS Code (.vscode/mcp.json) — VS Code uses servers, not mcpServers; a copied mcpServers block is silently ignored:

{
  "servers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

Codex (~/.codex/config.toml) reads the key from an environment variable:

[mcp_servers.ton]
url = "https://mcp.tonnode.io/mcp"
bearer_token_env_var = "TONNODE_KEY"

Running it locally. npx -y @tonnode/mcp starts the same 16 tools over stdio. That mode has no authentication and takes no TONNode key: it is a local process that talks to the liteservers listed in the public TON global config. Point it at other liteservers with TON_LITESERVERS, or at testnet with --testnet (the swap tools refuse to run there).

Get a key: connect a wallet at tonnode.io/dashboard, top up the balance (GRAM or USDT on-chain, or xRocket inside Telegram), pick a plan. A plan is a rate limit, not a request quota: Hobby $0 / 60 rpm, Pro $29/mo / 300 rpm, Scale $199/mo / 1200 rpm. There is no monthly request cap to run out of.

Source: github.com/tonnode · package: @tonnode/mcp 0.9.1

A programmatic client

Every example on this page is a name + arguments pair. This helper runs any of them; it is used verbatim in the snippets below.

// npm install @modelcontextprotocol/sdk
// TONNODE_KEY=tn_live_… node tonnode.mjs
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.tonnode.io/mcp"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.TONNODE_KEY}` } } }
);

const client = new Client({ name: "tonnode-docs", version: "1.0.0" });
await client.connect(transport);

/** Call a tool and return the parsed JSON result. Throws on tool errors. */
export async function call(name, args = {}) {
  const res = await client.callTool({ name, arguments: args });
  if (res.isError) throw new Error(res.content[0].text);
  return res.structuredContent ?? JSON.parse(res.content[0].text);
}

Every tool returns the same envelope: a single text content block holding pretty-printed JSON, plus the identical object as structuredContent. Errors come back as isError: true with {"error": "<message>"} in the text block.

Without an SDK

The transport is plain Streamable HTTP. initialize, keep the mcp-session-id, then call:

KEY=tn_live_your_key

# 1. initialize — the session id comes back in a response header
curl -sD headers.txt -X POST https://mcp.tonnode.io/mcp \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-06-18","capabilities":{},
        "clientInfo":{"name":"curl","version":"1.0"}}}'

SID=$(awk -F': ' '/^mcp-session-id/{print $2}' headers.txt | tr -d '\r')

# 2. tell the server the handshake is done
curl -s -X POST https://mcp.tonnode.io/mcp \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. call a tool
curl -s -X POST https://mcp.tonnode.io/mcp \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_masterchain_info","arguments":{}}}'

Both Accept values are mandatory — the transport rejects a POST without them. Responses arrive as a one-event SSE frame (event: message + data: {…}). JSON-RPC batches are rejected with 400.

Conventions

These hold across every tool.

Tool annotations

The server declares MCP annotations so orchestrators can decide what to auto-approve. Do not auto-run anything in the bottom two rows.

Tool index

Chain reads

Jettons

Utilities

Swaps on TON

Cross-chain (ordered flow — see the lifecycle)

Wallet

Chain reads

These run over TON's native ADNL liteserver protocol — no HTTP indexer in the middle.

get_masterchain_info

The latest masterchain block: workchain, shard, seqno and block hashes.

When to use. Health-checking the network or your own endpoint, and getting the current block height. The masterchain produces a block roughly every 3 seconds — if seqno does not grow between two calls a few seconds apart, the liteserver answering you is lagging.

Parameters. None.

Example call

await call("get_masterchain_info");

Example response

{
  "workchain": -1,
  "shard": "-9223372036854775808",
  "seqno": 82174631,
  "rootHash": "ZoR3D4k9QcLQ2YEw9YdKnnG7cKCba48XAB75VnSDNr8=",
  "fileHash": "g4ZSWMffk+PC+0p4zkKqchd/d2hD+XCD8PykSkufJps="
}

get_balance

Native GRAM balance of an address.

When to use. The question is about the native coin only. For tokens use get_jetton_balance; for deployment status and the last-transaction cursor use get_account_state.

Example call

await call("get_balance", {
  address: "-1:3333333333333333333333333333333333333333333333333333333333333333"
});

Example response

{
  "address": "Ef8zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzM0vF",
  "balance_gram": "1329968526.250365411",
  "balance_nano": "1329968526250365411",
  "at_seqno": 82174631
}

A never-funded address returns 0 — that is a valid answer, not an error.

get_account_state

Full account state: status, balance, last-transaction pointer, and whether code and data are deployed.

When to use. Checking whether a contract or wallet is deployed, diagnosing an address that does not respond, and before run_get_method — a get-method needs status: "active".

Example call

await call("get_account_state", {
  address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs" // USDT master
});

Example response

{
  "address": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "status": "active",
  "balance_gram": "1067.260130657",
  "last_transaction": {
    "lt": "92706854000020",
    "hash": "71a1f753f02267e5a6e1db2c3b3bc7771adf053f8c51bded5cb2e2276fd42b8d"
  },
  "has_code": true,
  "has_data": true,
  "at_seqno": 82174632
}

Reading it. status: "uninit" with a non-zero balance means funds arrived but the wallet contract has not been deployed yet — normal for a freshly funded wallet. last_transaction is exactly the cursor get_transactions starts from.

get_transactions

Recent transactions of an address, newest first.

When to use. Verifying that a payment arrived, listing wallet activity, tracing what an address just did.

Example call

await call("get_transactions", {
  address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  limit: 2
});

Example response

{
  "address": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "transactions": [
    {
      "hash": "71a1f753f02267e5a6e1db2c3b3bc7771adf053f8c51bded5cb2e2276fd42b8d",
      "lt": "92706854000020",
      "unix_time": 1785083044,
      "in_value_gram": "0.012591002",
      "in_from": "EQBOmxbUlIYOTJ4I8UODLUHqmIVYZm5KU8NU1I_kh0OyFOAH",
      "out_messages": 1,
      "total_fees_gram": "0.000449864"
    },
    {
      "hash": "3ff362d5e82968e1e032f66b17c0d8ce94a06ab2813cd98fc346c1dfacb9e264",
      "lt": "92682482000007",
      "unix_time": 1785073058,
      "in_value_gram": "0.012591002",
      "in_from": "EQDTGD-F77I51teW6XiaDcVaVU2zcnzotx_-ntCeghp5zt6x",
      "out_messages": 1,
      "total_fees_gram": "0.000449399"
    }
  ]
}

Limits worth knowing.

• No pagination. Each call reads backwards from the account's newest transaction, so at most the 30 most recent are reachable. There is no cursor argument.
• An address that was never active returns "transactions": [] — not an error.
• History depth. A liteserver that has pruned the requested range answers lt not in db. The tool rewrites that into an explicit message telling you to point TON_LITESERVERS at an archive node. Deep history needs an archive-capable endpoint — the liteservers in the public global config are non-archive.

run_get_method

Execute a read-only get-method on any contract. No gas, no state change.

When to use. Reading typed on-chain data a dedicated tool does not cover: seqno, get_sale_data, get_collection_data, get_nft_data, and anything custom a contract exposes.

Only integer arguments are supported. Methods that take an address or slice argument have dedicated tools — use get_jetton_balance instead of calling get_wallet_address by hand.

Example call

await call("run_get_method", {
  address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  method: "get_jetton_data"
});

Example response

{
  "address": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "method": "get_jetton_data",
  "exit_code": 0,
  "stack": [
    { "type": "int", "value": "1429976002510000" },
    { "type": "int", "value": "-1" },
    { "type": "slice", "boc_base64": "te6cckEBAQEAJAAAQ4AMiB/HjSggcHLHKKLniWIo834XNprhIcsO73tLA4XzMxC89RGs" },
    { "type": "cell", "boc_base64": "te6cckEBBwEAfQABAwDAAQIBIAIFAUO/+HLr21FNnJfCg7fwrlF5Ap4rYRnDlGJxnk9G7Y90E+ZAAwECAAQAPmh0dHBzOi8vdGV0aGVyLnRvL3VzZHQtdG9uLmpzb24BQ7/3QH6XjwGkBxFBGxrLdzqWvdk/qDu1yoQ1ATyMSzrJH0AGAAQANmxT2v0=" },
    { "type": "cell", "boc_base64": "te6cckEBAQEAIwAIQgKPRS16Tf10BmtoI2UXclntBXNENb52tf1L1divK3w9aCBrv3Y=" }
  ]
}

exit_code. 0 and 1 both mean success (TVM uses either for a normal return). 11 almost always means the contract has no such method. Anything else is a contract-specific error.

Stack item shapes.

Decode a returned cell client-side with @ton/core:

// npm install @ton/core
import { Cell } from "@ton/core";

const res = await call("run_get_method", {
  address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  method: "get_jetton_data"
});

// item 2 is the admin address slice
const admin = Cell.fromBase64(res.stack[2].boc_base64).beginParse().loadAddress();
console.log(admin.toString()); // EQBkQP48aUEDg5Y5RRc8SxFHm_C5tNcJDlh3e9pYHC-ZmG2M

Jettons

get_jetton_balance

Token balance of an owner — USDT and every other TEP-74 jetton.

How it works. Calls get_wallet_address(owner) on the jetton master to derive the owner's jetton-wallet contract, then reads get_wallet_data on it. Two on-chain reads, one tool call.

Example call

await call("get_jetton_balance", {
  owner: "-1:3333333333333333333333333333333333333333333333333333333333333333",
  jetton_master: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs"
});

Example response

{
  "owner": "Ef8zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzM0vF",
  "jetton_master": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "jetton_wallet": "EQBkvsMdV2-HqsiLwaaJi-VkNVC69z2j7hYZ6thdkFMVXU_T",
  "balance": "0",
  "deployed": false,
  "at_seqno": 82174515
}

Converting to a human amount. balance is raw. USDT uses 6 decimals, most other jettons 9 — read the real figure with get_jetton_info:

const info = await call("get_jetton_info", { jetton_master: USDT });
const bal  = await call("get_jetton_balance", { owner: WALLET, jetton_master: USDT });
const human = Number(bal.balance) / 10 ** (info.decimals ?? 9);

If jetton_master is not actually a jetton master, the tool fails loudly: get_wallet_address failed with exit code … — is EQ… really a jetton master?

get_jetton_info

Metadata of a jetton master: name, symbol, decimals, supply, mintable flag, admin.

When to use. Before any amount conversion. Swap quotes and balances are in raw units; you need decimals to turn them into numbers a human reads. Call it before get_swap_quote whenever you do not already know a token's decimals.

Example call

await call("get_jetton_info", {
  jetton_master: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs"
});

Example response (mainnet USDT — note the semi-chained metadata)

{
  "jetton_master": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "name": null,
  "symbol": null,
  "decimals": 6,
  "description": null,
  "total_supply": "1429976002510000",
  "mintable": true,
  "admin": "EQBkQP48aUEDg5Y5RRc8SxFHm_C5tNcJDlh3e9pYHC-ZmG2M",
  "metadata_type": "onchain+uri",
  "metadata_uri": "https://tether.to/usdt-ton.json",
  "at_seqno": 82174515
}

Off-chain metadata. When metadata_type is offchain, name/symbol/decimals live in a JSON file at metadata_uri and come back null here. onchain+uri (the USDT case above) means the numeric fields are on-chain but the display fields are in that JSON. Fetch the URI yourself if you need the name.

Utilities

parse_address

Parse, validate and convert a TON address between all its forms. Purely local — no network access, no rate-limit cost beyond the request itself.

When to use. Normalizing user input, comparing two addresses that look different, or converting to the raw form that indexers expect.

Example call

await call("parse_address", {
  address: "-1:3333333333333333333333333333333333333333333333333333333333333333"
});

Example response

{
  "raw": "-1:3333333333333333333333333333333333333333333333333333333333333333",
  "friendly_bounceable": "Ef8zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzM0vF",
  "friendly_non_bounceable": "Uf8zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMxYA",
  "workchain": -1,
  "input_format": "raw",
  "input_flags": null
}

Why it matters. EQ… and UQ… encode the same account. Bounceable (EQ…) is conventional for contracts; non-bounceable (UQ…) for user wallets. Two addresses are the same account if and only if their raw forms match — never compare friendly strings.

Swaps on TON

get_swap_quote and build_swap_tx are backed by Omniston, STON.fi's RFQ protocol aggregating STON.fi and DeDust liquidity. Mainnet only.

The flow is two calls and is strictly non-custodial:

1. get_swap_quote → a firm quote with an id.
2. build_swap_tx → unsigned TonConnect messages. You sign and send them.

Quotes expire in roughly a minute. Build promptly or re-quote.

get_swap_quote

A firm quote to exchange GRAM or any jetton for another asset on TON.

When to use. Answering "what would I get for X right now", or as step 1 of an actual swap. For a swap into another blockchain use get_crosschain_quote instead.

"TON", "toncoin" and "native" are accepted as aliases for "GRAM".

Example call

const quote = await call("get_swap_quote", {
  from_asset: "GRAM",
  to_asset: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // USDT
  amount_units: "5000000000",                                   // 5 GRAM
  slippage_bps: 100                                             // 1%
});

Example response

{
  "quote_id": "9c010713aeaa68dac2bf8577b6b32560f7f214defb71bc69702efd12305b0f86",
  "resolver": "Omniston",
  "input_asset": "GRAM",
  "output_asset": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "input_units": "5000000000",
  "output_units": "7573330",
  "min_output_units": "7497597",
  "recommended_min_output_units": "7497597",
  "recommended_slippage_bps": 100,
  "price_impact_bps": 0,
  "protocol_fee_units": "0",
  "integrator_fee_units": "0",
  "gas_budget_nano": "100000000",
  "estimated_settlement_seconds": 1,
  "route": [
    {
      "from": "GRAM",
      "to": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
      "protocols": ["DeDust"]
    }
  ]
}

Reading it. output_units is an expectation; min_output_units is a promise. If the pool moves past the floor, the swap refunds instead of executing. Tightening slippage_bps narrows the floor — the 5% cap is deliberate, anything looser only feeds MEV. With exact: "output" the floor is still min_output_units, so raise amount_units or tighten slippage when an exact minimum must clear.

build_swap_tx

Turn a quote into the unsigned transaction for the wallet owner to sign.

This output moves real funds once signed. Treat it as an armed payment: show it to the wallet owner, never auto-approve it.

Example call

const tx = await call("build_swap_tx", {
  quote_id: quote.quote_id,
  wallet: "UQ…your wallet…"
});

Response shape (payload BoCs elided — they are long base64 strings unique to each build)

{
  "quote_id": "9c010713aeaa68dac2bf8577b6b32560f7f214defb71bc69702efd12305b0f86",
  "wallet": "UQ…",
  "message_count": 1,
  "total_attached_nano": "…",
  "tonconnect": {
    "validUntil": 1785083344,
    "network": "-239",
    "messages": [
      { "address": "EQ…", "amount": "…", "payload": "te6cck…" }
    ]
  }
}

tonconnect is exactly the shape TonConnect expects — hand it straight over:

// npm install @tonconnect/ui-react
await tonConnectUI.sendTransaction(tx.tonconnect);

Funding requirements. The wallet must hold the input amount plus gas_budget_nano in GRAM. For a GRAM-input swap the input is included in the attached value. Omniston emulates the transfer while building, so an underfunded wallet fails before anything is signed:

{"error":"Emulation error: wrong output amount. Expected: 7497597, actual: 0 — {\"error_info\":{\"reason\":\"QUOTE_VALIDATION_FAILED\",\"domain\":\"omni.ston.fi\",\"metadata\":{\"expected\":\"7497597\",\"actual\":\"0\",\"type\":\"EMULATION_WRONG_OUTPUT_AMOUNT\"}}}"}

An expired quote also fails here — re-quote and rebuild.

Cross-chain swaps: an ordered flow

The five *_crosschain_* tools are not independent calls. They are one atomic-swap lifecycle, and calling them out of order loses money. TON is always the source chain: the trade is funded and signed by a TON wallet. Destinations: Ethereum, Arbitrum, Base, BNB, Polygon, Avalanche.

flowchart TD
    A["1. get_crosschain_quote<br/>firm price + htlc_hashing_function"] --> B["2. build_crosschain_swap_tx<br/>unsigned escrow tx + htlc_secret"]
    B --> C["3. wallet owner signs and sends<br/>escrow position exists on TON"]
    C --> D["4. track_crosschain_swap<br/>poll every ~10s"]
    D -->|"dst_phase = ready_for_private_completion"| E["5. disclose_crosschain_secret<br/>both sides settle"]
    D -->|"cancellation_mode = onchain"| F["fallback: build_crosschain_refund<br/>reclaim escrow"]
    E --> G["status = fully_filled"]

Three rules that decide whether this ends well:

1. Keep htlc_secret until the trade completes. The server does not store it — it exists only in the build_crosschain_swap_tx response. Without it the trade cannot settle (funds stay refundable after the timeout, but the swap is lost).
2. Every build generates a NEW secret bound to that specific payload. If you rebuild for the same quote, discard every earlier payload and secret. Signing an older payload after a rebuild locks funds under a hash whose secret you are no longer tracking.
3. Disclose promptly, never late. Once revealed, the preimage is public and the resolver can claim the TON side. Revealing close to the destination's rollback window risks losing the input without receiving the output — that is the classic late-reveal loss. The tool refuses inside a 60-second safety margin and tells you to refund instead.

The server never signs, never holds funds, and cannot redirect anything: a disclosed secret can only complete the trade as quoted, and an unfilled escrow is always reclaimable by the owner wallet.

get_crosschain_quote

Step 1. Firm quote for paying on TON and receiving on an EVM chain, settled through Omniston's atomic HTLC escrow. Mainnet only.

An ERC-20 address in mixed case must carry a correct EIP-55 checksum — that is the typo guard. All-lowercase or all-uppercase input is normalized for you.

Example call

const xq = await call("get_crosschain_quote", {
  from_asset: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // USDT on TON
  to_chain: "ethereum",
  to_asset: "0xdAC17F958D2ee523a2206206994597C13D831ec7",         // USDT on Ethereum
  amount_units: "100000000"                                       // 100 USDT (6 decimals)
});

Example response

{
  "quote_id": "db858eb36b19b0c256d7d8929763abe29c97075693d33616972835595ac81895",
  "resolver": "Arbiter",
  "input_asset": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "output_asset": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "input_units": "100000000",
  "output_units": "99914503",
  "protocol_fee_units": "9992",
  "integrator_fee_units": "0",
  "gas_budget_nano": "400000000",
  "security_deposit_asset": "EQBnGWMCf3-FZZq1W4IWcWiGAc3PHuZ0_H-7sad2oY00o83S",
  "security_deposit_units": "500000000",
  "htlc_hashing_function": "keccak256",
  "estimated_settlement_seconds": 39
}

Note what is absent compared with an on-TON quote: there is no slippage_bps argument and no min_output_units. Cross-chain settlement is an escrowed order at the quoted terms, not an AMM route.

If htlc_hashing_function comes back null, stop — do not build.

Thin pairs simply do not get quoted:

{"error":"no resolver quoted this pair/amount — pool may lack liquidity, or the amount is too small to cover gas"}

build_crosschain_swap_tx

Step 2. Build the unsigned TON escrow transfer and generate the HTLC secret that later completes it.

The response contains both an armed payment and a payment authorization. Anyone who sees htlc_secret together with quote_id can trigger disclosure. Keep this response out of logs, transcripts and shared context.

Example call

const build = await call("build_crosschain_swap_tx", {
  quote_id: xq.quote_id,
  wallet: "UQ…your TON wallet…",
  to_chain: "ethereum",
  destination_address: "0x…your EVM wallet…",
  hashing_function: xq.htlc_hashing_function
});

// Persist this before signing anything.
saveSecret(build.quote_id, build.htlc_secret);
await tonConnectUI.sendTransaction(build.tonconnect);

Response shape (secret and BoCs elided)

{
  "quote_id": "db858eb36b19b0c256d7d8929763abe29c97075693d33616972835595ac81895",
  "wallet": "UQ…",
  "destination_address": "0x…",
  "htlc_secret": "<64-char hex — 32 random bytes>",
  "htlc_secret_hash": "<64-char hex — hash of the secret>",
  "message_count": 1,
  "total_attached_nano": "…",
  "tonconnect": {
    "validUntil": 1785083344,
    "network": "-239",
    "messages": [
      { "address": "EQ…", "amount": "…", "payload": "te6cck…" }
    ]
  }
}

track_crosschain_swap

Step 3. A snapshot of the escrow order: lifecycle phases and HTLC time windows on both chains. Poll it about every 10 seconds after sending the escrow transaction.

Example call

const st = await call("track_crosschain_swap", {
  quote_id: xq.quote_id,
  wallet: "UQ…your TON wallet…"
});

Response when the escrow has not landed yet (exact, not illustrative)

{
  "found": false,
  "status": null,
  "remaining_input_units": null,
  "escrowed_input_units": null,
  "cancellation_mode": null,
  "estimated_finish_timestamp": null,
  "maximum_finish_timestamp": null,
  "executions": []
}

Fields when found is true

Each execution

The decision this tool exists to support. When an execution's dst_phase reaches ready_for_private_completion (or ready_for_public_completion), the resolver has locked the output on the destination chain — disclose promptly. Do not disclose when now is anywhere near that execution's output_position_timestamps.private_rollback_at: past it the resolver can roll the destination back and still claim your TON with the now-public preimage. Refund instead.

A poll loop:

async function waitForReady(quoteId, wallet, timeoutMs = 10 * 60_000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const st = await call("track_crosschain_swap", { quote_id: quoteId, wallet });
    const ready = st.executions.find((e) =>
      e.dst_phase === "ready_for_private_completion" ||
      e.dst_phase === "ready_for_public_completion"
    );
    if (ready) return ready;
    if (st.cancellation_mode === "onchain") return null; // refund path
    await new Promise((r) => setTimeout(r, 10_000));
  }
  return null;
}

found: false means the escrow transaction has not landed yet (or was never sent). A quote_id the backend has never seen errors instead:

{"error":"Object not found: quote with id: 0000000000000000000000000000000000000000000000000000000000000000 — {\"error_info\":{\"reason\":\"NOT_FOUND\",\"domain\":\"omni.ston.fi\",\"metadata\":{\"object_id\":\"…\",\"object_type\":\"quote\"}}}"}

This returns a snapshot, not a stream. Poll again for updates.

disclose_crosschain_secret

Step 4 — the final, trade-committing call. Revealing the preimage lets the resolver claim the TON side. It cannot be taken back.

This is the only tool annotated destructive. Never auto-approve it.

Guards run before anything is revealed. Prose warnings do not protect funds, so the tool re-verifies live state and refuses unless all of these hold:

1. The order exists on-chain (it probes for up to 6 seconds).
2. The chosen execution's destination position is at ready_for_private_completion or ready_for_public_completion.
3. The secret matches that execution's on-chain hash (checked against both keccak256 and sha256).
4. now + 60s is still before the destination position's private_rollback_at.

Each failure returns an explicit error ending in secret NOT disclosed:

destination position is not ready (dst_phase=…) — disclosing now would let the resolver claim your TON without delivering; keep polling track_crosschain_swap; secret NOT disclosed
secret does not match this execution's on-chain hash — wrong secret or wrong quote_id pair; secret NOT disclosed
too close to the destination rollback window — a late reveal risks losing the input; do NOT disclose, reclaim the escrow with build_crosschain_refund instead; secret NOT disclosed
order not found — the escrow transaction has not landed (or quote_id/wallet is wrong); secret NOT disclosed

Example call

const ready = await waitForReady(xq.quote_id, WALLET);
if (ready) {
  await call("disclose_crosschain_secret", {
    quote_id: xq.quote_id,
    wallet: WALLET,
    secret: loadSecret(xq.quote_id),
    execution_index: ready.index
  });
}

Response

{
  "disclosed": true,
  "quote_id": "db858eb36b19b0c256d7d8929763abe29c97075693d33616972835595ac81895",
  "execution_index": 0,
  "verified_dst_phase": "ready_for_private_completion"
}

The secret can only complete the trade as quoted. It cannot redirect funds anywhere else.

build_crosschain_refund

Fallback. Build the unsigned transaction that cancels the escrow position and returns the funds to the owner wallet.

When to use. The trade did not settle and track_crosschain_swap reports cancellation_mode: "onchain". Before that point the position cannot be cancelled by the trader — building earlier will fail.

Example call

const refund = await call("build_crosschain_refund", {
  quote_id: xq.quote_id,
  wallet: "UQ…your TON wallet…"
});
await tonConnectUI.sendTransaction(refund.tonconnect);

Response shape

{
  "quote_id": "db858eb36b19b0c256d7d8929763abe29c97075693d33616972835595ac81895",
  "wallet": "UQ…",
  "message_count": 1,
  "total_attached_nano": "…",
  "tonconnect": {
    "validUntil": 1785083344,
    "network": "-239",
    "messages": [
      { "address": "EQ…", "amount": "…", "payload": "te6cck…" }
    ]
  }
}

After the wallet signs and sends it, the escrowed input and the security deposit come back to the owner.

Wallet

generate_wallet

Create a brand-new TON wallet: a fresh 24-word mnemonic, its ed25519 keypair, and the address for the chosen contract version.

This tool returns secrets

The response contains a mnemonic and a private key. Anyone who sees it controls the wallet and everything in it.

• The server never stores or logs the mnemonic or the private key. The only thing written to the server log is the public address.
• In hosted mode the keys are generated on the server and travel back over TLS, so treat every generated wallet as hot: fine for programmatic or ephemeral use, but move any meaningful balance to a hardware or cold wallet.
• Keep the response out of logs, transcripts and shared agent context.
• Losing the mnemonic means losing the funds. There is no recovery.
• Operators who do not want key material flowing through a shared endpoint can unregister the tool entirely with TONNODE_DISABLE_WALLET_GEN=1. On such a server it will not appear in tools/list.

When to use. An agent needs its own wallet to receive or send funds — for example before build_swap_tx.

Each call creates a new, independent wallet. Never re-call the tool to "re-read" a wallet you already made: you will get a different one and orphan any funds sent to the first.

Versions.

The v3r2/v4/v5r1 addresses come from @ton/ton's canonical contracts. highload_v3 is derived from the official contract code plus its data layout.

Example call

const w = await call("generate_wallet", { version: "v4" });
// Never console.log(w) — it contains the mnemonic and private key.
console.log("fund this address:", w.recommended_deposit_address);

Response shape (secret fields shown as placeholders — never print real ones)

{
  "version": "v4",
  "workchain": 0,
  "recommended_deposit_address": "UQ…",
  "address": {
    "bounceable": "EQ…",
    "non_bounceable": "UQ…",
    "raw": "0:…"
  },
  "public_key": "<64-char hex>",
  "private_key": "<128-char hex>",
  "mnemonic": ["word1", "word2", "…24 words total…"],
  "warning": "SECRET — anyone with this mnemonic or private key controls the wallet. …"
}

For highload_v3 the response additionally carries subwallet_id and timeout_sec.

Two things that cost people money.

1. Fund the non-bounceable address. A fresh wallet is uninitialized until its first outgoing transaction deploys it. Receiving does not require deployment — but a bounceable (EQ…) transfer to an undeployed wallet bounces straight back to the sender. Send the first deposit to recommended_deposit_address.
2. For highload_v3, store subwallet_id and timeout_sec alongside the mnemonic. Unlike seqno wallets, the highload address depends on both — the mnemonic alone cannot reproduce an address built with non-default parameters.

Errors

Tool-level failures come back as an MCP result with isError: true and a single text block:

{"error": "\"UQBOmxbUlIYOTJ4I8UODLUHqmIVYZm5KU8NU1I_kh0OyFF9r\" is not a valid TON address (expected friendly EQ…/UQ… or raw 0:… form)"}

Messages are written to be actionable by an agent without a human in the loop.

Transport-level errors (hosted mode) arrive as HTTP status codes with a JSON body:

Idle sessions are swept after 30 minutes. Revocation is not instant: the server re-reads its key registry on a 5-second file poll, and a revoked key's live sessions are dropped on that next reload.