@paysentry/x402

x402 protocol adapter for PaySentry. Adds spending limits, circuit breakers, and full observability to HTTP 402 payments made by AI agents.

Quick Start

import { PaySentryX402Adapter } from '@paysentry/x402';
import { PolicyEngine } from '@paysentry/control';
import { SpendTracker } from '@paysentry/observe';

const adapter = new PaySentryX402Adapter(
  { policyEngine: new PolicyEngine(), spendTracker: new SpendTracker() },
  { logger: console },
);

// Register hooks on your x402 server
adapter.withLifecycleHooks(x402Server);

Features

• Policy enforcement — Evaluate every x402 payment against declarative spend policies before verify and settle
• Circuit breaker — Per-facilitator circuit breakers protect against cascading failures (closed/open/half-open)
• Full audit trail — Every lifecycle stage (intent, policy check, verify, settle) recorded in TransactionProvenance
• Alert integration — Completed transactions trigger SpendAlerts evaluation (budget thresholds, anomalies, rate spikes)
• Transaction mapping — Automatic conversion from x402 PaymentPayload/Requirements to PaySentry AgentTransaction
• Response enrichment — ResourceServerExtension injects PaySentry session ID and audit metadata into 402/200 responses
• Zero side effects — Pure classes and functions; nothing runs until you call it

Integration Surfaces

1. Lifecycle Hooks (x402 server)

adapter.withLifecycleHooks(server);

Registers all 6 x402 lifecycle hooks: onBeforeVerify, onAfterVerify, onVerifyFailure, onBeforeSettle, onAfterSettle, onSettleFailure.

2. FacilitatorClient Wrapper

const wrappedClient = adapter.wrapFacilitatorClient(facilitatorClient, 'https://facilitator.example.com');

Wraps verify() and settle() with policy checks, circuit breaker, and provenance recording. Drop-in replacement.

3. ResourceServerExtension

const extension = adapter.createExtension();
// Register with your x402 server as an extension

Enriches 402 responses with PaySentry session metadata and settlement responses with audit data.

Configuration

const adapter = new PaySentryX402Adapter(engines, {
  logger: console,                    // Structured logger
  defaultAgentId: 'my-agent' as AgentId, // Fallback agent ID
  defaultCurrency: 'USDC',           // Default currency (default: 'USDC')
  abortOnPolicyDeny: true,           // Abort x402 flow on policy deny (default: true)
  sessionId: 'ps_custom_session',    // Custom session ID
  resolveAgentId: async (addr) => {  // Custom agent ID resolver
    return lookupAgent(addr);
  },
  circuitBreaker: {
    failureThreshold: 5,             // Failures before opening (default: 5)
    recoveryTimeoutMs: 30000,        // ms before half-open (default: 30000)
    halfOpenMaxRequests: 1,          // Probe requests in half-open (default: 1)
  },
});

Links

• x402 Protocol
• PaySentry