Epic] x402 payment rails — production

[clintjeff2]

Motivation

• Ensure x402 subscription state (plans, renewals, calls-used, grace/paused status) survives process restarts by replacing the in-memory-only registry with a durable store.
• Provide a tiny, developer-friendly SDK helper so operators can add an x402 paywall to Next.js/API routes in a few lines.

Description

• Persist subscriptions under a JSON-backed store (.data/x402-subscriptions.json) with helpers ensureSubscriptionStore, readSubscriptionStore, writeSubscriptionStore, hydrateSubscriptionRegistry, and persistSubscriptionRegistry in lib/protocols/x402.ts and wired into all subscription lifecycle paths (createX402Subscription, renewX402Subscriptions, checkX402Subscription, listX402Subscriptions, getX402SubscriptionById).
• Atomically write subscription updates and expose test helpers setX402SubscriptionStorePathForTests, resetX402SubscriptionStorePathForTests, and ensure test reset behavior via resetX402SubscriptionsForTests.
• Add a new package scaffold packages/x402 with a small TypeScript SDK and an x402Gate helper that verifies receipt headers and returns a 402 quote response when payment is required (packages/x402/src/index.ts and package.json/tsconfig.json).
• Add a persistence-focused test to lib/protocols/x402.test.ts that asserts subscriptions are written and reloaded and that consumeCall is persisted (calls used increments are durable).

Testing

• Ran npx tsc -p packages/x402/tsconfig.json which succeeded for the new SDK package.
• Ran npx vitest run lib/protocols/x402.test.ts __tests__/api/explorer/receipts.test.ts and all tests passed (Test Files 2 passed, Tests 5 passed).
• Attempted repository-level typecheck via npm run typecheck || npx tsc --noEmit but it surfaced unrelated, pre-existing repository type issues (no typecheck script and TS errors in app/api/agents/[id]/tasks/drain/route.ts, lib/wallet-config.ts, and tests/lib/agents/task-drain.test.ts), so a full repo typecheck was not completed as part of this change.

---

Closes #18

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud