@txnod/sdk 1.0.1

package/docs/01-authentication.md

@@ -0,0 +1,114 @@
+---
+title: "Authentication"
+description: "HMAC-SHA256 scheme for outbound API calls: headers, body canonicalization, ±300-second window, key rotation."
+sdk_version: 1.0.0
+---
+
+# Authentication
+
+Every `TxnodClient` method signs outbound requests automatically. You pass `projectId` and `apiSecret` to the constructor; the SDK takes care of headers, timestamps, HMAC, and retries. You only need to understand the scheme when debugging a `TxnodAuthInvalidError` or when building a non-TS client.
+
+The scheme below is **endpoint-agnostic** — it works identically against `https://txnod.com` (the default), a staging deployment, or any self-hosted txnod-compatible API the partner points `baseUrl` at. The server origin only changes where the signed bytes travel; the signing contract is the same.
+
+## Scheme
+
+Three request headers are required on every call:
+
+| Header | Value |
+|---|---|
+| `X-Project-Id` | ULID of the calling project (your `TXNOD_PROJECT_ID`) |
+| `X-Timestamp` | Current unix seconds (integer, as a string) |
+| `X-Signature` | 64-char lowercase hex HMAC-SHA256 |
+
+The signature is computed over the canonical bytes `${method}\n${pathname}\n${timestamp}\n${rawBody}` using `apiSecret` as the key. Method and pathname are bound into the input so an intercepted `(X-Timestamp, X-Signature)` pair cannot be replayed against a different endpoint of the same project. For `GET` / body-less `POST`, `rawBody` is the empty string.
+
+```ts
+// What the SDK does internally — you do NOT need to reimplement this when
+// you use TxnodClient. This is the exact contract a non-TS client must mirror.
+import { createHmac } from 'node:crypto';
+
+const method = 'POST';                       // uppercase HTTP verb
+const pathname = '/api/v1/invoices';          // URL pathname only — query string is NOT signed
+const timestamp = Math.floor(Date.now() / 1000);
+const rawBody = JSON.stringify(payload);      // exact bytes you put on the wire
+const signature = createHmac('sha256', apiSecret)
+  .update(`${method}\n${pathname}\n${timestamp}\n${rawBody}`)
+  .digest('hex');
+```
+
+> **Note — outbound API vs inbound webhook.** The outbound scheme above (`method\npathname\ntimestamp\nbody`) is what `TxnodClient` uses for every API call. The **inbound** webhook scheme is different — `verifyWebhookSignature` HMACs `${timestamp}.${rawBody}` because the webhook body byte stream is the only varying input. Do not mix the two formulas.
+
+## Clock skew window
+
+The server rejects requests whose `X-Timestamp` is outside `±300` seconds of server time. The SDK always stamps `Date.now()` at send time, so the only failure mode in practice is host clock drift. The server raises `TxnodTimestampOutOfWindowError` (HTTP 401, `error_code: timestamp_out_of_window`) — check NTP on the calling host.
+
+## Body canonicalization
+
+The SDK serializes request bodies with `JSON.stringify` and signs the exact bytes it puts on the wire. There is no field-order canonicalization — the HMAC covers the literal byte stream. Do not mutate a body between the SDK handing it to `fetch` and the request leaving the host (this is only a concern if you proxy or rewrite).
+
+## Retry behaviour
+
+`signedFetch` retries automatically:
+
+- `429`: up to 3 retries, honouring `Retry-After` header (seconds). Backoff is `max(Retry-After, fullJitterExponential)` with base 500 ms and cap 30 s. `Retry-After` is itself capped at 600 s — defends against a hostile or buggy upstream returning a far-future date.
+- `5xx`: GET retries on every 5xx (up to 2). POST only retries on **503** (`pool_exhausted`, server overloaded — server has not yet committed any state) and **504** (gateway timeout — request did not reach the application). 500/502 on POST surface immediately, because the server may have already processed the request before failing and re-issuing risks duplication.
+- Each retry re-signs with a fresh `timestamp`.
+
+After retries are exhausted, the response is returned to the caller and, if still non-2xx, mapped to a typed `TxnodError` (see [`05-errors.md`](./05-errors.md)).
+
+### Per-attempt timeout and body-size cap
+
+`TxnodClient` accepts two safety bounds:
+
+- `requestTimeoutMs` (default `30_000`) — per-attempt HTTP timeout via `AbortSignal.timeout`. Each retry gets its own clock.
+- `maxResponseBytes` (default `1 MiB`) — hard cap on response body size. Over-cap responses are surfaced as a typed 502 with `error_code: 'internal_error'` so the SDK never buffers an unbounded body from a hostile upstream.
+
+```ts
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+  requestTimeoutMs: 15_000,    // optional
+  maxResponseBytes: 256 * 1024, // optional
+});
+```
+
+### Request logger
+
+```ts
+const client = new TxnodClient({
+  /* ... */
+  requestLogger: (entry) => {
+    // entry.method | entry.path | entry.status | entry.durationMs | entry.attempt | entry.requestId
+    log.info('txnod', entry);
+  },
+});
+```
+
+One entry per HTTP attempt (success or failure, including each retry). Errors thrown from the logger are swallowed by the SDK so a buggy logger never fails a request.
+
+## Key rotation
+
+1. Generate a new key in the dashboard. The old key stays valid until you revoke it.
+2. Roll `TXNOD_API_SECRET` (and `TXNOD_WEBHOOK_SECRET`, which is the same value) in your secrets manager.
+3. Restart the application so the new value is picked up.
+4. Revoke the old key in the dashboard.
+
+When the server sees a request signed by a revoked key, it raises `TxnodKeyRevokedError` (HTTP 401, `error_code: key_revoked`). Treat as fatal — do not retry with the same secret.
+
+## Common failure modes
+
+| Symptom | Likely cause |
+|---|---|
+| `TxnodAuthInvalidError` on every call | `TXNOD_PROJECT_ID` does not match a project owned by the key, or headers are absent |
+| `TxnodSignatureInvalidError` | Wrong `apiSecret`, or a proxy is mutating the request body after signing |
+| `TxnodTimestampOutOfWindowError` | Host clock drift > 300 s — fix NTP |
+| `TxnodKeySuspendedError` / `TxnodProjectSuspendedError` | Operator action; contact support |
+| `TxnodKeyRevokedError` (HTTP 403) | Key was rotated; pick up the new secret |
+| `TxnodSubscriptionExpiredError` (HTTP 402) | Operator's TxNod subscription is not `active`; writes are gated until the operator renews via the dashboard `/billing` page. Reads keep working — surface the failure to the operator out-of-band rather than auto-retrying |
+
+See [`05-errors.md`](./05-errors.md) for how to branch on each.
+
+## Related
+
+- [`02-invoices.md`](./02-invoices.md) — what the authenticated calls do
+- [`04-webhooks.md`](./04-webhooks.md) — inbound HMAC uses the **same secret** and the same HMAC primitive but with an `X-Txnod-Signature: t=<unix>,v1=<hex>` header shape

