@peac/adapter-x402

x402 offer verification, receipt extraction, and PEAC interaction record mapping for the x402 Offer/Receipt extension.

Installation

pnpm add @peac/adapter-x402

What It Does

@peac/adapter-x402 is a Layer 4 adapter that verifies x402 offer and receipt artifacts, extracts receipt data from HTTP response headers, and maps the results into canonical PEAC interaction records. It implements a verification-first architecture with layered checks: wire validation, term-matching, offer-receipt consistency, and opt-in cryptographic verification. The adapter reads both PEAC-Receipt and upstream x402 response headers (v1 and v2) with priority-based fallback.

How Do I Use It?

Verify an offer against accept terms

import { verifyOffer } from '@peac/adapter-x402';

const result = verifyOffer(signedOffer, acceptEntries);

if (result.valid) {
  console.log('Matched accept entry:', result.matchedAccept);
  console.log('Used hint:', result.usedHint);
} else {
  console.log('Verification failed:', result.errors);
}

Extract receipt artifacts from HTTP response headers

import { extractReceiptArtifactFromHeaders } from '@peac/adapter-x402';

// Dual-header read: checks PEAC-Receipt, then PAYMENT-RESPONSE (v2),
// then X-PAYMENT-RESPONSE (v1)
const artifact = extractReceiptArtifactFromHeaders(responseHeaders);

if (artifact) {
  console.log('Source:', artifact.source); // 'peac' | 'x402_v2' | 'x402_v1'
  console.log('Is PEAC receipt:', artifact.isPeacReceipt);
  console.log('Raw artifact:', artifact.rawArtifact);
}

Build evidence carriers from x402 responses

import { fromOfferResponse, X402CarrierAdapter } from '@peac/adapter-x402';

// Extract from an x402 402 response (offer)
const extraction = fromOfferResponse(response);
console.log('Carriers:', extraction.receipts);
console.log('Transport:', extraction.meta.transport);

// Or use the CarrierAdapter interface
const adapter = new X402CarrierAdapter();

Map an x402 payment flow to a PEAC record

import { toPeacRecord } from '@peac/adapter-x402';

const record = toPeacRecord(challenge, settlementResponse);
// record.proofs.x402.offer   -- raw offer preserved for audit
// record.proofs.x402.receipt  -- raw receipt preserved for audit
// record.evidence.resourceUrl -- from signed offer payload
// record.evidence.payer       -- from signed receipt payload

Integrates With

• @peac/adapter-core (Layer 4): Shared Result types and validators
• @peac/kernel (Layer 0): Wire constants and evidence carrier types
• @peac/schema (Layer 1): Receipt ref computation and carrier validation
• @peac/crypto (Layer 2): JWS parsing utilities

For Agent Developers

If you are building an AI agent that makes paid API calls via x402:

• Use extractReceiptArtifactFromHeaders() to capture receipt evidence from HTTP responses
• Use verifyOffer() and verifyReceipt() to validate x402 artifacts before accepting them
• Use toPeacRecord() to map verified x402 flows into signed PEAC interaction records
• See the llms.txt for a concise protocol overview

License

Apache-2.0

PEAC Protocol is an open source project stewarded by Originary and community contributors.

Docs | GitHub | Originary