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, 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 a credential.
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:

# the resource's challenge, saved from its 402 answer or created by the payee:
tenzro payment challenge /v1/chat/completions --amount 100000 --protocol x402 > challenge.json

# sign a credential with this machine's hardware key and pay it
tenzro payment pay --challenge @challenge.json \
  --payer-did did:tenzro:human:<you> \
  --max-amount 100000

From TypeScript, with npm install tenzro-sdk (and @tenzro/device-key for the hardware key):

import { HardwareKeySigner, TenzroClient, openHardwareSigner, type PaymentChallenge } from "tenzro-sdk";

const client = new TenzroClient({ endpoint: "https://rpc.tenzro.com" });
const signer = openHardwareSigner({ label: "tenzro/wallet" });
if (!(signer instanceof HardwareKeySigner)) throw new Error("no TPM or Secure Enclave on this machine");

// The challenge from the resource's 402 answer, or one a payee created with
// client.payment.createChallenge(resource, amount, asset, "x402").
declare const challenge: PaymentChallenge;
const receipt = await client.payment.payChallenge(challenge, signer, "did:tenzro:human:<you>", 100_000n);
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

A seller answers an unpaid request with 402 Payment Required and a signed offer in the PAYMENT-REQUIRED body: the scheme, network, asset, payee and amount it accepts. Listings are signed by the seller's DID key, and the payee must be an address bound to that DID. Buyers check the seller's signature on an offer before paying, then pay and fetch in one step:

# Check the signed offer a resource returned
tenzro x402 verify-offer --required-file ./payment-required.json

# Pay the resource's 402 from your account and fetch it
tenzro x402 pay https://api.example.com/forecast

tenzro x402 list-schemes (JSON-RPC tenzro_listX402Schemes) shows the schemes and settlement networks a node accepts, and tenzro_x402VerifyOffer checks an offer over JSON-RPC.