x402 Payment Protocol

PEAC integrates with HTTP 402-based payment protocols through two packages: @peac/rails-x402 for payment evidence extraction and @peac/adapter-x402 for evidence carrier transport. Together they enable payment receipts that are verifiable, portable, and transport-neutral.

---

Install

Terminal

# Payment evidence extraction
pnpm add @peac/rails-x402

# Evidence carrier for x402 responses
pnpm add @peac/adapter-x402

---

How it works

The x402 payment flow uses HTTP 402 (Payment Required) responses to negotiate payment before granting access. PEAC attaches evidence of the completed payment to a receipt.

x402 Payment Flow

Client -> Server: GET /api/data
Server -> Client: 402 Payment Required (payment details)
Client -> Payment: Complete payment
Client -> Server: GET /api/data + X-PAYMENT header
Server -> Client: 200 OK + PEAC-Receipt header

The receipt captures the settlement reference, amount, currency, and payment rail without storing sensitive payment details.

---

Payment evidence

Extract payment evidence from x402 payment headers:

x402-evidence.ts

import { fromX402Payment } from '@peac/rails-x402';

const evidence = fromX402Payment({
  paymentHeader: req.headers['x-402-payment'],
  amount: '0.001',
  currency: 'USDC',
  network: 'base',
});

The fromX402Payment function produces a standardized PaymentEvidence object:

PaymentEvidence

{
  rail: 'x402',
  amount: '0.001',
  currency: 'USDC',
  settlement_ref: 'tx_abc123...',
  evidence: {
    network: 'base',
    payment_header: '<hash-of-payment-header>',
  },
}

---

Evidence carrier

The @peac/adapter-x402 package implements the Evidence Carrier Contract for x402 responses, placing receipt evidence in HTTP response headers.

x402-carrier.ts

import { attachX402Carrier, extractX402Carrier } from '@peac/adapter-x402';

// Attach evidence to an x402 response
const response = attachX402Carrier(originalResponse, carrier);

// Extract evidence from an x402 response
const carrier = extractX402Carrier(incomingResponse);

Transport limits

Constraint	Value
Header size limit	8 KB
Header name	PEAC-Receipt
Format	Compact JWS

---

Issuing a payment receipt

issue-payment-receipt.ts

import { issueReceipt } from '@peac/protocol';
import { fromX402Payment } from '@peac/rails-x402';

const paymentEvidence = fromX402Payment({
  paymentHeader: req.headers['x-402-payment'],
  amount: '0.001',
  currency: 'USDC',
  network: 'base',
});

const receipt = await issueReceipt({
  privateKey: process.env.PEAC_PRIVATE_KEY,
  kid: 'peac-2026-02',
  claims: {
    iss: 'https://api.example.com',
    sub: 'agent:payer-001',
    peac: {
      type: 'payment',
      attestation_type: 'payment',
      status: 'executed',
      payment: paymentEvidence,
    },
  },
});

---

Supported payment methods

The x402 adapter works with any payment method supported by the x402 ecosystem:

Category	Examples
Stablecoins	USDC, USDT, DAI
Cryptocurrencies	ETH, BTC (via bridge)
Fiat wrappers	Stripe-backed x402

Category-first

PEAC extracts settlement evidence from the payment header regardless of the underlying payment method. The same fromX402Payment function handles all x402-compatible payment flows.

---

Implementation examples

Express middleware with x402

express-x402.ts

import express from 'express';
import { peacMiddleware } from '@peac/middleware-express';
import { fromX402Payment } from '@peac/rails-x402';

const app = express();

app.use(peacMiddleware({
  privateKey: process.env.PEAC_PRIVATE_KEY,
  kid: 'peac-2026-02',
  issuer: 'https://api.example.com',
}));

app.get('/api/data', (req, res) => {
  // x402 payment already completed at this point
  // PEAC middleware auto-attaches receipt to response
  res.json({ data: 'protected content' });
});

---

Next steps

Payment Rails

All supported payment rails: x402, Stripe, Razorpay, card networks.

Evidence Carrier

How payment evidence travels across HTTP, MCP, and A2A transports.

Express Middleware

Auto-attach receipts to Express.js responses.