draft v0.1 ยท reference implementation
x429 docs
x429 is an HTTP-native coordination layer for overloaded resources. It turns 429 Too Many Requests into a signed reservation, and gives agents a deterministic way to wait, redeem, or pay for priority.
Where to begin
Choose your path
Run the proof
Clone the repo, run tests and the 100-agent simulator, inspect the live /429 response.
Install on an API
Wrap a scarce endpoint, issue tickets when saturated, and publish discovery metadata.
03Teach agents to react
Use the client state machine: verify, wait, pay if budget allows, redeem once.
04Validate with a partner
Measure retry reduction, completion rate, paid priority behavior, and operational risk.
What is implemented today
Signed tickets
Ed25519 ticket creation, encoding, verification, resource scope checks, client-key binding, and nonce replay protection live in packages/core.
Middleware and client
Workers/Hono-style middleware issues tickets. The fetch wrapper handles x429 responses using deadline and budget policy.
Simulator
The 100-agent simulator compares naive retry against x429-aware admission and mock paid priority.
Real x402 settlement
The payment adapter exists as a placeholder. V1 proves scheduling first, then swaps mock receipts for real x402 verification.
System map
X429-Version: 1, verifies the offer, then waits or pays./.well-known/x429.json publishes keys, docs URL, version, and supported payment modes.Ecosystem fit
x429 should feel narrow, not vague. It is the admission primitive for overloaded resources. Other systems can plug into it without becoming part of the core protocol.
| Layer | Role | x429 stance |
|---|---|---|
HTTP 429 | Existing overload signal. | x429 stays compatible: legacy clients still see Retry-After. |
x402 | Payment rail for machine-native payments. | x429 can use x402 to settle paid priority, but scheduling and tickets remain separate. |
MCP | Tool and context servers for agents. | MCP endpoints are strong pilot candidates because agent retry behavior is visible. |
llms.txt | Machine-readable site instructions. | The site publishes concise agent instructions at /llms.txt. |
GSLP / policy layers | Higher-level service promises, routing, or guarantees. | Can reference x429 as the concrete wait/redeem/pay mechanism underneath. |
Trust checklist
- Developers can run the simulator and reproduce the retry-reduction claim.
- Agents can discover the protocol through headers, JSON, well-known metadata, and
llms.txt. - Tickets are signed, scoped, time-bound, bound to a client key, and single-use.
- Payments are explicitly marked mock until a real x402 adapter verifies settlement.
- The docs separate implemented behavior from planned behavior so readers do not have to guess.