API reference
The current APIs are local workspace packages in the reference repository. They are not published npm packages yet.
Packages
| Package | Purpose |
|---|
@x429/admission-worker | Deployable v2 Cloudflare Worker with SQLite Durable Objects, finite lanes, sealed auctions, exact settlement, and execution leases. |
@x429/client | V2 proof client, pinned-trust verification, free/paid policy, mock opt-in, and exact x402 payer flow. Also retains a legacy v1 fetch export. |
@x429/payment-mock | No-money payer and verifier for local compatibility tests. |
@x429/payment-x402 | Strict x402 v2 exact EVM server/payer adapter using standard payment headers and EIP-3009. |
@x429/origin | Verifier for the Worker's signed, short-lived, replay-protected upstream assertion. |
@x429/core, @x429/hono | Legacy v1 reference. Compatibility helpers and Hono middleware; not the v2 production boundary. |
All package names above are private workspaces, not public npm artifacts. A release operator can create coordinated client-only tarballs, checksums, and install notes with npm run sdk:bundle -- <directory>. That bundle excludes the admission Worker and console.
V2 client exports
| Export | Purpose |
|---|
generateClientKey() | One-time provisioning of an Ed25519 proof-of-possession pair. Persist it in the agent secret store; never generate a new production/paid identity per request. |
x429FetchV2() | Execute the signed GET/HEAD state machine with a deadline, sealed maximum, trust pins, and explicit settlement policy. |
resumeExactPayment() | After confirmed reconciliation, verify the durably stored recovery context, obtain the current capacity-backed permit, and redeem it without a wallet signer or new authorization. |
mockSettlement() | Explicitly allow local no-money settlement. |
exactSettlement(payer, { recoveryStore, budgetStore }) | Enable exact USDC transfer only through a policy-constrained EVM payer, durable recovery WAL, and atomic gross-authorization budget. |
createNodeFileRecoveryStore() | Create a persistent Node filesystem journal that commits recovery before payment submission and retains completed audit records. |
provisionNodeFileRecoveryDirectory() | One-time durable creation and verification of the private recovery root before a signer or inspection process opens it. |
createNodeExactSpendBudgetStore() | Create the single-host shared-directory gross cap required before an exact authorization can be submitted. Multi-host signers need one strongly consistent shared service. |
provisionNodeExactSpendBudgetDirectory() | One-time durable creation/verification of the private budget root before the file-backed store is opened. |
x429Fetch() | Legacy v1 only. Fixed-price compatibility flow. |
V2 routes
| Route | Purpose |
|---|
GET /.well-known/x429.json | Publish v2 configuration and active issuer key. Exact mode includes payment.admissionChainSecurity with provider count, security level, minimum depth within the agreed boundary, timeout, poll interval, attempt cap, and RPC cap. Clients still require independent trust pins. |
GET /healthz | Verify both local signing-key round trips and expose the non-secret active origin-assertion key pin for operator comparison. It does not probe external dependencies. |
POST /x429/v2/bids | Submit one sealed maximum with a signed ticket, offer, client proof, and idempotency key. |
GET /x429/v2/bids/{bidId} | Read the final loss or signed award after the epoch closes. |
POST /x429/v2/awards/{awardId}/settle | Two-step exact challenge and settlement; uses standard x402 v2 headers. |
POST /x429/v2/awards/{awardId}/mock-settle | Local development only; disabled outside mock mode. |
POST /x429/v2/payment-intents/{paymentIntentId}/resume | Original-client recovery after confirmed exact payment; requires the signed award and original settlement idempotency key, accepts no payment signature. |
POST /x429/v2/admin/payment-intents/{paymentIntentId}/reconcile | Authenticated operator recovery using a known confirmed transaction, bounded finalized AuthorizationUsed discovery when its hash is lost, or finalized expired-unspent evidence from two configured RPC URLs. Discovery is capped at 2,048 blocks and eight discovery RPC requests, then the transaction still undergoes normal verification. Operators must select independently administered providers. |
V2 client options
| Option | Purpose |
|---|
deadlineMs | Maximum useful wait. An explicit value wins; omission defaults to 360,000ms with exact settlement and 60,000ms otherwise. The v2 client bids only when the latest possible paid slot fits, then rechecks the winning award before payment. |
maxBidAtomic | One canonical atomic-unit maximum. A submitted bid is not pre-funded. |
settlement | Explicit mockSettlement() or exactSettlement(payer, { recoveryStore, budgetStore }); omitted means never pay. |
clientKey | Persisted Ed25519 public/private pair used for every fresh proof. Production uses the pre-approved thumbprint and payment recovery requires the same identity. |
trust | Pinned issuer, audience, key id, public key, and payment mode. Exact-payment clients must also pin configHash before any network or storage I/O. |
onEvent | In-process protocol callback. Export only an explicit allowlisted projection such as type, code, and status; never log the complete event. |
resumeExactPayment() additionally requires the original request/authentication context, client key, trust pins, the same recovery and budget stores, and the non-secret recovery object committed before payment submission. WAL format 4 contains the immutable award, auction, bid, ticket, resource, method, and configuration anchors alongside the payment-intent ID, network/asset/payer, EIP-3009 nonce and short validity window, payment fingerprints, award-scoped EIP-191 payer binding, signed award, settlement and redemption idempotency keys, and settlement URL. It never contains the wallet key or transferable PAYMENT-SIGNATURE. Older WAL formats fail closed and must be reconciled before upgrading. The Node budget implementation coordinates one host through one owner-controlled persistent directory; separate directories create separate caps, so the hard loss bound remains a dedicated low-balance wallet.
Operator commands
| Command | Purpose |
|---|
npm run client:identity -- --kid x429-client-<name> --output PRIVATE_FILE | Create one exclusive mode-0600 Ed25519 identity file and print only the public enrollment values. The packed client exposes the same command as x429-client-identity. |
npm run payer:generate:staging | Create one dedicated, low-balance Base Sepolia payer in a new private file and print only its public faucet address. Mainnet payer provisioning is not claimed. |
npm run worker:bootstrap:staging -- --secrets-file PRIVATE_JSON | Validate and atomically publish the exact first-deployment secret set while issuance remains disabled. Later safe deployments do not accept a secrets file. |
npm run payment:reconcile | Resolve a recorded indeterminate exact payment with a signed award and dual-RPC evidence. Confirmed resolution requires a new private --permit-output; use --discover-transaction only when the hash is genuinely unknown. |
npm run sdk:bundle -- <directory> | Build coordinated private client/payment/origin/core tarballs with checksums and install notes; excludes the Worker and console. |
npm run console:provision -- --token-stdin --origin HTTPS_ORIGIN --secret-output PRIVATE_DIR/project.json | After creating an owner-only private directory, create one observe-console project and write its one-time telemetry credential only to a new exclusive mode-0600 file. |
npm run console:manage -- --token-stdin --action rotate --project UUID --confirm UUID --secret-output PRIVATE_DIR/replacement.json | Rotate one project and write the replacement key only to a new owner-only file. List, revoke, and purge omit --secret-output. |
Before either credential write, create the parent with install -d -m 700 PRIVATE_DIR. Stream the administrator token on stdin and import the credential file directly; never cat, echo, shell-substitute, or put either secret in argv. Credential generation, console provisioning, and console rotation use POSIX-only private-file writers. Native Windows is not supported: use reviewed secret-manager-native tooling that does not invoke those writers, or WSL on a private Linux filesystem—not /mnt/c or another shared mount. Otherwise, do not run them.