# x402 Micropayment

#### Protocol Role

The x402 protocol is the HTTP-layer payment negotiation mechanism that OpenShard uses to authorize per-inference payments on Base without requiring an on-chain transaction per request. It operates as a header-based flow layered on top of standard HTTP semantics, which means it requires no changes to the transport layer and is compatible with any HTTP client that can attach custom headers. From the perspective of the downstream application sending requests through the buyer, payment negotiation is entirely invisible — the buyer handles all 402 interactions internally and retries transparently.

#### Payment Negotiation Flow

When a buyer sends a request to a paid seller endpoint without valid payment authorization attached, the seller responds with HTTP 402 Payment Required. It includes a payment-required header that describes the channel requirements, accepted token type, spending limit constraints, and the metadata hash for the expected request.

The buyer's payment retry loop intercepts this 402 response before it reaches the calling application. The buyer creates or updates a local payment channel state for the buyer-seller pair. It then signs a SpendingAuth payload using EIP-712 typed-data signing and retries the original request — including the full privacy payload — with the x-402-payment-auth and x-402-channel-id headers attached. The seller validates the signed authorization and only then forwards the decrypted request to the upstream inference provider.

The full 402 negotiation loop — initial rejection, channel state creation, SpendingAuth signing, and retry — is designed to complete fast enough that calling applications experience it as normal request latency rather than a visible protocol handshake.

#### EIP-712 Signature Types

The shared package defines two primary EIP-712 typed-data structures that govern payment authorization in OpenShard.

ReserveAuth establishes a payment channel between a buyer and seller with a declared capacity reserve on Base. This is the channel-opening action, and it commits a specific amount of value to be available for spending within the channel. Buyers create ReserveAuth signatures when opening a new channel or topping up an existing one that is approaching its capacity limit.

SpendingAuth authorizes a specific cumulative spending amount against an existing channel. Rather than authorizing individual per-request amounts, the protocol tracks cumulative totals. Each SpendingAuth signature must reflect a cumulative amount that is strictly greater than the previously accepted cumulative total for that channel. The seller validates that the new authorization is monotonically increasing and does not exceed the channel's reserve capacity. This design prevents both double-spend attempts (replaying an older lower-value SpendingAuth) and overspend attempts (signing for more than the reserve allows).

#### Channel Identity and Determinism

Channel IDs are deterministic hashes derived from the buyer commitment, the seller's Ethereum address, and a nonce. This determinism means that the same buyer-seller pair with the same nonce always produces the same channel ID, making channel state reconcilable without requiring a separate registration step. It also means that channels cannot be reassigned across different seller endpoints — a SpendingAuth signed for one seller cannot be replayed against a different seller, because the channel ID would not match.

#### Metadata Hash and Request Fingerprinting

The SpendingAuth payload includes a metadata hash that encodes input token count, output token count, and request fingerprinting fields. This binding ties the payment authorization to a specific inference request's size and content fingerprint. A seller cannot accept a SpendingAuth originally signed for a small request and apply it against a large inference response — the metadata hash would not match and validation would fail. This prevents scenarios where a buyer signs payment authorization for a short query and an attacker or a misbehaving seller attempts to apply that authorization to a significantly more expensive request.

#### USDC Accounting and Chain Support

Payment amounts are denominated in USDC with strict 6-decimal precision on Base. The shared package provides parse and format helpers that enforce this semantics consistently across all payment arithmetic, preventing unit confusion between raw on-chain token amounts and human-readable USD values. A mistake in decimal handling at any point in the payment pipeline would result in either overcharging or undercharging by a factor of one million, making this a critical correctness invariant. Chain support includes Base mainnet, Base Sepolia testnet, and localhost/Hardhat for local development and integration test environments.

#### Contract Settlement Layer

The contracts package provides a Solidity contract deployed on Base implementing the lock, queueWithdrawal, and withdraw lifecycle with cooldown semantics and a reentrancy guard. This contract handles cases where channel balances need to be settled on-chain — for example, at the end of a long-running inference session or when a buyer needs to recover unused locked funds. The cooldown period between queueWithdrawal and withdraw prevents rapid lock-unlock cycles that could be exploited to manipulate payment accounting. The reentrancy guard prevents re-entrant calls to the withdrawal path during settlement execution.

<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.openshard.ai/core-concepts/x402-micropayment.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.