Cross-Chain Swaps from TON to Avalanche: How It Works

Why an agent needs to move value from TON to Avalanche

Your agent just spotted a great price on an asset over on Avalanche — but its entire balance sits in GRAM on TON. What follows is a familiar kind of hell: withdraw GRAM to an exchange, wait for the deposit to clear, pass KYC, buy the target token, withdraw to the Avalanche network, and pay for every step in fees and time. Five manual operations, three trusted intermediaries, and half an hour during which the price has already moved on.

For a human, that's annoying. For an autonomous AI agent, it's fundamentally incompatible with autonomy: it has no exchange account and no right to pass identity verification on your behalf, and you simply can't build a reliable pipeline on top of a custodian that can freeze withdrawals at any moment. At every step, someone else is holding your money — and the agent has to stash an exchange API key or a hot wallet seed phrase somewhere.

A TON → Avalanche cross-chain swap solves this differently. No exchange in the middle. Funds move between chains under a mathematical guarantee — "either the trade settles on both chains, or nobody loses anything" — rather than an intermediary's promise. Let's break down exactly how this works through TONNode's MCP tools: no custodian, no keys stored on the server.

How atomic HTLC escrow between TON and Avalanche works

The core mechanism is an atomic HTLC escrow (hashed timelock contract). Sounds heavyweight, but the idea is simple, and a safe-deposit-box analogy explains it nicely.

You put funds into a box that only opens with the right key — the secret. The box has a timer: if the key isn't inserted within the allotted time, the contents return to their owner. Now set up two such boxes — one on TON, one on Avalanche — and lock them with the same lock:

• A random secret S is generated along with its hash H = hash(S). You can't recover the secret from the hash, but it's trivial to verify that a presented secret matches it.
• On the TON side, you deposit GRAM into an escrow with hashlock H.
• On the Avalanche side, the counterparty (a market maker) deposits the target asset into their escrow with the same H.
• When you reveal secret S to claim the asset on Avalanche, S becomes public on-chain. The market maker sees it and uses the same S to claim your GRAM from the TON escrow.

Hence the word atomic. Unlocking one escrow without unlocking the other is impossible: there's one secret across both chains. Either both sides receive their funds, or once the timeout expires, both take their own back via refund. The intermediate state of "money left TON but the asset never arrived" simply doesn't exist.

The guarantee here comes from cryptography and timeouts, not an intermediary's reputation. And that's exactly why no exchange is needed in the middle.

The five cross-chain tools: quote, build, track, disclose, refund

In TONNode, cross-chain is covered by exactly five MCP tools, each owning one phase of the trade:

• get_crosschain_quote — the quote: how much of the asset on the target chain you'll get for your GRAM or jetton, accounting for the route and the timeouts.
• build_crosschain_swap_tx — builds the unsigned HTLC escrow transaction for TON and returns the associated secret (plus its hash). The user's wallet signs the transaction.
• track_crosschain_swap — shows the trade's phases on both chains: whether your deposit has landed in the TON escrow, and whether the counter-escrow has appeared on Avalanche.
• disclose_crosschain_secret — reveals the secret for settlement, after an on-chain readiness check (the counter-escrow exists, the amounts and hash match).
• build_crosschain_refund — builds the transaction to pull your funds back out of escrow if the trade stalled and the timeout has passed.

Five tools isn't "too few." These are precisely the five steps an atomic swap physically consists of: quote, deposit, track, settle — and refund on failure. Not one extra, not one missing.

Non-custodial: the server never signs and never holds keys

This isn't marketing language — it's an architectural constraint. TONNode's cross-chain, swap, and wallet tools are strictly non-custodial:

• The server never signs transactions and never holds funds or private keys.
• build_crosschain_swap_tx returns an unsigned TonConnect message. The signature comes from the user's wallet — Tonkeeper, MyTonWallet, or any TonConnect-compatible wallet. The server merely assembled a correct transaction envelope.
• The HTLC secret S is generated by the server and handed to you along with the built transaction — from then on, revealing it stays under your control. Even calling disclose_crosschain_secret is a deliberate step you initiate after the on-chain check, not an automated action somewhere on a backend.

If the TONNode server vanished mid-trade, your funds wouldn't be lost: they sit in escrow on the blockchain, and build_crosschain_refund will return them once the timeout expires. For moving value between chains, non-custodial means one simple thing: there is nothing on the server to steal and nothing to freeze.

Compare that to the custodial model, where the operator holds the key and signs on your behalf. Both models have their place — we drew that line in detail in the post on custodial vs non-custodial MCP and in the deep dive on the non-custodial swap for agents.

Which networks are supported (and why TON is always the source)

The cross-chain target networks: Ethereum, Arbitrum, Base, BNB Chain, Polygon, Avalanche. TRON is not supported yet — don't build it into your pipelines.

