feat(tvm): add TON mechanism for exact payment scheme

[ohld]

Summary

Adds full TVM (TON) mechanism support to x402 — both Python and TypeScript SDKs — so anyone using pip install x402[tvm] or @x402/tvm can pay and accept TON payments out of the box, matching the existing EVM/SVM pattern.

What's included

Python SDK (python/x402/mechanisms/tvm/)

• ExactTvmClientScheme — builds gasless USDT payments on TON using TONAPI relay
• ExactTvmServerScheme — price parsing with 6-decimal USDT default
• ExactTvmFacilitatorScheme — verify (Ed25519 + 5 field checks) + settle via TONAPI gasless/send
• ClientTvmSigner / FacilitatorTvmSigner protocol definitions
• TonapiProvider concrete implementation (lazy-imported to avoid hard httpx dep)
• BoC parser, address normalization, Ed25519 verification utilities
• register_tvm_exact() — V2 only, wildcard tvm:* network
• 72 unit tests passing

TypeScript SDK (typescript/packages/mechanisms/tvm/)

• ExactTvmScheme (client) — gasless USDT payment flow with W5R1 wallet signing
• ExactTvmScheme (server) — price parsing matching EVM/SVM pattern
• ExactTvmScheme (facilitator) — full Ed25519 signature verification (tweetnacl) + settle
• ClientTvmSigner / FacilitatorTvmSigner type definitions
• toClientTvmSigner() / toFacilitatorTvmSigner() factory functions
• 49 unit tests passing (including real cryptographic fixtures)

Dependencies

• Python: pytoniq-core>=0.1.36, PyNaCl>=1.5, httpx>=0.28.1 (optional tvm extra)
• TypeScript: @ton/ton, @ton/core, @ton/crypto, @ton-api/client, @ton-api/ton-adapter, tweetnacl

Related

• Spec PR: specs(exact): propose TON exact scheme for x402 v2 (spec-only) #1455 (x402 payment scheme for TON)
• Live facilitator: ton-facilitator.okhlopkov.com — running the same verify/settle logic
• TypeScript POC: ohld/x402-ton-poc — working client signing demo
• Facilitator repo: ohld/x402-ton-facilitator — standalone facilitator with E2E tests

TON gasless payment flow

Client                    Server                   Facilitator
  |                         |                         |
  |--- GET /resource ------>|                         |
  |<-- 402 + requirements --|                         |
  |                         |                         |
  | [resolve jetton wallet] |                         |
  | [estimate gasless fee]  |                         |
  | [sign W5R1 transfer]    |                         |
  |                         |                         |
  |--- GET + x-402 header ->|                         |
  |                         |--- verify(payload) ---->|
  |                         |    [Ed25519 sig check]  |
  |                         |    [field validation]   |
  |                         |<-- {isValid: true} -----|
  |                         |--- settle(payload) ---->|
  |                         |    [gasless/send relay]  |
  |                         |<-- {success: true} -----|
  |<-- 200 + resource ------|                         |

Network identifiers

Network	CAIP-2	Chain ID
TON Mainnet	tvm:-239	-239
TON Testnet	tvm:-3	-3

Test plan

• Python: uv run pytest tests/unit/mechanisms/tvm/ -v — 72 tests passing
• TypeScript: pnpm test in typescript/packages/mechanisms/tvm/ — 49 tests passing
• E2E: testnet gasless payment flow (in facilitator repo)
• Integration: pip install "git+https://github.com/ohld/x402.git@feat/mechanism-tvm-exact#subdirectory=python/x402" with [tvm] extra

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[vercel]

@ohld is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

[phdargen]

FYI, we have some guidelines for the implementation of new networks here: https://github.com/coinbase/x402/blob/main/CONTRIBUTING.md#new-chains

[ohld]

Thanks for the pointer to CONTRIBUTING.md, @phdargen. Splitting this PR to TypeScript-only per the guidelines — just pushed a commit removing all Python TVM files. Python implementation will follow in a separate PR after TS merges.

Testnet E2E setup: happy to prepare everything for testing — deploy a test jetton on TON testnet, fund wallets with testnet TON and test tokens, share private keys privately.

If you'd like me to set it up for you, ping me on Telegram: https://t.me/okhlopkov

Or self-service:

• Testnet TON: @testgiver_ton_bot on Telegram (2 TON per request)
• Deploy test jetton: @ton/ton SDK, TEP-74 standard
• Testnet explorer: https://testnet.tonviewer.com
• Facilitator testnet mode: TESTNET=true env var

[cb-heimdall]

Review Error for SAFIR143 @ 2026-03-17 04:47:32 UTC
User failed mfa authentication, either user does not exist or public email is not set on your github profile. \ see go/mfa-help