Tonnode MCP vs MCP Server

get_transactions

Recent transactions of a TON address, newest first. Use when: verifying that a payment arrived, listing latest wallet activity, or tracing what an address did recently. Returns an array of {hash, lt (string), unix_time, in_value_gram, in_from, out_messages, total_fees_gram} — in_value_gram/in_from describe the incoming message (null for outgoing-only transactions). Never-active addresses return an empty array (not an error); an undecodable transaction comes back as {hash, parse_error: true}. No pagination: each call reads from the account's newest transaction — at most the 30 most recent are reachable. History depth: an error like "lt not in db" means this liteserver has already pruned that part of history — only archive endpoints keep the full chain; retry through one (TON_LITESERVERS or a TONNode hosted key) for deep history.

run_get_method

Execute a read-only get-method (no gas, no state change) on a smart contract: seqno, get_jetton_data, get_sale_data, get_collection_data and anything else the contract exposes. Use when: reading typed on-chain data from a specific contract. The contract must be active — check with get_account_state first if unsure. Args: only integer arguments are supported here (decimal strings); methods that need an address/slice argument have dedicated tools — e.g. use get_jetton_balance instead of calling get_wallet_address manually. Returns: exit_code (0 or 1 = success; 11 usually means the contract has no such method; other values are contract-specific errors) and the result stack — typed items like {type:"int", value} or {type:"cell"|"slice", boc_base64}.

get_jetton_balance

Jetton (TON token) balance of an owner address — USDT and every other TEP-74 token. Use when: the question is about token balances rather than the native GRAM coin (for GRAM use get_balance). Args: owner — the holder's address; jetton_master — the token's master contract address. How it works: derives the owner's jetton-wallet address from the master, then reads its balance on-chain. Returns: jetton_wallet (the derived address), balance in raw indivisible units (string), deployed — false means the owner never held this token, so the balance is 0 — and at_seqno. Raw units: divide by 10^decimals; USDT uses 6 decimals, most other jettons 9 (read decimals from the master's metadata via run_get_method get_jetton_data).

get_jetton_info

Metadata of a jetton master (token) contract: name, symbol, DECIMALS, total supply, mintable, admin. Use when: you need a token's decimals to convert raw indivisible units — swap quotes and balances are in raw units, so a human amount = raw / 10^decimals (USDT is 6, most jettons 9). Call this before get_swap_quote/build_swap_tx when you don't know the token's decimals. Args: jetton_master — the token's master contract address (e.g. USDT "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs"). Returns: name, symbol, decimals (a number, or null when the token stores metadata off-chain), description, total_supply (raw), mintable, admin, metadata_type (onchain/offchain) and metadata_uri. Off-chain tokens keep name/symbol/decimals in a JSON file at metadata_uri — this tool returns the URI but does not fetch it, so decimals may be null (assume 6 for USDT-like, 9 otherwise, or fetch the URI).

parse_address

Parse, validate and convert a TON address between all its formats — purely local, no network access. Use when: normalizing user input, comparing addresses that look different but may be the same account, or converting to the raw form that indexers and APIs expect. Accepts friendly (EQ…/UQ…, with or without URL-safe characters) and raw (workchain:hex) forms. Returns: raw, friendly_bounceable (EQ…), friendly_non_bounceable (UQ…), workchain and flags of the given input. Background: EQ… and UQ… encode the SAME account — EQ (bounceable) is conventional for contracts, UQ (non-bounceable) for user wallets; two addresses are equal if their raw forms match.

get_swap_quote

Firm swap quote for exchanging GRAM or any jetton into another asset on TON, via the Omniston protocol (STON.fi RFQ aggregation over STON.fi/DeDust liquidity). MAINNET only. Use when: an agent wants to know the current exchange terms, or as step 1 of an actual swap (step 2 is build_swap_tx with the returned quote_id). For swaps INTO another blockchain (ETH, Base, BNB…) use get_crosschain_quote instead. Amounts are raw indivisible units — GRAM has 9 decimals (1 GRAM = 1e9), USDT has 6; read a jetton's decimals via run_get_method get_jetton_data if unsure. Returns: quote_id (pass it to build_swap_tx PROMPTLY — quotes expire in about a minute), input/output amounts, min_output_units (the on-chain slippage floor the swap will be built with — the only guaranteed minimum), price_impact_bps, integrator_fee_units (revenue share of the server operator, if configured — already deducted from output_units), gas_budget_nano (GRAM the wallet must additionally hold for gas) and the DEX route. This is a price lookup only — nothing is signed or sent.

build_swap_tx

Build the UNSIGNED transaction for a swap quoted by get_swap_quote. Non-custodial: this returns TonConnect-ready messages — nothing is signed and nothing is sent; the wallet owner signs and broadcasts them (e.g. tonConnectUi.sendTransaction(result.tonconnect)). The messages MOVE REAL FUNDS once signed, so treat the output as an armed payment and show it to the wallet owner before sending. Use when: an agent (or the app driving it) actually wants to execute the swap after inspecting the quote. Args: quote_id from get_swap_quote (use it promptly — expired quotes fail and need a re-quote) and wallet — the address that will send the transaction, receive the swap output and any gas excess. Returns: tonconnect {validUntil, network, messages[{address, amount, payload, stateInit?}]} with base64 BoC payloads, exactly the shape TonConnect sendTransaction expects. Omniston emulates the transfer while building — if the wallet lacks the input funds, this fails up front. The wallet must hold the input amount (for GRAM swaps it is included in the attached value) plus the quote's gas_budget_nano in GRAM.

get_crosschain_quote

Firm quote for swapping GRAM or a TON jetton into an asset on another blockchain (Ethereum, Arbitrum, Base, BNB, Polygon, Avalanche) via Omniston's atomic HTLC escrow settlement. MAINNET only. TON is always the source chain — the trade is initiated and funded by a TON wallet. Use when: an agent needs USDT/USDC/native coins delivered to an EVM address, paid from TON. Step 2 is build_crosschain_swap_tx with the returned quote_id. Amounts are raw indivisible units of each asset (TON USDT = 6 decimals, GRAM = 9, EVM tokens per their own decimals). Returns: quote_id (use PROMPTLY — quotes expire in about a minute), input/output amounts, fees, gas_budget_nano (GRAM needed for gas on TON), security_deposit (extra value temporarily locked in the escrow, returned on completion), htlc_hashing_function (COPY IT VERBATIM into build_crosschain_swap_tx) and estimated_settlement_seconds for the full cross-chain trade. This is a price lookup only — nothing is signed or sent.

build_crosschain_swap_tx

Build the UNSIGNED TON escrow transaction for a cross-chain swap quoted by get_crosschain_quote, and generate the HTLC secret that later completes it. Non-custodial: nothing is signed or sent, and the server does NOT keep the secret — it exists only in this response. The messages MOVE REAL FUNDS once signed; treat the output as an armed payment. Treat htlc_secret like a payment authorization: anyone who sees it together with quote_id can trigger disclosure — keep this response out of logs and shared contexts. EVERY CALL GENERATES A NEW SECRET bound to THIS tonconnect 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 no longer track. THE FLOW AFTER THIS CALL: (1) the wallet owner signs and sends result.tonconnect; (2) poll track_crosschain_swap every ~10s; (3) when an execution's dst_phase reaches ready_for_private_completion, call disclose_crosschain_secret PROMPTLY with htlc_secret (the tool re-verifies the on-chain state before revealing anything); (4) if nothing fills and cancellation_mode becomes onchain, reclaim funds with build_crosschain_refund. STORE htlc_secret UNTIL THE TRADE COMPLETES — without it the trade cannot settle (funds remain refundable after the timeout, but the swap is lost).