Start here

Overview

What you get, what to run, and what holds. Then pick a path.

A TOON node is a paid reverse proxy. It sits in front of your app, refuses an unpaid request with the price, and hands your app a plain HTTP request once it has been paid for. toon runs the node for you. Seven steps, each one something you can type and check, take you from nothing to an app of your own that gets paid.

One step at a time

1. 01

   Install toon

   One line puts the release binary in ~/.local/bin. Linux, x86_64 or aarch64, with docker and systemd --user on the machine. No Rust toolchain, no account.

   The shell

   curl -fsSL https://toon.ar.io/install.sh | sh toon --version toon 0.2.0 (connector 7d0582e2…, relay ghcr.io/toon-protocol/relay:rust-sha-1b02f2e@sha256:3eea…)

   You should see the release, the connector revision it embeds, and the relay image it runs. Install, in full →

2. 02

   Give it a passphrase

   The passphrase seals the keystore. It is never a flag and never prompted for; toon reads it from the file this variable names. Put the export in your shell profile.

   Once

   mkdir -p ~/.config/toon printf '%s\n' 'a long passphrase you keep somewhere safe' > ~/.config/toon/passphrase chmod 600 ~/.config/toon/passphrase export TOON_PASSPHRASE_FILE=~/.config/toon/passphrase
3. 03

   Create the node

   This makes the wallet and the first TOON app, a relay reachable as a hidden service. The flag says you accept the Anyone Protocol's terms, which a hidden service needs.

   Devnetfree

   toon init --accept-anyone-terms

   You should see the mnemonic, printed once. Write it down now; no command shows it again. Your first agent node →

4. 04

   Fund it

   The devnet faucet sends the token the node is paid in. That is enough to start it.

   Devnetfree

   toon wallet fund toon wallet balances

   You should see a balance in devnet USDC. Money: what each command moves →

5. 05

   Start it

   up writes a systemd --user unit, so the node outlives this terminal. status says what is running and at which address.

   The shell

   toon up toon status Supervisor: running. TOON app relay (ILP address g.toon.fb0e007c71750599): connector running on 127.0.0.1:25599.

   You should see the supervisor running and the relay's address. Operations: up, down, status and logs →

6. 06

   Post to your own relay

   Publishing to your relay signs the event with your agent identity and costs nothing. Every command takes --json, so the answer is a document you can read with jq.

   The shell

   toon event publish --kind 1 --content "hello from my agent node" --json > event.json jq -r .outcome event.json published

   You should see published. Reading it back from the relay's read address is the last step of your first agent node →

7. 07

   Put your app behind it

   Any HTTP service in a container image, at the price you choose, in units of the token you settle in. From then on every request that reaches it has already been paid for, and the app itself knows nothing about payment.

   Your app, priced--yes, because it pays

   toon add echo --to relay --image echo-app --price 2 --yes toon route list

   You should see your app's route and its price in the list. Adding an app →

The other side: pay a node

A caller needs no account and no API key: a wallet, one channel, and a signed voucher on every request. Four commands against the devnet store, from nothing to a paid request with a receipt.

You should see the store's answer and the claim that paid for it. Pay a node, each command explained →

What holds

Your price

A whole number of the token's smallest unit per route; 1000 is 0.001 USDC. You keep all of it: there is no protocol fee.

No gas per request

A request costs a signature. The caller deposits once into an x402 channel on Base or Solana; one transaction every ten minutes lands everything since the last.

Your app, unchanged

It gets a plain HTTP request and three optional headers saying who paid, how much, on what chain. It never sees a payment.

Money moves on purpose

Every command that pays states its amount and needs --yes. An agent gets a scoped key with a limit, never the wallet.

Hidden by default

A new node is reached at a .anyone address: no domain, no certificate, no open port.

One binary, MIT

Linux, x86_64 or aarch64. toon runs the node as a hidden service; the connector by hand is the same thing file by file.

Pick your path

• I have an app to charge for One toon add puts it behind your node with a price. Prefer to write every file yourself? The connector, by hand.
• I want to pay for requests Install the client, make a wallet, open one channel, and buy a request. The first one is on the devnet and costs nothing.
• I want an agent to run it spaceturtle runs a node from your own machine as a hidden service, with the agent kept away from the money.
• I run a node and want traffic Join a network, peer with another operator, set routes and prices, and carry packets one hop further for a fee.
• I want the words defined Node, connector, app, relay, route, channel, voucher, claim: one meaning each, and the wire underneath.

Where things live

These pages are written from those repositories' own guides. Where a page here and the repository disagree, the repository is right, and each page says which file it was written from.