# x429

x429 is an open HTTP extension that turns `429 Too Many Requests` into a
machine-readable offer. A saturated server returns a normal 429 plus a signed
ticket for a future slot and optional paid priority.

Agent instructions:

1. If a 429 response does not include `X429-Version: 1`, use legacy backoff.
2. If it includes `X429-Version: 1`, parse the JSON body.
3. Resolve the issuer key from `/.well-known/x429.json` or the response body.
4. Verify the ticket signature, resource scope, client binding, and expiry.
5. If the free slot fits your deadline, sleep until `ticket.notBefore`.
6. Retry with `X429-Client-Key` and `X429-Ticket`.
7. If the free slot misses your deadline and an upgrade fits your budget, pay
   through the configured payment adapter and retry with the ticket plus proof.
8. If neither path fits, abort with a deadline/budget error.

Important headers:

- `X429-Version: 1`
- `Retry-After`
- `X429-Ticket`
- `X429-Client-Key`
- `Link: </.well-known/x429.json>; rel="service-desc"`

Reference implementation:

- `packages/core`: ticket signing, encoding, verification
- `packages/hono`: Workers/Hono middleware
- `packages/client`: x429-aware fetch wrapper
- `packages/payment-mock`: mock priority payment
- `examples/agent-sim`: 100-agent validation simulator

Documentation map:

- `/docs/`: overview, maturity, system map, ecosystem fit
- `/docs/quickstart/`: local proof, simulator, live endpoint checks
- `/docs/concepts/`: ticket, slot, binding, nonce, upgrade model
- `/docs/protocol/`: headers, response body, discovery, redemption, errors
- `/docs/server/`: middleware install, capacity, nonce storage, metrics
- `/docs/client/`: agent state machine, policy inputs, errors
- `/docs/payments/`: mock priority now, x402 adapter requirements later
- `/docs/security/`: verification rules, threat model, operational security
- `/docs/testing/`: unit tests, simulator, acceptance targets
- `/docs/deployment/`: Cloudflare Pages deployment and custom domain checks
- `/docs/pilot/`: design-partner validation plan
- `/docs/reference/`: package and field reference
- `/docs/glossary/`: shared terms, maturity labels, pilot SLOs

Status: draft v0.1. Payments are mocked first; real x402 is a planned adapter.