# x402 Protocol

The x402 Protocol is the operational heart of the OpenSeed network. It is the mechanism by which AI inference gets paid for — the precise sequence of messages and cryptographic operations that occur between a Buyer and a Seller to authorize, verify, and record payment for each inference request. Understanding x402 in detail is essential to understanding both how OpenSeed works and why it is secure.

### The History of HTTP 402: A Standard Ahead of Its Time

The HTTP 402 status code has one of the most unusual histories in the annals of internet standardization. It was defined in RFC 1945, the original HTTP/1.0 specification published in 1996, with the description "Payment Required." The RFC text explicitly noted that the status code was "reserved for future use" and anticipated that it would be used for digital payment systems that did not yet exist at the time.

The authors of the HTTP specification understood, even in 1996, that the web would eventually need a native mechanism for per-resource micro-payments. The vision was a web where content and services could be priced and paid for at a granular level — where reading a specific article, accessing a specific API endpoint, or downloading a specific file could trigger an automated payment without requiring a subscription or a billing relationship established in advance.

For nearly three decades, HTTP 402 sat unused in the specification. The payment infrastructure of the 1990s and 2000s was simply not capable of making the vision real. Credit cards were too slow, too expensive for small amounts, and required human interaction. Early digital payment systems like DigiCash and e-gold failed to achieve sufficient adoption. The web evolved instead around advertising and subscription models — payment structures compatible with human billing cycles and credit card minimums.

The emergence of programmable blockchain infrastructure — specifically, smart contracts on Ethereum and its Layer 2 networks — finally provides the payment primitives that make HTTP 402 practical. Smart contracts can enforce payment channel logic automatically, without trust in any counterparty. Cryptographic signatures can authorize payments instantly and at zero cost. And Layer 2 settlement can batch-confirm those authorizations on-chain at costs measured in fractions of a cent.

OpenSeed's x402 implementation is the practical realization of the HTTP 402 vision. For the first time, it is possible to build services where every HTTP request can carry a valid, irrevocable payment authorization — where the "Payment Required" response is not an error message but an invoice, and where the payment is not a credit card transaction initiated by a human but a cryptographic signature generated autonomously by a machine.

### The Invoice Format

When a Seller node receives an inference request without a valid payment authorization, it responds with HTTP 402 Payment Required. The response body is a structured JSON object — the invoice — that contains everything the Buyer needs to generate a valid payment authorization.

The invoice contains several key fields. The channelId is the unique identifier for the payment channel between this specific Buyer-Seller pair. It is derived from both parties' wallet addresses and a session identifier, ensuring that payment authorizations are specific to this relationship and cannot be used against other channels.

The amount field specifies the required payment in USDC, expressed as an integer in the smallest denomination (micro-USDC). For a typical inference request, this amount is calculated based on the Seller's per-token pricing multiplied by an estimate of the input and output token counts for this specific request. Because output token counts cannot be known with certainty before inference runs, the Seller may estimate based on the requested max\_tokens parameter or historical averages.

The metadataHash is a cryptographic hash of the request parameters — the prompt, the model specification, the inference parameters, and the estimated token counts. This hash serves as a binding commitment: the SpendingAuth the Buyer generates in response to this invoice authorizes payment specifically for the computation described by this metadataHash. The Seller cannot use this authorization to claim payment for a different, more expensive request.

The nonce is a unique, monotonically incrementing identifier for this invoice. The Buyer's SpendingAuth must reference the correct nonce, and each nonce can only be used once in the settlement process. This prevents replay attacks in which a Seller attempts to re-use a valid SpendingAuth to claim double payment.

The deadline is a Unix timestamp specifying when the invoice expires. SpendingAuths generated after the deadline are invalid. This prevents the accumulation of stale authorizations and ensures that the Buyer's budget cannot be claimed long after the inference session has ended.

### EIP-712: The Signature Standard

The SpendingAuth generated by the Buyer in response to an x402 invoice uses EIP-712 — the Ethereum standard for typed, structured data signatures. Understanding EIP-712 and why it was chosen over simpler alternatives is important for appreciating the security properties of the x402 protocol.

EIP-712 was designed to solve a specific problem with raw Ethereum message signatures: they are opaque blobs of bytes that a signer cannot meaningfully inspect before signing. When a user is asked to sign a raw byte string, they have no way to know what they are authorizing — it could be a payment, a token approval, a governance vote, or anything else. This opacity is a significant security risk, particularly for automated signers that must sign messages without human review.

EIP-712 defines a standard for expressing the structure and content of messages to be signed in a human-readable and machine-verifiable way. A message signed under EIP-712 has a defined type schema — like a strongly-typed data structure — that specifies exactly what each field in the message means. The signer signs not just the raw data but the typed, structured representation of it. Any software that verifies the signature can also verify that the data it represents is exactly what the signer agreed to.

For OpenSeed's SpendingAuth, the EIP-712 typed structure includes all the fields necessary to unambiguously define the payment being authorized: the channelId, the authorized amount, the nonce, the deadline, and the metadataHash from the invoice. When the Buyer's signer signs this structure, it is providing a mathematically provable attestation that it authorizes this specific payment amount, for this specific channel, for this specific request, with this specific expiration — and nothing else.

The Seller's verification logic checks the signature against this typed structure. If any field has been tampered with — if the amount has been inflated, if the nonce has been changed, if the metadataHash no longer matches the actual request — the signature verification fails and the request is rejected. The cryptographic binding is exact and complete.

### Security Analysis: What x402 Protects Against

The x402 protocol is designed to provide strong security guarantees for both Buyers and Sellers simultaneously — a non-trivial requirement given that the two parties are mutually distrusting participants in an adversarial market.

From the Seller's perspective, the primary threat is receiving and serving inference requests without receiving valid payment. x402 protects against this by requiring a valid, verifiable SpendingAuth before serving any response. The Seller does not trust the Buyer — it trusts the cryptographic signature. If the signature is valid, the payment is guaranteed. The Buyer's locked USDC deposit in the ReserveAuth ensures that the funds actually exist to be claimed. A Seller that follows the protocol cannot be defrauded of payment.

From the Buyer's perspective, the primary threats are double-billing (paying twice for one request), over-billing (paying more than the agreed amount), and replay attacks (having a previously-used authorization re-submitted to claim duplicate payment). The metadataHash binding addresses over-billing — the authorization is tied to a specific request with specific parameters and cannot be reused for a more expensive request. The nonce mechanism addresses double-billing and replay attacks — each nonce is unique and can only be used in settlement once. The Buyer's local nonce ledger tracks all issued nonces, and the smart contract enforces nonce uniqueness at settlement time.

The deadline mechanism protects against the accumulation of stale, never-settled authorizations. Without deadlines, a Seller could theoretically hold a large portfolio of old SpendingAuths and submit them for settlement years later, creating unexpected claims on a Buyer's deposit. The deadline ensures that authorizations expire if not used within a reasonable window.

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.openseed.gg/core-concepts/x402-protocol.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.