One important directional constraint: TON is always the source of the swap. You deposit GRAM or a jetton into the TON escrow and claim the counter-asset on the target EVM chain. This follows from the mechanics: the HTLC is initiated by a deposit on TON, where your wallet and your balance live, and the counterparty mirrors it on the target chain.

The practical takeaway: if your agent lives on TON and needs to deliver value to Avalanche — that's exactly the scenario this was built for. If you need to move funds into TON from outside — that route doesn't exist right now. Cross-chain from TON to Ethereum works identically — only the target-network parameter changes; see the breakdown in the TON → Ethereum swap.

Step-by-step: swapping GRAM → Avalanche

Let's put it all together. Below is the actual call sequence; the agent walks through it on its own — all you do is sign a transaction in your wallet.

Step 1. The quote. The agent asks for a price:

"Get me a cross-chain quote: 500 GRAM from TON to USDC on Avalanche."

Under the hood: get_crosschain_quote. The agent sees the output amount, the route, and the timelock parameters. If the price works, we move on.

Step 2. Building the HTLC escrow transaction.

"Looks good. Build the transaction for this quote to my Avalanche address 0x… and return the unsigned TonConnect message and the secret hash."

This calls build_crosschain_swap_tx. It returns the unsigned deposit transaction for the TON escrow plus the secret and its hash H. The user signs the message with their wallet via TonConnect — this is the moment the GRAM goes into escrow on TON. The server never touches the signature.

Step 3. Tracking the counter-escrow.

"Watch the trade with track_crosschain_swap until a counter-escrow with my hash appears on Avalanche."

track_crosschain_swap shows the phases on both chains. We wait for the market maker to deposit the target asset into their escrow on Avalanche under the same H. Until that counter-escrow is there, the secret must not be revealed.

Step 4. Revealing the secret and settling. Once tracking confirms on-chain readiness:

"The counter-escrow is in place. Verify readiness on-chain and reveal the secret with disclose_crosschain_secret."

disclose_crosschain_secret first checks readiness (the counter-escrow exists, the amounts and hash match), then reveals the secret. It unlocks both escrows: you receive USDC on Avalanche, and the counterparty uses the same S to claim the GRAM from the TON escrow. The trade closes atomically.

Step 5 (failure path only). The refund. If the counter-escrow never showed up and the trade stalled, don't reveal the secret. Wait out the timeout and call build_crosschain_refund:

"The trade stalled and the timeout has expired. Build a refund with build_crosschain_refund."

The tool builds a transaction returning the GRAM from the TON escrow back to you; the user signs it with their wallet. Losing funds to a stalled counterparty is impossible by design — the timelock protects them.

Note the discipline here: the secret is revealed only after tracking has confirmed the counter-escrow. Revealing it early is the only way to get burned, which is exactly why this step lives in its own explicit tool instead of being buried in automation.

Connecting the MCP server, and what's next

First, an important fork in the road, so you don't waste time. The @tonnode/mcp package is open source (MIT, GitHub tonnode/mcp) and speaks TON's native ADNL protocol, with no HTTP layers in between. Run it locally with the public config and you get the full read set (8 read tools: balance, account state, transactions, get-methods, and so on) — enough to read TON, but it does not include swap, cross-chain, or wallet tools. The local MCP client config (Claude, Cursor, Codex, or any MCP-compatible client):

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

The five cross-chain tools from this article (along with swap and wallet generation) work only through the hosted endpoint mcp.tonnode.io with a Bearer key. The Hobby key is free and issued right after sign-in, no card required (60 requests/min) — but it is specifically a hosted key, not the bare local npx. The config for the cross-chain pipeline:

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": { "Authorization": "Bearer tn_live_…" }
    }
  }
}

A few facts that clear up the usual questions:

• TONNode has 16 tools total. All 16 are available on every plan — you pay for throughput, not for "unlocking features." The difference between the two configs above isn't the tool set, it's the connection point: local npx gives you read-only, while the hosted endpoint with a key opens up the full set, including the five cross-chain tools.
• GRAM is Toncoin, renamed in June 2026. The network is still called TON; only the coin's name changed.
• The free Hobby key — 60 requests per minute, no card — is enough to run the full cross-chain pipeline end to end.

What's next

If your agent already lives on TON and you need to deliver value to Avalanche (or Ethereum, Base, Arbitrum, BNB Chain, Polygon) — wire up the chain get_crosschain_quote → build_crosschain_swap_tx → track_crosschain_swap → disclose_crosschain_secret and keep build_crosschain_refund as your safety net. Why cross-chain from TON is worth doing through MCP at all, rather than through an exchange, is something we cover separately in this post.

Grab a free Hobby key and hook up the cross-chain tools right now: tonnode.io/dashboard?plan=hobby. No card needed, and 60 requests/min is enough to run the full pipeline and see atomic HTLC in action.

Browse all 16 tools on the tools page. See what's coming next on the roadmap.