---
key: sdk
path: /sdk
section: sdk
priority: 0.8
title: SDK reference
description: The vendorable ZadQ SDK snippets — verdict fetching and local verification, the 402 identityPolicy extension, the companion header, and the badge — all with graceful degradation built in.
---

# 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

```ts
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.