feat(x402): usage-based billing & quota enforcement with metering middleware

[teethaking]

---

Summary

This PR adds metering, quota enforcement, and a usage/billing summary endpoint on top of the existing x402 payment middleware, enabling operators to run x402 as a paid service with per-key rate tiers and configurable over-quota policy. The existing x402 middleware is extended, not replaced.

Closes #82

---

What changed

src/x402/metering.ts (new)

• Meters every paid request against the calling API key's quota
• Tracks usage per key with a Redis-backed counter for accurate metering under concurrent load
• Quota and rate tiers are configurable per key (e.g. requests/day, requests/month)
• Enforces a configurable over-quota policy:
  • block — reject the request outright once quota is exhausted
  • 402 — return HTTP 402 Payment Required, prompting the caller to pay per-call as normal
  • overage — allow the request through and bill the overage at a configured rate
• Hooks into the existing x402 middleware chain so paid-call detection and metering happen in the same request lifecycle, without duplicating payment verification logic

src/api/usage.ts (new)

• New endpoint exposing a usage/billing summary per API key:
  • Total metered calls in the current billing period
  • Remaining quota
  • Overage calls and associated charges (if overage policy is active)
  • Current rate tier
• Summary data is sourced directly from the Redis metering store to stay consistent with enforcement

Tests

• Metering correctly increments per paid call and resets on period rollover
• Over-quota behavior verified for all three policies (block, 402, overage)
• Usage summary endpoint returns accurate counts matching the underlying metering store
• Concurrent request handling does not cause quota miscounting (race condition coverage)

---

How to verify

npm test -- --grep metering
npm test -- --grep usage

• Make paid calls up to a key's quota and assert the count increments correctly
• Exceed the quota under each policy (block, 402, overage) and assert the expected response/behavior
• Call GET /api/usage (or configured route) and assert the summary matches actual metered usage
• Run concurrent requests against the same key and assert no quota overcounting/undercounting occurs

---

Checklist

• Every paid request metered against the key's quota
• Quotas and rate tiers configurable per key
• Over-quota policy supports block, 402, and overage
• Usage/billing summary endpoint implemented and tested
• Built on top of existing x402 middleware — no duplicated payment logic
• Redis-backed metering verified under concurrent load
• Tests cover metering, all three over-quota policies, and the summary endpoint
• Closes Usage-based billing & quota enforcement for x402 #82

[drips-wave]

@teethaking Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits