x402 Integration
Verifiable payment evidence for HTTP 402 flows. When a server returns 402 Payment Required, the client pays, and PEAC records verifiable evidence of what happened. The receipt travels back to the server via the PEAC-Receipt header.
Built on the Evidence Carrier Contract.
How It Works
1. Server returns 402
The server responds with HTTP 402 Payment Required and an x402 offer describing the payment terms (amount, currency, accepted methods).
2. Client pays
The client (or agent) completes the payment via the specified payment rail. The x402 facilitator returns a settlement response.
3. PEAC records evidence
The settlement response is normalized into a PEAC receipt using @peac/rails-x402. The receipt is signed and attached to the retry request.
4. Receipt travels via header
The compact JWS is carried in the PEAC-Receipt HTTP header (8 KB limit). The server can verify the receipt before serving the resource.
Packages
The x402 integration is split into two packages with distinct responsibilities:
@peac/rails-x402
Layer 4: Payment Rail
Normalizes x402 offers and settlement responses into PEAC payment records. Maps payment fields (amount, currency, tx_hash) into the receipt payment claim.
Since v0.10.11
@peac/adapter-x402
Layer 4: Evidence Carrier
Attaches and extracts receipts from x402 HTTP responses. Implements the CarrierAdapter interface for the PEAC-Receipt header.
Since v0.11.1
Install
pnpm add @peac/rails-x402 @peac/adapter-x402
Receipt Issuance from Settlement
import { normalizeSettlement } from '@peac/rails-x402';
import { issue } from '@peac/protocol';
// Settlement response from the x402 facilitator
const settlement = {
amount: '0.05',
currency: 'USD',
rail: 'x402',
tx_hash: '0x1234...abcd',
settled_at: '2026-02-25T12:00:00Z',
};
// Normalize into PEAC payment record
const payment = normalizeSettlement(settlement);
// { rail: 'x402', amount: '0.05', currency: 'USD', tx_hash: '0x1234...abcd' }
// Issue a signed receipt
const receipt = await issue({
iss: 'https://publisher.example.com',
aud: 'agent.consumer.com',
payment,
control: {
decision: 'allow',
purposes: ['inference'],
},
});
// Attach to retry request via PEAC-Receipt header
const response = await fetch('https://api.example.com/resource', {
headers: {
'PEAC-Receipt': receipt.jws,
},
});HTTP Transport
The PEAC-Receipt header carries the compact JWS. The 8 KB header size limit applies.
GET /api/resource HTTP/1.1 Host: api.example.com PEAC-Receipt: eyJhbGciOiJFZERTQSIsInR5cCI6InBlYWMtcmVjZWlwdC8wLjEifQ...
Supported Payment Methods
The x402 rail supports crypto rails and fiat facilitators. PEAC records evidence of the settlement regardless of the underlying payment mechanism.
| Category | Description |
|---|---|
| Crypto rails | On-chain settlement with transaction hash evidence |
| Fiat facilitators | Card and account-based payments via payment processor APIs |
Implementation examples
| Provider | Type | Evidence Field |
|---|---|---|
| Base network (USDC) | Crypto rail | tx_hash |
| Stripe x402 profile | Fiat facilitator | payment_intent_id |
Payment Claim Structure
The payment claim in the receipt payload contains normalized settlement data:
| Field | Type | Description |
|---|---|---|
rail | string | Payment rail identifier ("x402") |
amount | string | Settlement amount as a decimal string |
currency | string | ISO 4217 currency code or token symbol |
tx_hash | string | Transaction hash or payment reference (optional) |
Links
Evidence Carrier Contract
The x402 adapter implements the CarrierAdapter interface shared across all PEAC integrations. Receipts issued from x402 settlements are portable: the same receipt can be carried through MCP, A2A, ACP, UCP, and HTTP transports.