Skip to main content
The x402 protocol revives the long-dormant HTTP 402 Payment Required status code and puts it to work for machine-to-machine micropayments. Instead of API keys, subscriptions, or out-of-band billing, an x402-enabled server embeds the exact price and payment destination in the HTTP response itself — and the client pays inline, inside the same logical request cycle. Agora402 uses x402 as the payment layer for every call a buyer agent makes to a seller service, with Hedera as the settlement network.

​
What x402 Is

HTTP has carried a 402 Payment Required status code since 1991 but left it “reserved for future use.” The x402 specification defines that future use: when a server needs payment for a resource, it returns 402 with a PAYMENT-REQUIRED header that encodes the payment scheme, network, asset, amount, and destination. The client — a wallet, an agent, or any x402-aware HTTP client — builds and signs a payment transaction, then retries the original request with a PAYMENT-SIGNATURE header. The server verifies and settles the payment, then runs the handler. No redirect, no pre-registration, no API key handshake.

​
The Full Request Flow

1

Client sends the initial request

The buyer agent calls the seller endpoint normally — for example, POST /v1/infer with a chat messages body. The request reaches the @x402/express middleware before the handler runs.
2

Server returns HTTP 402 with payment terms

The middleware rejects the unpaid request with 402 Payment Required and attaches a PAYMENT-REQUIRED header encoding the exact payment requirements:
Example 402 response headers
The amount is computed dynamically from the request body — for the inference endpoint, it reflects the actual input token count and the budgeted output tokens. If the buyer attached a quoteId, the middleware uses the locked quote amount instead.
3

Buyer builds and signs a Hedera TransferTransaction

@x402/fetch on the buyer side intercepts the 402. It runs the configured spend controls (per-call cap, session budget, allowed assets) and, if the amount is acceptable, hands off to @x402/hedera. The Hedera exact scheme constructs a TransferTransaction that moves exactly amount tinybars (or token units) from the buyer account to payTo, designating the Blocky402 fee-payer account (extra.feePayer) as the Hedera transaction fee payer. The buyer signs the transaction with their own account key — only their transfer signature, not the fee-payer signature — and the partially signed transaction is base64-encoded into a PAYMENT-SIGNATURE header. The original request is retried with this header attached.
4

Seller middleware calls Blocky402 /verify

Before the handler runs, the @x402/express middleware sends the partially signed transaction to Blocky402 POST /verify. Blocky402 decodes the transaction, checks the buyer’s signature, confirms the transfer amounts match the requirements, and verifies the buyer account has sufficient balance. If verification fails, the server returns 402 again without running the handler and without charging the buyer.
5

Server runs the handler

With the payment verified, the middleware allows the request through to the actual route handler — the LLM inference call, the HBAR/USD rate lookup, or any other service. The handler executes normally and returns a response.
6

Settlement fails fast on errors

If the handler returns a 4xx or 5xx status, the middleware cancels settlement entirely. The buyer is never charged for a request that fails. This guarantee is built into the @x402/express middleware and applies to every endpoint.
7

Seller middleware calls Blocky402 /settle

On a successful handler response, the middleware calls Blocky402 POST /settle. Blocky402 co-signs the transaction as the Hedera fee payer, submits the fully signed TransferTransaction to the Hedera network, and returns the Hedera transaction ID. The final response to the buyer includes a PAYMENT-RESPONSE header:
Example settled response headers
The buyer agent reads this transaction ID, queries the mirror node to confirm the transfer, and surfaces the HashScan link.

​
PAYMENT-REQUIRED Header Fields

The PAYMENT-REQUIRED header carries all the information the buyer needs to construct a valid payment. Each field is documented below.

​
x402 Packages

Agora402 is built on the open x402 package ecosystem. You interact with the buyer-side packages directly; the seller-side packages run inside the service you connect to.

@x402/fetch

The buyer-side fetch wrapper. Wrap your fetch calls with wrapFetchWithPayment and it automatically intercepts 402 responses, runs your spend policies, builds the payment, and retries. Import from the @x402/fetch package.

@x402/hedera

The Hedera-specific exact scheme implementation. Constructs and partially signs TransferTransaction objects for both buyer (ExactHederaScheme) and verification. Used internally by @x402/fetch once registered for the hedera:* network prefix.

@x402/express

The seller-side Express middleware. Issues 402 challenges with per-request pricing, calls Blocky402 for verify and settle, and triggers receipt writing after each successful settlement. Runs inside the Agora402 seller service.

@x402/core

Shared types used by all other packages: PaymentRequirements, SettleResponse, x402Client, x402HTTPClient. Import these for typed access to payment objects in your agent code.
If a seller endpoint returns any 4xx or 5xx status code, the @x402/express middleware cancels the settlement call to Blocky402. The buyer’s TransferTransaction is never submitted to Hedera and no funds leave the buyer account. You are only charged when the seller delivers a successful response.

​
Spend Controls on the Buyer

The BuyerAgent configures two layers of protection before any payment is created:
Set as maxPerCall in atomic units when constructing BuyerAgent. The x402 spend controls inside @x402/fetch reject any PAYMENT-REQUIRED header whose amount exceeds this value, even before the transaction is built. The request fails immediately rather than paying more than you authorized for a single call.
Set as sessionBudget in atomic units. A registered policy checks the remaining budget (sessionBudget - totalSpent) against the incoming amount. If no offered option fits within the remaining budget, the agent emits a failed event and does not proceed. The session budget accumulates across all calls in a single BuyerAgent instance.
A policy filters out any PAYMENT-REQUIRED option that does not match the agent’s configured asset (0.0.0 for HBAR by default) and the configured Hedera network. If a seller offers multiple payment options, only the matching one is used.