Build with x429

Put one durable admission boundary in front of a scarce GET or HEAD endpoint. Every free ticket and paid permit occupies a real slot and redeems once.

Quickstart Wire protocol API reference

Choose your path

Quickstart

Run the full verification suite, generate separate protocol and origin-assertion keys, and start the v2 Worker locally.

Wire protocol

Read the proof, signed-envelope, ticket, sealed-bid, award, and redemption rules.

API reference

Separate the deployable v2 Worker from the legacy v1 workspace packages.

What is implemented today

Durable admission

Implemented in v2. packages/admission-worker uses a SQLite Durable Object for capacity, reservations, proof nonces, bids, awards, and single-use redemption.

Proof of possession

Implemented in v2. Every protected request signs its method, authority, target, body digest, credential digest, time, and nonce with Ed25519.

Sealed micro-auction

Implemented for research and mock testing. The engine supports sealed maxima and uniform K+1 clearing, but bids are not funded when submitted. Real-value launch profiles disable competition and expose one fixed-price paid slot to one vetted client.

Exact settlement path

Implemented, not yet launch-proven. Exact x402 v2 EIP-3009 settlement, standard payment headers, durable intents, and dual-RPC reconciliation are in source. There is no funded public-chain proof, retained live-provider reconciliation exercise, or independent audit yet.

System map

Admission WorkerTerminates client proofs, verifies exact issuer context, and proxies admitted GET or HEAD requests to a fixed upstream under an execution lease.

Resource coordinatorOne deterministic SQLite Durable Object serializes admission for each canonical resource and HTTP method.

Free laneFinite instant capacity and future reservations share the configured free quota.

Paid laneA sealed epoch allocates finite paid capacity. Research/mock mode can clear K+1; deployed exact mode carries one fixed-price offer and settles it through x402 before issuing a permit.

Client policyVerify first; wait for the free window, bid once within budget, or exit without retry amplification.

Origin assertionThe Worker signs the exact target, lane, request id, receipt digest, short expiry, and one-time nonce for the fixed upstream.

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`	Exact USDC authorization and settlement rail.	The private source tree implements x402 v2 exact on Base profiles, including indeterminate-state reconciliation. Operators still need funded staging evidence, audit, monitoring, and legal review.
`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`.
Authentication	Identity, authorization, and abuse controls.	Remains the origin's responsibility. x429 only controls admission.

Trust checklist

Developers with repository access can run Node tests, workerd tests, type checks, package smoke tests, and the simulator.
Agents can discover the protocol through headers, JSON, well-known metadata, and llms.txt, but generic x402 clients still need an x429-aware SDK or compatible ticket/auction state machine to execute it.
V2 tickets are signed, scoped, time-bound, bound to proof of possession, durably reserved, and single-use.
Free and paid allocations are finite and accounted by an explicit operator-named capacity pool; URL variation cannot mint another queue.
Exact settlement uses PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE; an unknown facilitator outcome never issues a permit.
Exact admission in the synchronous deployed profile waits for two operator-selected, independently administered RPC providers to agree on the Base safe boundary number and hash, then measures configured depth inside that boundary. The runtime rejects identical hostnames but cannot prove provider independence; safe is not irreversible.
Deployed exact mode is hard-locked to exactly one vetted X429_ALLOWED_CLIENTS thumbprint, one paid slot, reserve equal to maximum, and one outstanding paid obligation while bids remain uncollateralized.
A ticket or permit buys admission, not guaranteed response delivery; protected-origin dispatch irrevocably consumes it, and the signed receipt may accompany an unknown application result.
The source and tests are available in this private repository, but the packages are not published and there is no funded public-chain or independent-audit claim.