SDK reference

The SDK ships as copy-in snippets: small TypeScript modules designed to be copied into an integration and reviewed in place, rather than pulled as an opaque dependency. Each module is self-contained and degrades gracefully.

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 maintained in the project's tooling repository and are provided to integrators at onboarding; these pages document the contracts they implement.