Get started
Quickstart
Run the reference implementation locally, inspect the protocol response, and verify that x429 reduces retry storm traffic.
Prerequisites
- Node.js 24 or newer. The reference uses Web Crypto Ed25519 support.
- GitHub access to
x429-protocol/x429. - No package install is required for the current local proof.
Status: package names such as
@x429/core are the intended package API. They are local workspace packages today, not public npm packages yet.1. Clone and run checks
git clone https://github.com/x429-protocol/x429.git
cd x429
npm run checkThis command runs the unit tests and the 100-agent simulator.
> npm run test
✔ signed tickets verify and redeem once
✔ tampered tickets fail signature verification
> npm run simulate
{
"naive": { "totalRequests": 1400 },
"x429": { "totalRequests": 180, "successes": 80, "paid": 30, "free": 50 },
"retryReductionPercent": 80+,
"paidBeatsFree": true
}2. Run the scarce API demo
npm run demoThe demo starts a local endpoint at http://127.0.0.1:8787/v1/infer. It allows a small burst through, then issues x429 tickets when saturated.
curl -i http://127.0.0.1:8787/v1/inferUnder saturation, the response includes HTTP/1.1 429, X429-Version: 1, Retry-After, and a signed ticket body.
3. Inspect the live protocol demo
curl -I https://x429.dev/429
curl https://x429.dev/429
curl https://x429.dev/.well-known/x429.jsonThe /429 endpoint exists so the public site speaks its own protocol. It signs each demo ticket with an ephemeral key and includes the public key in the response body.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
npm run check fails on Node version. | Node is older than the Web Crypto Ed25519 support expected by the repo. | Install Node 24 or newer and retry. |
| Simulator retry reduction is too low. | Capacity, free delay, or deadline assumptions were changed. | Reset the simulator defaults and compare against the acceptance targets. |
/429 does not include X429-Version. | The Pages Function did not deploy or the wrong folder was deployed. | Deploy from site/ with Wrangler so Pages Functions are included. |
| A ticket redeems before its window. | Server is skipping the notBefore check or accepting payment proof incorrectly. | Treat as a security bug and block release. |