SDK reference

The SDK ships as the npm package **@zadq/x402 — ES modules with type declarations, Node 20 or later, zero runtime dependencies — and, for integrators who prefer to vendor, as copy-in snippets**: the same modules as files to copy into an integration and review in place. Each module is self-contained and degrades gracefully.

Install

npm install @zadq/x402

import { fetchVerdict, freshness, verifyVerdictSignature } from '@zadq/x402/verdict';
import { withIdentityPolicy } from '@zadq/x402/extension';
import { SellerHolder } from '@zadq/x402/holder'; // Node only — the seller rail

The copy-in files live in the snippets/ folder of the tools repository, generated from the package's sources at every release. The module names below are the contracts; the table gives the package subpath each one ships under.

Module	Package subpath
`verdict`	`@zadq/x402/verdict` (and `@zadq/x402/keys` for the published verification keys)
`payment-required`	`@zadq/x402/extension`
`receipt`	`@zadq/x402/receipt`
`x-payment`	`@zadq/x402/header`
`badge`	`@zadq/x402/explorer` (the signal the badge renders; `verdict.updated` deliveries: `@zadq/x402/webhook`)
`holder`	`@zadq/x402/holder` (Node only)

Modules

Module	Side	Contract
`verdict`	Buyer	Fetch a verdict over the free path, check freshness against the credential's cadence promise, verify the Ed25519 signature over the canonical payload — all locally. A non-positive verdict carries `reason` from the verifier's closed vocabulary (for example `bond_insufficient` or `suspended`); a positive one never does
`payment-required`	Seller	Attach the additive `identityPolicy` extension to an HTTP 402 response (the canonical v0 seller object: one claim, closed shape) with an optional inline verdict; attach or read the vendor's trust-perimeter invitation under its own `trustPerimeter` key (`welcome` or `preferred`; never enforced)
`receipt`	Both	Carry the issuer-signed receipt of the attestation on `X-PAYMENT-IDENTITY` (`attestation-ref/v0`) and verify the issuer's Ed25519 signature locally — proof of issuance, never of standing
`x-payment`	Both	The `X-PAYMENT-IDENTITY` companion header: carry proof in either direction when the transport calls for it
`badge`	Buyer / UI	Map a verification outcome to `human-backed`, `revoked` or `unknown` — falling back to `unknown` always
`holder`	Seller (v1)	Hold the accountable party's own credential in your infrastructure over the identity network's holder library process: redeem the operator's one-shot offer, refresh the witness on your cadence, answer the service's challenges from one presentation endpoint, self-check, self-revoke; custody store sealed under your own key. Node only

Contracts every module honours

Graceful degradation. Absent, stale or unverifiable input yields

unknown; no module throws on missing infrastructure, and every product built on these modules keeps working when no verdict is available.

Canonical verification. Signature checks reproduce the signer's

canonical byte form exactly (including escaping rules and second-precision timestamps), so a verdict verifies byte-for-byte or not at all.

No personal data. Module inputs and outputs are endpoint identifiers,

signed documents and states — never personal data.

Standard vocabulary. Authentication material is an API key or a

short-lived session credential; "x402" is used descriptively for the HTTP 402 rail.

No custody by the service. The holder module keeps the credential and

its custody encoding on your side only; the service receives state and a presentation endpoint, never a key, an offer code or a proof.

Typed surface

type BadgeState = 'human-backed' | 'revoked' | 'unknown';

interface VerdictCheck {
  state: BadgeState;
  /** Present when state !== 'unknown' */
  verdict?: SignedVerdict;
  /** Why the state degraded, for logs — never for control flow */
  reason?: 'absent' | 'stale' | 'invalid-signature';
}

Fixtures and tests

The snippets ship with a fixture containing a real signed verdict from a development run (test-only public key) and a node test suite exercising the free path end to end, including every degradation branch.

The snippet sources are published in the Apache-2.0 tools repository; these pages document the contracts they implement.