X402 Headers for Paid API Endpoints

X402 headers are where a paid API becomes understandable to software. A human can read a pricing page and click through checkout. An AI agent needs a different contract: a clear `HTTP 402 Payment Required` response, structured payment terms, a predictable proof field, and records that explain what happened after the retry.

For API sellers, this is not just a protocol detail. The header design affects whether agents can buy safely, whether developers can debug failed calls, and whether finance can reconcile many small payments later. If the payment challenge is vague, agents will hesitate or overpay. If the proof response is ambiguous, sellers will struggle to connect revenue to specific endpoint work.

Apiosk is built around this practical operating layer: get paid by AI, accept x402-style payments, support USDC on rails such as Base, keep non-custodial seller controls, bundle micropayments, and connect crypto-in activity to euro-facing settlement and reconciliation records where available.

The job of x402 headers

The primary job of x402 headers is to turn a protected API endpoint into a quoteable action. When an unpaid request reaches the endpoint, the server should not simply say "payment required." It should describe the payment requirement in a way an agent can parse without guessing.

A good challenge tells the agent what action is being priced, how much it costs, which asset and network are accepted, where payment should be directed, how long the quote remains valid, and how the agent should retry after payment. The exact field names can vary by implementation, but the information must be stable.

That stability matters because agents make budget decisions programmatically. A research agent, data enrichment workflow, or coding assistant may compare multiple tools before deciding which paid endpoint to call. It cannot do that if prices are hidden in prose or if the payment destination changes without a reference the agent can record.

Start with a clear payment challenge

The first response should be an `HTTP 402 Payment Required` challenge with structured metadata. Think of it as a short-lived quote for one protected action.

A practical challenge includes:

• `amount`: the amount required for the call.
• `asset`: the accepted token, such as USDC.
• `network`: the chain or settlement rail, such as Base when supported.
• `recipient`: the approved seller payment destination or gateway reference.
• `payment_reference`: a unique reference that links payment to the API request.
• `expires_at`: the time after which the quote should be refreshed.
• `idempotency_key`: the key the agent should reuse on retry.
• `paid_action`: a plain description of what the endpoint will do.
• `proof_header`: the header or field where payment proof should be attached.

These fields give the agent enough context to decide, pay, and retry. They also keep the seller from relying on scattered logs when a buyer asks why a call was charged.

The challenge should be specific to the endpoint. "Access to API" is too broad. "One company enrichment result for one submitted domain" is clearer.

Keep retries deterministic

Paid API integrations often fail at the boundaries: the agent pays but the retry times out, the endpoint succeeds but the client loses the response, or the agent repeats a call because it cannot tell whether proof was accepted.

The most important rule is deterministic retry behavior. If the agent retries with the same payment reference and idempotency key, the seller should be able to recognize the call. That does not mean every endpoint must return a cached result forever. It does mean the seller should avoid treating a normal retry as a brand-new unpaid action.

Useful retry response fields include:

• `payment_status`: pending, verified, rejected, expired, or already_used.
• `request_status`: not_started, running, succeeded, failed, or timed_out.
• `receipt_id`: the seller or gateway receipt for the paid call.
• `retry_after`: guidance when verification or execution is still pending.
• `error_code`: a stable reason when proof is invalid or expired.

Agents can use these fields to avoid duplicate spending. Developers can debug integrations. Sellers can identify whether an issue happened before payment verification, during endpoint execution, or after delivery.

Separate quote fields from receipt fields

A common mistake is to make the initial payment challenge carry too much responsibility. The 402 response should quote the action and explain how to pay. The verified response or receipt should document what happened.

This separation keeps the flow clean. Before payment, the agent needs price, asset, network, destination, expiration, and retry instructions. After payment, it needs proof status, endpoint result, receipt identifier, and settlement context.

For example, the initial challenge might include USDC on Base, the amount, an approved recipient reference, and a payment reference. The successful retry can then include a receipt ID, endpoint response, verification timestamp, and settlement status if it is already known. If settlement is still pending, say so and keep an identifier that can later connect to a bundle, payout, accounting export, or euro reconciliation reference.

Make headers readable

Agents prefer structured fields. Humans still need to inspect the flow.

Use concise machine-readable values for automation and plain labels for operations. A field like `paid_action_code: company_enrichment.single_domain` is useful for routing. A companion description such as "one company enrichment result for one submitted domain" helps support and finance teams understand what was purchased.

Avoid ambiguous units. If the price is per successful result, say so. If the price is per attempt, say so. If validation failures are free but downstream execution is paid, explain where that boundary sits.

Respect seller controls

X402 headers should reflect seller-approved payment policy, not ad hoc endpoint logic. The seller should control which endpoints are paid, which asset is accepted, which network is active, which payment destination is approved, and which conditions require review.

This is especially important in a non-custodial setup. Seller controls should define payment acceptance, while the API integration exposes approved terms to buyers. Practical control fields include a policy version, endpoint price version, accepted asset, network, seller account reference, and review state. Those fields do not all need to be visible to every buyer, but they should be preserved in the seller's receipt and logs.

Design for micropayment bundling

Many paid API calls will be small. Treating each call as a full finance workflow is inefficient, but ignoring call-level records is risky.

The pattern is simple: each paid call gets its own payment reference and receipt; many receipts can be bundled for settlement. A bundle can include gross USDC amount, receipt IDs, network details, exception status, payout status, and euro-facing reconciliation references where available. Headers do not need to expose the full bundle at call time. They need to create identifiers that make bundling possible later.

Example flow for a paid endpoint

Consider a seller with a paid fraud-screening endpoint. An agent sends a request without payment. The endpoint returns `HTTP 402 Payment Required` with a payment reference, amount, USDC asset, Base network, expiration time, idempotency key, and proof header name.

The agent checks its budget policy, submits payment using the provided terms, and retries the same endpoint with proof attached. The seller verifies the proof, executes the protected work, and returns the result with a receipt ID. Later, the receipt is assigned to a settlement bundle. If the agent reports a duplicate charge, support can inspect one chain of records rather than piecing together disconnected logs.

That is the value of careful header design. It creates a commercial trail without turning every API call into a manual checkout.

How Apiosk fits

Apiosk helps API sellers turn protected endpoints into paid, agent-readable services. The agent-facing side can use x402-style payment requirements and USDC payments on supported rails. The seller-facing side can preserve controls, receipts, settlement batches, exception handling, euro settlement context, and reconciliation exports.

The important point is that x402 headers are not isolated syntax. They are the entry point to a payment operating system for APIs. They shape how agents understand price, how sellers verify proof, how retries are handled, and how revenue later becomes reconcilable business records.

For developers building paid endpoints, the goal should be boringly clear behavior: quote the action, preserve the terms, verify the proof, execute once, return a receipt, and connect the receipt to settlement. That is what makes API monetization usable for AI agents and manageable for the teams that sell to them.