package/docs/02-invoices.md

@@ -0,0 +1,216 @@
+---
+title: "Invoices"
+description: "Create, fetch, search, and cancel invoices; the nine-state invoice lifecycle."
+sdk_version: 1.0.0
+---
+
+# Invoices
+
+## Lifecycle
+
+An invoice moves through a state machine. Statuses are the `InvoiceStatus` union:
+
+| Status | Meaning | Terminal? |
+|---|---|---|
+| `pending` | Created, awaiting on-chain receipt | no |
+| `detected` | On-chain receipt seen, below confirmation threshold | no |
+| `paid` | Meets confirmation threshold AND covers `amount_crypto` | **no, reorg-reversible** |
+| `overpaid` | Paid with strictly more than `amount_crypto` | **no, reorg-reversible** |
+| `partial` | Detected under `amount_crypto`; waiting for additional deposits | no |
+| `expired` | `expires_at` passed before reaching paid | yes |
+| `expired_paid_late` | Payment arrived after `expires_at` | yes |
+| `reverted` | Previously `paid`/`overpaid` but dropped by a chain reorg | yes |
+| `cancelled` | Explicitly cancelled via `cancelInvoice` | yes |
+
+**`paid` is not the end of the story.** A deeper reorg can still invalidate on-chain receipts. Only trust `paid` / `overpaid` for fulfilment once `confirmations` ≥ your project's finalization threshold, and always have a path to roll back on an `invoice.reverted` webhook — see [`06-idempotency.md`](./06-idempotency.md).
+
+## `createInvoice(body)`
+
+```ts
+const invoice = await client.createInvoice({
+  external_id: 'order-42',       // required, 1..128 chars, unique per project
+  coin: 'usdt_trc20',             // required — see reference/types.md#coin
+  amount_usd: 9.99,               // EITHER amount_usd OR amount_crypto (not both)
+  // amount_crypto: '9.990000',
+  callback_url: 'https://your-site.com/api/txnod-webhook',  // optional
+  metadata: { order_ref: '42' },  // optional free-form JSON
+});
+```
+
+Response (selected fields, full shape in [`reference/types.md`](./reference/types.md#invoiceresponse)):
+
+```ts
+invoice.id               // ULID, txnod-side primary key
+invoice.external_id      // echoed back
+invoice.address          // deposit address, never reused across invoices
+invoice.amount_crypto    // decimal string (matches the coin's display precision)
+invoice.amount_crypto_units // integer string in smallest unit (sats, wei, lovelace, ...)
+invoice.payment_uri           // BIP-21 / EIP-681 / Cardano URI for rendering a QR
+invoice.status           // 'pending' on creation
+invoice.rate_snapshot    // null if amount_crypto was passed; otherwise binding rate
+invoice.expires_at_iso   // ISO-8601 UTC
+invoice.matching_mode    // 'exact' | 'at_least' | 'any' — governs partial/overpaid classification
+invoice.confirmation_threshold // per-chain default, configurable in dashboard
+```
+
+### Idempotency
+
+The pair `(project_id, external_id)` is `UNIQUE`. A second `createInvoice` with the same `external_id` returns `TxnodExternalIdConflictError` — treat it as idempotent success and fetch the existing invoice:
+
+```ts
+import { TxnodClient, TxnodExternalIdConflictError } from '@txnod/sdk';
+
+try {
+  return await client.createInvoice({ external_id, coin, amount_usd });
+} catch (err) {
+  if (err instanceof TxnodExternalIdConflictError) {
+    const page = await client.searchInvoices({ external_id, limit: 1 });
+    return page.items[0]!;
+  }
+  throw err;
+}
+```
+
+### USD vs crypto amount
+
+Exactly one of `amount_usd` / `amount_crypto` must be provided.
+
+- `amount_usd`: TxNod computes the binding crypto amount at creation using the current CoinGecko rate. `rate_snapshot` is populated with the rate, source, and age. Any subsequent market move is not reflected — **the invoice amount is fixed at creation**.
+- `amount_crypto`: you set the crypto amount directly. `rate_snapshot` is `null`, `amount_usd` is `null`. Use this if you price in crypto upstream.
+
+For USD-priced integrations, call [`quoteAmount`](./03-rates-and-quotes.md) before creation if you want to preview the amount (indicative only — binding rate is still captured at `createInvoice` time).
+
+### Pool exhaustion (503)
+
+`createInvoice` allocates an address from a per-chain pool bounded by the project's `poolSizePerChain[chain]` (default 20 — matches the BIP-44 / CIP-1852 gap-limit of 20 so a recovery wallet still rediscovers every deposit). If the pool is already at cap with no `available` slot, the server returns `503` `pool_exhausted` with a `Retry-After` header and the SDK throws [`TxnodPoolExhaustedError`](./05-errors.md) after its internal retry budget is exhausted. `err.retry_after_seconds` carries the header value (server-computed from the soonest `locked_until` or project cooldown); wait that interval then retry, or raise the cap from the operator dashboard if the error recurs under normal load.
+
+### TRON activation error
+
+TRON is the only chain that requires a recipient address to be "activated" with at least 1 TRX (or 1 USDT-TRC20) before it can hold funds. TxNod handles activation on the operator side via the dashboard. Until the operator's TRON wallet has at least one activated row in its address pool, `createInvoice({ coin: 'trx' | 'usdt_trc20' })` raises [`TxnodTronNoActivatedAddressesError`](./05-errors.md) (HTTP 422, `error_code: tron_no_activated_addresses_available`). This is operator-action-required and not transient — do not auto-retry.
+
+```ts
+import { TxnodClient, TxnodTronNoActivatedAddressesError, TxnodError } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+});
+
+try {
+  const invoice = await client.createInvoice({
+    external_id: 'order-1',
+    amount_usd: 9.99,
+    coin: 'usdt_trc20',
+    callback_url: 'https://your-site.com/api/txnod-webhook',
+  });
+  console.log(invoice.id);
+} catch (err) {
+  if (err instanceof TxnodTronNoActivatedAddressesError) {
+    // Surface this to the user — the operator must complete TRON setup before
+    // TRON invoices succeed. err.walletId is the operator wallet id, useful
+    // for in-app deep-links if your UI knows the operator dashboard URL.
+    console.error('TRON not ready, walletId =', err.walletId, 'request_id =', err.request_id);
+    throw err; // not retryable
+  }
+  if (err instanceof TxnodError) console.error(err.error_code, err.request_id);
+  throw err;
+}
+```
+
+The `walletId` field is guaranteed non-empty (the SDK constructor fails fast if the server omits it). Treat the error as a structural setup gap on the operator's side — fall back to a non-TRON coin or block the user's checkout until the operator activates their TRON pool.
+
+### Testnet
+
+Testnet runs are project-scoped, not request-scoped: the operator creates a separate `kind='testnet'` project (via the dashboard) and binds testnet-only wallets to it. Once that's done the SDK code path is identical to production — invoice creation has no `network` knob, so partner code stays the same. The `kind` is a property of the project, not of each invoice.
+
+```ts
+// Same code regardless of kind. Talk to the testnet project's API key
+// and the matching invoices get testnet addresses + testnet confirmation
+// cadence.
+const invoice = await client.createInvoice({
+  external_id: 'staging-order-1',
+  amount_usd: 5,
+  coin: 'btc',
+  callback_url: 'https://staging.example.com/api/txnod-webhook',
+});
+console.log(invoice.address);   // testnet-prefix address (e.g. 'tb1...' for BTC)
+```
+
+The matching operator wallet must be registered with a testnet-prefix xpub (`tpub`/`vpub`/`zpub` for BTC, `tpub` for ETH/Polygon/BSC/TRON, `addr_test1...` stake for Cardano). The SDK's automatic address verification (`createInvoice` → `verifyAddress`) accepts those prefixes whenever the project is `kind='testnet'` — no flag, no separate setup. Use a public testnet faucet to fund the deposit address. Webhooks, finalization thresholds, and idempotency behave the same as production; only the chain and confirmation cadence differ.
+
+### Address verification
+
+When `TXNOD_<chain>_XPUB` is set in the environment, the SDK automatically derives the expected receive address from the configured xpub at the invoice's `derivation_path` and compares it to the server-returned `invoice.address`. On mismatch `createInvoice` throws `AddressVerificationError` (not a `TxnodError` subclass; the verification happens client-side after the HTTP call). This is the SDK's defense against a compromised TxNod backend silently swapping the deposit address. Set the env var per chain you accept; omit it to skip verification on that chain.
+
+**Multiple xpubs (wallet rotation).** Each `TXNOD_<chain>_XPUB` value can be a single xpub, a comma-separated newest-first list, or a JSON array of strings. Verification iterates newest-first and accepts on the first match.
+
+```bash
+TXNOD_BTC_XPUB=zpub_new,zpub_old
+# equivalent JSON-array form:
+TXNOD_BTC_XPUB=["zpub_new","zpub_old"]
+```
+
+**TON has no xpub** — its address is derived from `(walletPubkey, walletVersion, subwalletId, workchain)`. Configure four env vars; only `TXNOD_TON_PUBKEY` is required:
+
+```bash
+TXNOD_TON_PUBKEY=<64-hex Ed25519 pubkey from operator's wallet device>
+TXNOD_TON_WALLET_VERSION=v4R2          # default; alternatives: v3R2, v5R1
+TXNOD_TON_SUBWALLET_ID=698983191       # default; standard for v3R2/v4R2
+TXNOD_TON_WORKCHAIN=0                  # default; basechain. -1 = masterchain
+```
+
+The pubkey is the public Ed25519 key the operator's wallet device exports — never the secret key. The SDK is non-custodial by construction.
+
+**Wallet rotation in long-lived processes.** After changing an env var without restarting the worker, call `client.refreshXpubConfig()` to pick up the new value.
+
+**Testnet.** Use the testnet-prefixed xpub variant (`tpub`/`vpub`/`zpub`); the verifier accepts both prefix styles whenever the project's `kind` is `'testnet'`.
+
+## `getInvoice(id)`
+
+```ts
+const invoice = await client.getInvoice(id); // 01HK8MAR2QEXAMPLE000000000
+```
+
+Raises `TxnodInvoiceNotFoundError` if the id does not belong to the calling project. Use the ULID from `createInvoice`, not `external_id`.
+
+## `searchInvoices(query)`
+
+```ts
+const page = await client.searchInvoices({
+  status: 'paid',           // optional; any InvoiceStatus
+  external_id: 'order-42',  // optional
+  address: '...',           // optional
+  tx_hash: '...',           // optional
+  date_from: '2026-04-01T00:00:00Z',
+  date_to: '2026-04-22T00:00:00Z',
+  cursor: undefined,        // pass page.next_cursor for the next page
+  limit: 50,                // 1..200, default 50
+});
+for (const invoice of page.items) { /* ... */ }
+if (page.next_cursor !== undefined) { /* call again with cursor: page.next_cursor */ }
+```
+
+Pagination is cursor-based. `next_cursor` is `undefined` on the last page.
+
+`network` is no longer part of the query — invoices belong to a single project, and that project has a fixed `kind`, so there is nothing to disambiguate per-call.
+
+## `cancelInvoice(id)`
+
+```ts
+const cancelled = await client.cancelInvoice(id);
+```
+
+Allowed only while the invoice is cancellable (`pending`, or `detected` below threshold depending on project config). Raises `TxnodInvoiceNotCancellableError` otherwise. Cancellation is a state transition, not a delete — the invoice record stays in your audit trail and its derivation slot is recycled into the address pool, so the same address may surface on a future invoice from the same project.
+
+## Orphan payments
+
+A receipt that lands on a derivation address not currently bound to any open invoice is recorded as an *orphan payment*. Typical cause: user paid after `expires_at`, or paid to an address from a previously cancelled invoice.
+
+- [`listOrphanPayments`](./reference/client.md#listorphanpayments) — list and filter
+- [`attributeOrphanPayment`](./reference/client.md#attributeorphanpayment) — post-hoc bind an orphan to an `external_id`; the returned invoice reflects the attribution
+
+## Related
+
+- [`04-webhooks.md`](./04-webhooks.md) — status changes you will observe from the outside
+- [`05-errors.md`](./05-errors.md) — every error `createInvoice` / `getInvoice` / `cancelInvoice` can raise
+- [`reference/types.md`](./reference/types.md) — authoritative type shapes

package/docs/03-rates-and-quotes.md

@@ -0,0 +1,82 @@
+---
+title: "Rates and quotes"
+description: "Pre-invoice USD→crypto pricing via getRates and quoteAmount. Indicative only — binding rate is captured at createInvoice."
+sdk_version: 1.0.0
+---
+
+# Rates and quotes
+
+Two methods expose current USD→crypto pricing for display before invoice creation. **Both return indicative rates**, not a binding quote. The binding rate is the one captured by `createInvoice` in `invoice.rate_snapshot`. Any drift between a pre-invoice quote and the invoice itself is the partner's responsibility.
+
+## `getRates(query)` — list of current rates
+
+```ts
+const rates = await client.getRates({
+  coins: 'btc,eth,usdt_erc20', // optional CSV; omit to get all enabled coins
+});
+
+// rates.quoted_at                  — ISO-8601 UTC timestamp of the quote
+// rates.source                      — always 'coingecko'
+// rates.indicative_notice           — human-readable disclaimer string
+// rates.rates.btc                   — may be undefined if not enabled/returned
+// rates.rates.btc?.rate             — decimal string, USD per 1 BTC, e.g. "62000.00"
+// rates.rates.btc?.rate_is_stale    — true if rate is older than the freshness SLO
+// rates.rates.btc?.rate_age_seconds — int seconds since the quote was fetched
+```
+
+`rates.rates` is keyed by `Coin` (see [`reference/types.md`](./reference/types.md#coin)); each per-coin value may be absent if the coin is not enabled for the project or not returned by the upstream.
+
+## `quoteAmount(query)` — USD → per-coin crypto amount
+
+```ts
+const quote = await client.quoteAmount({
+  amount_usd: 9.99,              // required, positive finite number
+  coins: 'btc,usdt_trc20',        // optional CSV; omit for all enabled coins
+});
+
+// quote.amount_usd                   — echoed back
+// quote.quoted_at                     — ISO-8601 UTC
+// quote.source                        — always 'coingecko'
+// quote.quotes.btc?.amount_crypto     — decimal string, how much BTC for 9.99 USD
+// quote.quotes.btc?.amount_crypto_units — integer string in base units (sats)
+// quote.quotes.btc?.rate              — same decimal string as getRates
+// quote.quotes.btc?.rate_is_stale
+// quote.quotes.btc?.rate_age_seconds
+```
+
+## Indicative vs binding
+
+| | `getRates` / `quoteAmount` | `createInvoice` |
+|---|---|---|
+| Source | CoinGecko | CoinGecko |
+| Freshness | `rate_is_stale` / `rate_age_seconds` surfaced | same, captured into `rate_snapshot` |
+| Binding? | No — for display only | **Yes** — invoice amount is fixed |
+| Who owns drift? | Partner | — |
+
+If you need a binding quote, call `createInvoice` directly. The invoice embeds `rate_snapshot` with the rate, source, and age at the moment of creation.
+
+## `rate_is_stale` — what to do
+
+`rate_is_stale: true` means the upstream CoinGecko feed has not refreshed within the project's freshness SLO. You can still create an invoice — the server will reuse the latest cached rate and mark `rate_snapshot.rate_is_stale`. For UX, consider surfacing a "rates may be stale" notice to the payer.
+
+## Typical flow
+
+```ts
+// 1. Show the user approximate amounts across enabled coins
+const quote = await client.quoteAmount({ amount_usd: 9.99 });
+
+// 2. User picks a coin; create the binding invoice
+const invoice = await client.createInvoice({
+  amount_usd: 9.99,
+  coin: 'usdt_trc20',
+  external_id: orderId,
+});
+
+// 3. Tell the user the exact `invoice.amount_crypto` (not the earlier indicative)
+```
+
+## Related
+
+- [`02-invoices.md`](./02-invoices.md#usd-vs-crypto-amount) — how `createInvoice` interprets `amount_usd`
+- [`reference/client.md`](./reference/client.md) — full method signatures
+- [`reference/types.md`](./reference/types.md) — `RatesResponse` / `QuoteResponse` shapes

package/docs/04-webhooks.md

@@ -0,0 +1,126 @@
+---
+title: "Webhooks"
+description: "Event types, verifyWebhookSignature, ±300-second window, event_id idempotency, retries, resend."
+sdk_version: 1.0.0
+---
+
+# Webhooks
+
+TxNod sends webhook events to the `callback_url` you set on an invoice. Events are signed with HMAC-SHA256 over the raw request body. The SDK ships [`verifyWebhookSignature`](./reference/client.md#verifywebhooksignature) — the only correct way to accept inbound events.
+
+## Event types
+
+The `WebhookEvent` type is a discriminated union on `event_type`:
+
+| `event_type` | When | Terminal? |
+|---|---|---|
+| `invoice.detected` | First on-chain receipt seen, below threshold | no |
+| `invoice.paid` | Threshold reached AND exact-amount match | **reorg-reversible** |
+| `invoice.overpaid` | Threshold reached AND strict over-payment | **reorg-reversible** |
+| `invoice.partial` | Receipt below `amount_crypto`, still open | no |
+| `invoice.expired` | `expires_at` passed before `paid` | yes |
+| `invoice.expired_paid_late` | Payment arrived after `expires_at` | yes |
+| `invoice.reverted` | Previously `paid`/`overpaid` dropped by reorg | yes |
+
+Every event shares this envelope:
+
+```ts
+{
+  event_id: string;        // ULID — idempotency key, stable across retries
+  event_type: '...';        // discriminant above
+  created_at: number;       // unix seconds
+  created_at_iso: string;   // ISO-8601 UTC
+  project_id: string;       // ULID
+  attempt: number;          // 1-based; increments on retry
+  data: Record<string, unknown>; // shape depends on event_type
+}
+```
+
+**Always key your idempotency on `event_id`, not on `(invoice_id, status)`.** The same `event_id` is sent on every delivery attempt. See [`06-idempotency.md`](./06-idempotency.md).
+
+## Signature header
+
+```
+X-Txnod-Signature: t=<unix_seconds>,v1=<64_lowercase_hex>
+```
+
+- `t` — the server's unix timestamp at signing time.
+- `v1` — HMAC-SHA256 hex digest of `${t}.${rawBody}` using `TXNOD_WEBHOOK_SECRET` (which equals `TXNOD_API_SECRET`).
+
+## `verifyWebhookSignature(headers, rawBody, secret)`
+
+```ts
+import {
+  verifyWebhookSignature,
+  TxnodHmacError,
+  TxnodSignatureFormatError,
+  TxnodTimestampError,
+} from '@txnod/sdk';
+
+export async function POST(request: Request): Promise<Response> {
+  const rawBody = await request.text(); // must be the exact bytes
+
+  try {
+    const event = verifyWebhookSignature(
+      request.headers,
+      rawBody,
+      process.env.TXNOD_WEBHOOK_SECRET!,
+    );
+    // event is now narrowed — use event.event_type as the discriminant
+  } catch (err) {
+    if (err instanceof TxnodSignatureFormatError) return new Response('bad header', { status: 401 });
+    if (err instanceof TxnodHmacError) return new Response('bad sig', { status: 401 });
+    if (err instanceof TxnodTimestampError) {
+      console.warn('clock skew seconds:', err.skew_seconds);
+      return new Response('stale', { status: 401 });
+    }
+    throw err;
+  }
+  return Response.json({ ok: true });
+}
+```
+
+The function is synchronous and throws typed errors on any failure:
+
+- `TxnodSignatureFormatError` — header absent or not matching `t=<int>,v1=<hex>`.
+- `TxnodTimestampError` — `|now - t| > 300` seconds. The `skew_seconds` field exposes the signed delta for alerting on drift.
+- `TxnodHmacError` — computed HMAC did not match. Also thrown when the hex is the wrong length.
+- `TxnodWebhookPayloadParseError` — HMAC verified successfully but the body is not valid JSON. Indicates a misbehaving server release. `.cause` is the underlying `SyntaxError`. Treat as 401-class (do not parse, do not act).
+
+On success it returns the typed, parsed `WebhookEvent` whose `data` is fully typed under each `event_type` discriminant — see [`reference/types.md`](./reference/types.md#webhookevent).
+
+**Headers parameter accepts three shapes**: Web API `Headers`, `Record<string, string>`, or `Record<string, string[]>` — whichever your framework exposes. Matching is case-insensitive.
+
+## Raw body is load-bearing
+
+HMAC is computed over the exact request bytes. Anything that re-serializes JSON between the wire and your handler breaks the signature.
+
+- **Next.js App Router**: `await request.text()` is safe — Next does not pre-parse.
+- **Express**: use `express.raw({ type: 'application/json' })` for the webhook route, **not** `express.json()`. See [`examples/express-webhook-receiver.md`](./examples/express-webhook-receiver.md).
+- **Fastify**: opt into the `content-type-parser` raw body hook.
+- **Any middleware that rewrites bodies (sanitizers, logging wrappers)**: must run after the webhook route, not before.
+
+## Retry and delivery guarantees
+
+- Deliveries are at-least-once. The same `event_id` can arrive multiple times.
+- Retries are dispatched by the TxNod server (up to the DLQ threshold). Each attempt re-signs with a fresh `t`.
+- Ordering is **not** guaranteed across events for a single invoice. Treat the `status` inside `event.data` as the source of truth, not the arrival order.
+- Return HTTP 2xx to ack. Any non-2xx triggers a retry.
+
+## List and resend events
+
+- [`listWebhookEvents`](./reference/client.md#listwebhookevents) — paginated list for a project, filterable by `status` (`delivered` / `retrying` / `dlq` / `skipped`), `event_type`, `invoice_id`, `since`.
+- [`resendWebhookEvent(eventId)`](./reference/client.md#resendwebhookevent) — re-enqueues the delivery; produces a new attempt with a fresh `event_id`, and the response carries `original_event_id` for lineage.
+
+## Driving webhook events deterministically (sandbox)
+
+For tests that need every event type without waiting for chain activity, use the SDK's sandbox surface — see [`05-sandbox.md`](./05-sandbox.md). `client.sandbox.simulateDetect` / `simulatePaid` / `simulateOverpaid` / `simulatePartial` / `simulateExpire` / `simulateLatePayment` / `simulateReorg` / `simulateReconfirm` walk the state machine; the resulting webhooks carry `mode: 'sandbox'` and your verifier code path is unchanged.
+
+Use these to recover from a bad deploy that 500'd on real events (pull the DLQ, fix, resend).
+
+## Related
+
+- [`05-errors.md`](./05-errors.md) — signature errors and the other webhook-side error classes
+- [`06-idempotency.md`](./06-idempotency.md) — why to key on `event_id`
+- [`examples/express-webhook-receiver.md`](./examples/express-webhook-receiver.md) — full Express receiver with raw body
+- [`examples/nextjs-route-handler.md`](./examples/nextjs-route-handler.md) — Next.js 16 App Router handler