┌── DOSSIER № 02 · PROTOCOL ──┐▌ READ-ONLY

  ┌─ AGENT ─┐         ┌─ TOOL ─┐         ┌─ BASE ─┐
  │ 0xa7f  │  ──REQ──▶│  402   │         │ chain  │
  │        │◀─QUOTE── │ x402   │  ──PAY─▶│ 8453   │
  │        │  ─RETRY─▶│        │◀─BLOCK──│  USDC  │
  └────────┘◀──200────└────────┘         └────────┘
                ~1.4s · stateless · idempotent

x402 protocol.

TOLL implements the open x402 specification for HTTP-native payments. The protocol revives the long-unused HTTP 402 Payment Required status code and gives clients — especially autonomous agents — a deterministic way to discover, pay, and retry against a paid endpoint.

SCOPE

This page covers the wire format and lifecycle TOLL respects. For the full spec, see x402.org.

The handshake

Six steps. No accounts. No sessions. The protocol is stateless at the resource layer; all state lives on-chain. Watch one loop:

┌── PROTOCOL HANDSHAKE · LOOP ──┐STEP 01 / 06

▌ AGENT

▌ BASE

▌ TOOL

01AGENT → TOOL → REQUEST▌

02TOOL → AGENT ← 402 + QUOTE

03AGENT → BASE → SIGN USDC

04BASE → AGENT ← BLOCK + HASH

05AGENT → TOOL → RETRY + RECEIPT

06TOOL → AGENT ← 200 OK + PAYLOAD

total loop: ~1.4s · cost: 0.0001 USDC + gas

Status codes

Code	Meaning	Action
`200`	OK	Tool returned a payload. Done.
`402`	Payment Required	Read payment headers, settle, retry.
`409`	Receipt Conflict	Receipt already redeemed. Pay again with a new nonce.
`410`	Tool Deprecated	Tool deregistered. Reissue against current registry.
`451`	Restricted	Tool unavailable in caller jurisdiction. Do not retry.

Payment headers

Header	Required	Description
`X-Payment-Required`	Yes	Decimal amount in the named token.
`X-Payment-Address`	Yes	Destination address (EVM hex).
`X-Payment-Chain`	Yes	CAIP-2 identifier. TOLL targets `eip155:8453` (Base).
`X-Payment-Token`	Yes	Token symbol; `USDC` for TOLL-routed tools.
`X-Payment-Nonce`	Yes	One-shot nonce. Prevents replay.
`X-Payment-Expires`	No	Quote validity window (default 30s).

Settlement

TOLL settles in USDC on Base. The gateway acts as a facilitator: it observes the on-chain transfer and admits the receipt only if it matches the quote (address, amount, nonce, expiry).

Chain: Base mainnet (chain ID 8453).
Token: native USDC, 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.
Confirmation target: 1 block (~2s).
Replay protection: nonce + per-resource bloom filter.

Retry semantics

After settlement, the client re-issues the original request with X-Payment-Receipt: 0x<txhash>. The gateway is idempotent on the receipt — the same receipt against the same resource always yields the same response within the response cache window (default 30s).

Errors

If settlement fails on-chain, the client receives 402 again with a new nonce. If the receipt is malformed, expired, or targets the wrong address, the gateway returns 409. TOLL never charges twice for one successful response.

What TOLL adds on top

A registry of MCP-style tools with schemas, prices, and reputation.
A single gateway URL so agents don't have to discover tool endpoints individually.
A curation layer staked in $TOLL that slashes operators for downtime or bad responses.

Next: $TOLL utility →