Per-Request API Payments Over HTTP 402 With On-Chain Settlement
A payment-gated API relay implementing the x402 protocol, where each request carries a signed USDC transfer in an HTTP header, verified on-chain before the call is routed onward.
X402 Relay is a payment-gated API relay backend that implements the x402 protocol for per-request blockchain payments. The core idea is old HTTP status code, new trick. X402 uses the 402 Payment Required response to demand a payment for each request, and the client answers by including a signed USDC transaction in an X-PAYMENT header. It is deployed at relay402.io.
No smart contract required
The design decision I like most here is that the base flow needs no smart contract. Payment settles as a standard SPL token transfer on Solana, not through a bespoke on-chain program. That removes an entire class of deployment risk and audit surface. There is an optional prepaid smart contract for high-frequency users who want to avoid a transfer per call, but it is an enhancement, not a dependency. The default path is deliberately boring, which is exactly what you want in a payments primitive.
Facilitator integration is what makes this usable rather than theoretical. The relay works with facilitators like PayAI or Coinbase, or a self-hosted one, and the facilitator can cover the Solana gas fees so the user's transactions are effectively gasless. Pushing gas onto the facilitator is the difference between a protocol a developer will try and one they will bounce off.
Verification is the hot path
Per-request payment means per-request verification, and that is where the engineering pressure sits. Every incoming call has to have its payment checked before the request is relayed onward, and it has to be fast enough not to dominate the latency of the underlying API. The build targets sub-200ms payment verification, which it reaches with caching, and it guards the obvious attack with replay prevention so a signed payment cannot be reused across requests. Rate limiting sits alongside it.
Once a request is paid for, the smart relay routes it to OpenRouter or a partner API. Because it fronts OpenRouter, it also syncs model pricing hourly so charges track current rates rather than a stale table.
The stack
It is built on Bun and Hono with PostgreSQL, deployed on Ubuntu 24.04, and it ships with a frontend. The observability side is deliberately complete: logging, health checks, and analytics, because a payment relay that you cannot see into is a liability.
The lesson I take from building this is that for a payment gate, the trust boundary is the verification step and nothing else. Everything upstream can be conventional. What has to be bulletproof is confirming the payment actually happened, exactly once, before you do any work, and doing it fast enough that the gate does not become the bottleneck.
Have something that needs building, or stabilizing?
These notes are the work log. The paid work runs through Moonshine Labs, my product and engineering studio. Tell us what you're building, or grab a call.
Work with us →