The x402 protocol brings HTTP 402 Payment Required to life on TON — enabling autonomous machine-to-machine payments for the 1B+ Telegram user ecosystem.
AI agents need to access hundreds of APIs autonomously. Today's authentication model was designed for humans, not machines.
A Claude agent receives a task, discovers a paid API, sends TON automatically via x402, and retrieves premium data — zero human intervention.
From AI research agents to Telegram bot economies — x402 enables entirely new business models where machines transact autonomously.
Agents autonomously access premium data sources — financial feeds, scientific databases, proprietary datasets — paying per-request without pre-registration.
Monetize any API endpoint with a single middleware line. No Stripe, no billing dashboard, no invoices. Revenue flows directly to your TON wallet in real-time.
Agents compose services from other agents. An orchestrator agent pays specialist agents for translation, summarization, image generation — all via x402.
Build Telegram bots that offer premium features with instant TON payments. 1B+ users already have TON wallets in Telegram — zero friction to pay.
TON combines the speed, cost, and reach needed for autonomous agent infrastructure at global scale.
| Feature | TON (this project) | Base | Solana | Aptos | Ethereum |
|---|---|---|---|---|---|
| x402 Protocol | Yes | Yes | Yes | Yes | Yes |
| Tx Finality | ~5s | ~2s | ~0.4s | ~1s | ~12s |
| Tx Fee | ~$0.01 | ~$0.01 | ~$0.001 | ~$0.005 | $1-10 |
| Micropayments | Excellent | Good | Excellent | Good | Poor |
| Built-in User Base | 1B+ (Telegram) | Growing | Growing | Growing | Large |
| MCP Server for AI | Included | No | No | No | No |
| Composable Packages | 5 npm packages | 1 SDK | 1 SDK | 1 SDK | 1 SDK |
| Test Coverage | 34 tests | N/A | N/A | N/A | N/A |
Standard HTTP semantics. No new protocols to learn. If your agent can make HTTP requests, it can pay for APIs.
Agent sends a standard GET/POST to any API endpoint.
Server responds with payment details: recipient wallet, amount, and network.
Client auto-sends TON to the specified recipient. ~5s confirmation.
Request is retried with the payment proof in headers (base64 BOC).
Server verifies the transaction on-chain and returns premium data.
Every design decision optimizes for real-world deployment. Zero dependencies in the core, comprehensive tests, and safety-first architecture.
Every payment is verified directly against the TON blockchain. Not trusted headers — cryptographic proof via BOC deserialization.
Configurable maxAutoPayAmount prevents accidental overspending. Agents can estimate costs before paying via x402_estimate.
Unique paymentId per 402 response prevents double payments. Clients and servers can safely retry without duplicate charges.
@ton-x402/core has zero external dependencies. Shared types and utilities with no supply-chain risk. Tree-shakeable ESM + CJS builds.
Production-ready, fully typed TypeScript packages. Use the full stack or pick individual layers. Each package has a single responsibility.
Hit the live endpoints below. Free endpoints return 200 OK. Premium endpoints return 402 with TON payment details — exactly what an x402 client would see.
Protect your API with payment gates, build auto-paying clients, or give your AI agent a TON wallet via MCP.
// npm install @ton-x402/server hono import { Hono } from "hono"; import { x402 } from "@ton-x402/server"; const app = new Hono(); // One line to payment-gate any endpoint app.use("/api/premium/*", x402({ recipient: "UQB...your-wallet", amount: "0.05", // 0.05 TON per request network: "testnet", })); app.get("/api/premium/data", (c) => { return c.json({ data: "premium content" }); });
// npm install @ton-x402/client import { X402Client } from "@ton-x402/client"; const client = new X402Client({ mnemonic: process.env.TON_MNEMONIC.split(" "), network: "testnet", maxAutoPayAmount: "0.1", // Safety cap }); // Fetch like normal - payment is invisible const res = await client.fetch("https://api.example.com/premium/data"); const data = await res.json(); // That's it. 402 -> pay -> retry happened automatically.
// Add to your AI agent's MCP config (Claude, GPT, etc.) // npm install @ton-x402/mcp { "mcpServers": { "ton-x402": { "command": "npx", "args": ["ton-x402-mcp"], "env": { "TON_MNEMONIC": "word1 word2 ... word24", "TON_NETWORK": "testnet" } } } } // Your AI agent now has these tools: // // x402_fetch - Fetch any URL, auto-pay if 402 // x402_balance - Check TON wallet balance // x402_estimate - Preview cost without paying // x402_history - View recent payments
# 1. Free endpoint - returns 200 OK curl /api/info # 2. Premium endpoint - returns 402 Payment Required curl -i /api/premium/joke # Response headers: # HTTP/2 402 # X-Payment-Protocol: x402-ton # # Response body: # { "recipient": "UQDr...EPz4", # "amount": "10000000", # "token": "TON", # "network": "testnet" } # 3. After paying on TON, retry with proof: curl -H "X-Payment-Proof: <base64-boc>" \ -H "X-Payment-Id: <payment-id>" \ -H "X-Payment-Sender: <your-wallet>" \ /api/premium/joke
ton-x402 is shipping today with a clear path to production deployment. Each milestone is scoped and achievable.
5 packages. 34 tests. Full TypeScript. Zero-dep core. Whether you're monetizing APIs or building autonomous agents, ton-x402 gets you there in minutes.
Install now: npm install @ton-x402/client @ton-x402/server