Pay-Through

An x402 Extension for Rate-Limited APIs

A dual-path 402: wait for free or pay to proceed.

Author: Ian McCutcheon, eSoup Date: February 2026 Status: Living document

Abstract

Pay-Through is a pattern that extends the x402 protocol by adding a free-tier backoff path to the payment negotiation. When a rate-limited API returns HTTP 402, the response carries both rate-limit backoff information (allowing the client to wait and retry for free) and a payment offer (allowing the client to pay for elevated access). The client chooses: time or money. The server handles both paths in a single response.

We believe the specific combination described here — embedding 429-compatible rate limit headers inside a 402 payment response to create a backwards-compatible freemium API — may be novel. This document records that thinking. The individual components (x402, rate limiting, 402) are well-established; the contribution, if any, is in how they're composed.

A reference implementation is running in production on DNSlurp, a DNS lookup API. The companion article covers the motivation and implementation details. You can test the pattern yourself — thirty requests in a minute and you'll see it.

Why This Matters

Pay-Through turns a hard rate-limit wall into a protocol-native negotiation that both humans and agents can act on automatically. Instead of forcing registration, API keys, or opaque "try again later" behavior, the server returns one machine-readable response that preserves a functioning free tier (Retry-After) while offering an immediate paid bypass (x402).

This enables:

• Frictionless freemium APIs — no signup, no API keys for the free tier
• Conversion at the exact moment of demonstrated value
• Self-explanatory throttling that reduces support friction
• A safe, policy-driven way for automated clients and AI agents to trade latency for cost — without scraping workarounds or custom billing integrations

The Pattern

1. Free tier requires no authentication. The API is open. No API keys, no signup, no registration. Users make requests and get responses.

2. Rate limits are enforced using standard HTTP headers. The server communicates quota and reset timing through X-RateLimit-* headers and communicates backoff through Retry-After.

3. When the rate limit is exceeded and payment bypass is available, the server returns 402 — not 429. The 402 status code signals that payment is an option. If payment is not configured or not available, the server falls back to 429. Use 402 only when the server is willing to accept payment as an alternate path for this specific request; otherwise use 429.

4. The 402 response includes both a free path and a paid path. The response body contains a retryAfter interval (wait and retry at no cost) alongside a payment offer (pay to bypass the limit immediately). Both paths are presented in the same response:

HTTP/1.1 402 Payment Required
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 45
Retry-After: 45
Content-Type: application/json

{
  "x402Version": 2,
  "error": "Rate limit exceeded.",
  "retryAfter": 45,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "170000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "description": "3-day elevated rate limits"
  }],
  "message": "Pay $0.17 USDC to get 3 days of unlimited access."
}

The key design point: the rate limit headers (X-RateLimit-*, Retry-After) are identical to what a 429 would carry. A client that does not understand payments treats this response exactly like a 429. Nothing breaks. The accepts array contains payment details per the x402 protocol.

1. On successful payment, the server issues a time-limited bearer token. The token is stateless, self-contained, and cryptographically signed. It carries its own expiry and permissions. No database lookups required.

2. The token bypasses rate limits for its duration. When it expires, the client returns to the free tier. No subscription. No renewal. Pay again if you need more.

Design Principles

Graceful degradation. A client that does not understand x402 can treat 402 like 429: follow Retry-After and retry. The free path works without any payment awareness. This is the central design constraint — the 402 response must be backwards-compatible with existing rate limit handling.

Value before payment. The user's first interaction with the API is a result, not a registration form. Payment is offered only after the user has consumed enough of the API to hit a rate limit — meaning they've already seen the product and decided it's useful.

Protocol-native negotiation. The payment offer lives in the HTTP response, not on a pricing page. The client can act on it programmatically. No browser required. No human in the loop if the client has a payment policy.

Agent-friendly. Automated clients and AI agents can implement policy-driven payment decisions: "pay if the wait exceeds 30 seconds," "never pay more than $0.50 per session," "pay only for interactive requests, not background jobs." The dual-path response gives agents the information they need to decide autonomously.

Client Behavior

Standard HTTP client: Receives 402. Does not understand payment headers. Reads Retry-After. Waits. Retries. Functions correctly without payment support.

x402-aware client: Receives 402. Reads the payment offer. Prompts the user or applies a payment policy. Submits payment via Payment-Signature header. Receives a bearer token. Continues with elevated access.

Agent / automated client: Receives 402. Evaluates the payment offer against a configured budget and latency policy. Decides whether to wait (free) or pay (immediate). Operates autonomously within its policy constraints.

Acknowledgments

Pay-Through builds entirely on the x402 protocol and Coinbase's CDP facilitator for payment verification and settlement. The rate limit header conventions follow established industry practice. HTTP 402 has been part of the HTTP specification since RFC 2616 (1997) — we're just finally using it.

The @x402/fetch client library handles the payment flow transparently, and the @coinbase/x402 server library provides facilitator integration. This pattern would not be practical without these tools and the stablecoin infrastructure that makes micropayments economically viable.

Questions, ideas, or feedback on the Pay-Through pattern? All eSoup projects are discussed through the GitHub link at the bottom of this page.