TOONProtocol
Docs

Start here

Overview The agent node Connector concepts Where TOON sits FAQ

Run an agent node

Install Your first agent node Networks and reachability Money Agent keys Peering Adding an app Creating a TOON app The relay Operations Backup and restore

The connector, by hand

Run a node Put your app behind it Get paid Peer with another node The operator surface Hidden services

Callers

Pay a node Payment channels CLI reference Errors and reject codes

Agents

spaceturtle

Reference

Devnet reference Protocol and specs Exit codes Proof

Start here

FAQ

The questions operators and callers ask, with short answers and where to read on.

Is TOON an x402 facilitator?

No. A facilitator verifies and settles payments for a seller as a hosted service, usually for a fee per settlement. A TOON node is software you run: it verifies vouchers itself, offchain, and settles its own channels in batches. Every TOON channel is an x402 batch-settlement channel, so the contracts and the 402 document are x402's; the node is yours. There is no fee to anyone but you.

Do I have to change my app?

No. Your app is an ordinary HTTP service behind a route's handler_url. It receives an ordinary HTTP request, holds no key on your behalf, and never sees a payment. The relay, the store and the gas station on the landing page contain no payment code at all.

Which chains and tokens?

The live node settles in USDC on Base mainnet and Solana mainnet. You choose the token and chain in the settlement block of your config. On EVM the channel contract is x402's x402BatchSettlement; on Solana it is the Solana Foundation's payment-channels program. Base Sepolia and Solana devnet are the devnets.

What is the smallest payment?

One base unit of the token. In USDC that is a millionth of a dollar. A voucher is a signature, so a tenth of a cent is a real price with no gas attached to it.

Does a caller need an account or an API key?

No. A caller needs a wallet with a deposit in the token the node prices in. It opens a channel once and attaches a voucher to each request. The node never learns who the caller is beyond the key that signs.

What happens to an unpaid request?

It is refused before it reaches your app, with an x402 402 Payment Required that states the exact price, token, chain and address. The caller pays and sends again. A refusal is a value in the client, not an exception. The 402 answers a well-formed packet that carries no voucher; a bare curl -X POST /ilp is not a packet and gets a 400. To read a price by hand, GET /ilp lists every route with its price.

When does the money land?

Claims are free and cumulative; the node lands the latest voucher on chain in batches, every ten minutes by default, and right away if the payer starts a withdrawal. One transaction settles everything since the last one.

What does TOON itself charge?

Nothing. The software is MIT licensed and there is no protocol fee. What a caller pays lands in the operator's channel, minus nothing. Gas for a batch settlement is paid by whoever lands it, once per batch, not per request.

Where do I find other nodes and apps?

There is no discovery layer by design (ADR 0046): a node answers for itself at GET /ilp and announces nothing. A peering is made from a URL (ADR 0058). The apps on the landing page are the ones the project runs; anyone can run the same images. The devnet reference lists three public nodes and six routes you can pay today without real money.