---
key: sdk
path: /sdk
section: sdk
priority: 0.8
title: SDK reference
description: The copy-in 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 **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

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