x402

x402 is an open protocol that puts payment inside HTTP. A server answers a request with 402 Payment Required and a description of what to pay; the client signs a payment and retries; the server verifies, settles and serves. On Tenzro Network 1, every paid route on a node speaks x402, including the OpenAI-compatible inference APIs, storage, databases and hosted sites.

Every Tenzro node runs its own x402 facilitator. Verification and settlement happen on the node that serves the request, against the Tenzro ledger, with no third party in the path.

How a payment works

1. The client calls a paid resource without an API key.
2. The node returns 402 with one or more payment requirements: scheme, network, asset, payee (payTo), maximum amount and a validity window.
3. The client picks a requirement, signs a payment payload with the paying account's key and retries the request with it.
4. The node verifies the payload, settles it on the ledger and serves the response with a receipt.

The requirement is bound to the resource, payee and amount it was issued for, and the debited account is always the one whose key signed the payload. A receipt is returned once the settlement transaction is in a finalised block.

Schemes

A requirement names its scheme, and the node dispatches to the matching verifier. Each scheme signs a domain-separated preimage, so an authorisation for one scheme can never be replayed as another.

List what a node supports:

tenzro x402 list-schemes

or call the open method tenzro_listX402Schemes.

Metered payments with upto

An inference or query endpoint rarely knows the cost before it runs. With upto, the buyer authorises a maximum once. The provider serves the request, meters what was used, for example tokens generated, and captures that amount against a usage record from the serving node. The capture can never exceed the signed ceiling. Metered, per-use settlement is the default for Machine Economy services. See SLA attestation and metering.

Batch settlement

For per-token billing or per-epoch storage, settling every charge on-chain is wasteful. With batch-settlement, the buyer deposits into a channel and signs a cumulative voucher for each charge. Each voucher commits to the channel and the running total, so the provider only needs the latest one. At close, the provider redeems it against the deposit in a single transaction and the remainder returns to the buyer.

The node's facilitator

Each node exposes its facilitator on its web API:

For stablecoin schemes, the facilitator runs the full set of checks before it submits anything: network, payee and amount match the requirement; the signed time window is current; the signature recovers to the payer; the nonce is unused; the payer holds the funds; and the transfer simulates successfully. Only then does it submit the transfer on the chain where the asset lives. The signer the facilitator uses is hardware-rooted, like every key on the network.

Stablecoin payments over x402 are covered in Stablecoin payments.

Paying from the CLI

Pay a resource through a node, with a spending ceiling:

tenzro payment pay https://rpc.tenzro.xyz/v1/chat/completions \
  --protocol x402 \
  --payer-did did:tenzro:human:<you> \
  --max-amount 100000

Or submit a payload your wallet has already signed against a saved challenge:

tenzro x402 pay --challenge-file challenge.json --payload-file payment.json

From TypeScript, with npm install tenzro-sdk:

import { TenzroClient } from "tenzro-sdk";

const client = new TenzroClient({ endpoint: "https://rpc.tenzro.xyz" });
const receipt = await client.payment.payX402(
  "https://rpc.tenzro.xyz/v1/chat/completions",
  "did:tenzro:machine:<agent>",
);
console.log(receipt);

Paying is an owner action: the request must be signed by the paying account, and an agent's delegation scope and spending limits apply. See Payments.

Selling a resource

Any seller can list a paid resource so that buyers and agents find it without prior contact. Listings are signed by the seller's DID key, and the payee must be an address bound to that DID.

tenzro x402 register-resource \
  --seller-did did:tenzro:machine:<you> \
  --resource https://api.example.com/forecast \
  --scheme upto \
  --network <network-id> \
  --asset TNZO \
  --pay-to 0x<your-address> \
  --max-amount-required 2000000000000000000 \
  --description "7-day demand forecast" \
  --tags forecasting,timeseries

tenzro x402 discover-resources --scheme upto --tags forecasting

--network takes the settlement network identifier; tenzro x402 list-schemes shows the networks the node accepts. Buyers can check the seller's signature on an offer with tenzro x402 verify-offer before paying. tenzro x402 deregister-resource withdraws a listing. Discovery can be narrowed by scheme, network, asset, tags and a minimum seller reputation.

Idempotency

A retried request must not charge twice. tenzro x402 payment-id (method tenzro_x402PaymentId) derives a deterministic identifier from the offer and the authorisation, so a repeated settlement collapses into the first. tenzro_x402ProtocolInfo reports the schemes, networks and facilitator a node runs.