SDK reference
The SDK ships as vendorable snippets: small TypeScript modules designed to be copied into an integration and audited 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 |
payment-required | Seller | Attach the additive identityPolicy extension to an HTTP 402 response, with an optional inline verdict |
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 |
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.
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.