@txnod/sdk 1.0.1

package/docs/reference/client.md

@@ -0,0 +1,392 @@
+---
+title: "TxnodClient reference"
+description: "Every method of TxnodClient and the verifyWebhookSignature helper: signature, behaviour, and a minimal example."
+sdk_version: 1.0.0
+---
+
+# `TxnodClient` reference
+
+```ts
+import { TxnodClient } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: string;            // required — your TXNOD_PROJECT_ID
+  apiSecret: string;            // required — your TXNOD_API_SECRET
+  baseUrl?: string;             // optional — defaults to 'https://txnod.com'
+  requestTimeoutMs?: number;    // optional — per-attempt HTTP timeout (default 30_000)
+  maxResponseBytes?: number;    // optional — body size cap (default 1 MiB)
+  requestLogger?: TxnodRequestLogger; // optional — per-attempt observer
+});
+```
+
+`baseUrl` controls only the HTTP origin the SDK talks to. The HMAC scheme, header names, request/response shapes, and retry semantics are all endpoint-agnostic. Any trailing slash is stripped by the constructor. Typical values:
+
+- Omitted → `https://txnod.com` (default).
+- `TXNOD_BASE_URL=https://staging.txnod.com` for a staging environment.
+- `'https://pay.mycompany.com'` for a self-hosted txnod-compatible deployment.
+
+Every method returns a `Promise<T>` and throws a subclass of `TxnodError` on a non-2xx response. Retries for `429` (×3, honouring `Retry-After`) and `5xx` (×2, full-jitter backoff, base 500 ms, cap 30 s) happen inside the SDK.
+
+After every call (success or error) the client stores the server's `X-Txnod-Request-Id` header on `client.lastRequestId` (`string | undefined`). On error paths the same id is also surfaced as `err.request_id` on the thrown `TxnodError`. The field is per-instance — concurrent calls on a shared client overwrite each other; create a client per request scope, or read the field synchronously after `await`-ing.
+
+Methods below are ordered by how you will reach for them in a typical integration.
+
+---
+
+## `createInvoice`
+
+Create a new invoice. Idempotent on `(project_id, external_id)`.
+
+**Signature**
+
+```ts
+createInvoice(body: InvoiceCreateRequest): Promise<InvoiceResponse>
+```
+
+**Parameters**
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `external_id` | `string` (1..128) | yes | Your-side stable id for this charge |
+| `coin` | `Coin` | yes | One of the 15 supported coins |
+| `amount_usd` | `number` positive finite | either-or | Mutually exclusive with `amount_crypto` |
+| `amount_crypto` | `string` (`^\d+(\.\d+)?$`) | either-or | Mutually exclusive with `amount_usd` |
+| `callback_url` | `string` (https URL) | no | Webhook target for this invoice |
+| `metadata` | `Record<string, unknown>` | no | Free-form JSON returned on the invoice |
+
+**Throws**: `TxnodExternalIdConflictError` (idempotent — fetch existing), `TxnodValidationError`, `TxnodInvalidCoinError`, `TxnodCoinNotEnabledError`, `TxnodAmountOutOfRangeError`, `TxnodXpubNotVerifiedError`, `TxnodWalletNotFoundError`, `TxnodWalletNotBoundError`, `TxnodInvalidWebhookUrlError`, `TxnodTronNoActivatedAddressesError` (TRON only — operator must activate addresses), `TxnodSubscriptionExpiredError` (HTTP 402 — operator must renew subscription), `TxnodPoolExhaustedError` (retryable), auth/identity family (see [`../05-errors.md`](../05-errors.md)). The SDK also raises `AddressVerificationError` (not a `TxnodError` subclass) when the returned `address` does not derive from a configured xpub — see [`../02-invoices.md`](../02-invoices.md#address-verification).
+
+**Example**
+
+```ts
+const invoice = await client.createInvoice({
+  external_id: 'order-42',
+  coin: 'usdt_trc20',
+  amount_usd: 9.99,
+  callback_url: 'https://your-site.com/api/txnod-webhook',
+});
+```
+
+---
+
+---
+
+## `createOrGetInvoice`
+
+Idempotent invoice creation. Tries `createInvoice`; on `TxnodExternalIdConflictError` fetches the pre-existing invoice via `searchInvoices({ external_id })` and returns it.
+
+**Signature**
+
+```ts
+createOrGetInvoice(body: InvoiceCreateRequest): Promise<InvoiceResponse>
+```
+
+**Throws**: every error that `createInvoice` can throw EXCEPT `TxnodExternalIdConflictError`. If the conflict is raised but the matching invoice cannot be fetched (race, recently deleted), the original conflict error rethrows.
+
+---
+
+## `refreshXpubConfig`
+
+Re-read `TXNOD_<chain>_XPUB` env vars (and `TXNOD_TON_PUBKEY` siblings) into the client's xpub config. Call after wallet rotation in long-lived processes.
+
+**Signature**
+
+```ts
+refreshXpubConfig(): void
+```
+
+Idempotent. No-op when env vars are unchanged.
+
+---
+
+## `getInvoice`
+
+Fetch an invoice by its ULID.
+
+**Signature**
+
+```ts
+getInvoice(id: string): Promise<InvoiceResponse>
+```
+
+**Throws**: `TxnodInvoiceNotFoundError` on unknown id.
+
+**Example**
+
+```ts
+const invoice = await client.getInvoice('01HK8MAR2QEXAMPLE000000000');
+```
+
+---
+
+## `searchInvoices`
+
+Cursor-paginated search.
+
+**Signature**
+
+```ts
+searchInvoices(query: InvoiceSearchQuery): Promise<CursorPaginatedInvoiceResponse>
+```
+
+**Query fields** (all optional)
+
+| Field | Type | Notes |
+|---|---|---|
+| `external_id` | `string` | Exact match |
+| `address` | `string` | Exact match on deposit address |
+| `tx_hash` | `string` | Invoices that received this tx |
+| `amount` | `string` | Crypto amount as decimal string |
+| `status` | `InvoiceStatus` | See [`../02-invoices.md`](../02-invoices.md#lifecycle) |
+| `date_from` / `date_to` | ISO-8601 datetime | Created-at window |
+| `cursor` | ULID | `next_cursor` from the previous page |
+| `limit` | `1..200` | Default `50` |
+
+**Response**: `{ items: InvoiceResponse[], next_cursor?: string }`. `next_cursor` is omitted on the last page.
+
+**Example**
+
+```ts
+const page = await client.searchInvoices({ status: 'paid', limit: 50 });
+for (const invoice of page.items) { /* ... */ }
+```
+
+---
+
+## `cancelInvoice`
+
+**Signature**
+
+```ts
+cancelInvoice(id: string): Promise<InvoiceResponse>
+```
+
+**Throws**: `TxnodInvoiceNotFoundError`, `TxnodInvoiceNotCancellableError` when the invoice is past its cancellable state.
+
+---
+
+## `getRates`
+
+Current indicative USD→coin rates. See [`../03-rates-and-quotes.md`](../03-rates-and-quotes.md).
+
+**Signature**
+
+```ts
+getRates(query: { coins?: string }): Promise<RatesResponse>
+```
+
+`coins` is an optional comma-separated list. Omit for all enabled coins.
+
+---
+
+## `quoteAmount`
+
+Indicative USD → per-coin crypto quote. See [`../03-rates-and-quotes.md`](../03-rates-and-quotes.md).
+
+**Signature**
+
+```ts
+quoteAmount(query: { amount_usd: number; coins?: string }): Promise<QuoteResponse>
+```
+
+---
+
+## `listOrphanPayments`
+
+Paginated list of on-chain receipts that did not match any open invoice.
+
+**Signature**
+
+```ts
+listOrphanPayments(query: OrphanPaymentListQuery): Promise<CursorPaginatedOrphanPaymentResponse>
+```
+
+**Query fields** (all optional)
+
+| Field | Type | Notes |
+|---|---|---|
+| `chain` | `Chain` | `btc` / `eth` / `tron` / `ada` / `polygon` / `bsc` / `ton` |
+| `attributed` | `boolean` | Filter by attribution state (SDK serialises to `?attributed=true`/`false`) |
+| `tx_hash` | `string` | Exact |
+| `date_from` / `date_to` | ISO-8601 datetime | |
+| `amount_units_gte` / `amount_units_lte` | integer string | Filter in smallest unit |
+| `cursor` | ULID | |
+| `limit` | `1..200` | Default `50` |
+
+---
+
+## `attributeOrphanPayment`
+
+Post-hoc bind an orphan on-chain receipt to an `external_id`.
+
+**Signature**
+
+```ts
+attributeOrphanPayment(
+  txHash: string,
+  body: OrphanAttributeRequest,
+): Promise<InvoiceResponse>
+```
+
+**Body**
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `external_id` | `string` (1..128) | yes | Target invoice's external id |
+| `user_id` | `string` (1..256) | no | Your-side user id for audit trail |
+| `metadata` | `Record<string, unknown>` | no | |
+| `to_address` | `string` | no | Disambiguate among multi-output txs |
+| `tx_output_index` | `int ≥ 0` | no | Disambiguate among multi-output txs |
+
+**Throws**: `TxnodOrphanNotFoundError`, `TxnodOrphanAlreadyAttributedError` (idempotent — treat as success).
+
+---
+
+## `listWebhookEvents`
+
+Paginated audit list of outbound webhook events for the calling project.
+
+**Signature**
+
+```ts
+listWebhookEvents(query: WebhookEventListApiQuery): Promise<WebhookEventListResponse>
+```
+
+**Query fields** (all optional)
+
+| Field | Type | Notes |
+|---|---|---|
+| `status` | `'delivered' \| 'retrying' \| 'dlq' \| 'skipped'` | |
+| `event_type` | `WebhookEventType` | See [`../04-webhooks.md`](../04-webhooks.md#event-types) |
+| `mode` | `'production' \| 'testnet' \| 'sandbox'` | Filter events by the source project's kind (mode = project.kind on the server side) |
+| `since` | ISO-8601 datetime | |
+| `invoice_id` | ULID | |
+| `cursor` | ULID | |
+| `limit` | `1..200` | Default `50` |
+
+---
+
+## `resendWebhookEvent`
+
+Re-enqueue a previously dispatched webhook event.
+
+**Signature**
+
+```ts
+resendWebhookEvent(eventId: string): Promise<WebhookEventResendResponse>
+```
+
+**Response**
+
+| Field | Notes |
+|---|---|
+| `event_id` | New ULID for the resent delivery |
+| `original_event_id` | ULID of the original event |
+| `event_type` | Same as the original |
+| `project_id` / `invoice_id` / `target_url` | Lineage |
+
+**Throws**: `TxnodEventNotFoundError`.
+
+---
+
+## Sandbox surface (`client.sandbox.*`)
+
+Lazy accessor (`client.sandbox` is constructed on first use; bundlers tree-shake the entire namespace when never referenced) onto the 14 sandbox-mode endpoints introduced by Story 37.2. Use it from a sandbox-API-secret-authenticated client (`apiSecret: 'sk_sandbox_...'` + `environment: 'non-production'`) — production secrets cannot reach these routes (the server returns `production_key_against_sandbox_project`). See [`../05-sandbox.md`](../05-sandbox.md) for the lifecycle picture and per-method worked examples.
+
+```ts
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_SANDBOX_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_SANDBOX_API_SECRET!, // sk_sandbox_*
+  environment: 'non-production',
+});
+
+// Lazy — TxnodClientSandbox constructed on first access.
+const r = await client.sandbox.simulatePaid('01HK8MAR2QEXAMPLE000000000');
+```
+
+**Method surface:**
+
+| Method | HTTP | Returns | Throws |
+|---|---|---|---|
+| `simulateDetect(invoiceId, opts?)` | `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-detect` | `{ event_id, status: 'detected' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `pending`), `TxnodSandboxInvoiceNotFoundError` |
+| `simulatePaid(invoiceId, opts?)` | `POST .../simulate-paid` | `{ event_id, status: 'paid' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `detected`) |
+| `simulateOverpaid(invoiceId, params)` | `POST .../simulate-overpaid` | `{ event_id, status: 'paid' }` | `TxnodSandboxInvoiceTransitionInvalidError` |
+| `simulatePartial(invoiceId, params)` | `POST .../simulate-partial` | `{ event_id, status: 'detected' }` | `TxnodSandboxInvoiceTransitionInvalidError` |
+| `simulateExpire(invoiceId)` | `POST .../simulate-expire` | `{ event_id, status: 'expired' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice already terminal) |
+| `simulateLatePayment(invoiceId, opts?)` | `POST .../simulate-late-payment` | `{ event_id, status: 'expired_paid_late' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `expired`) |
+| `simulateReorg(invoiceId)` | `POST .../simulate-reorg` | `{ event_id, status: 'reverted' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `paid`/`overpaid`/`partial`) |
+| `simulateReconfirm(invoiceId)` | `POST .../simulate-reconfirm` | `{ event_id, status: 'paid' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `reverted`) |
+| `simulateDuplicateDelivery(invoiceId)` | `POST .../simulate-duplicate-delivery` | `{ event_id }` | `TxnodSandboxInvoiceTerminalError` (no terminal event yet) |
+| `simulateEvent(invoiceId, eventInput)` | `POST .../simulate-event` | `{ event_id, status }` | `TxnodSandboxInvoiceTransitionInvalidError` (current status != `expectedCurrentStatus`) |
+| `clockAdvance(projectId, params)` | `POST /api/v1/sandbox/{projectId}/clock/advance` | `{ advanced, remaining }` | `TxnodSandboxRateLimitExceededError` (>10/min/project) |
+| `reset(projectId)` | `POST /api/v1/sandbox/{projectId}/reset` | `{ status: 'reset' }` | `TxnodSandboxResetFailedError` |
+| `destroy(projectId)` | `DELETE /api/v1/sandbox/{projectId}` | `{ status: 'deleted' }` | `TxnodSandboxDeleteFailedError` |
+| `listWallets(projectId)` | `GET /api/v1/sandbox/{projectId}/wallets` | `WalletsListResponse` | (read-only; no transition errors) |
+
+Every `simulate*` and lifecycle method can additionally throw `TxnodSandboxInvoiceNotFoundError` (cross-tenant invoice id), `TxnodSandboxRateLimitExceededError` (per-project caps), and the auth/identity family. The full sandbox error catalogue lives in [`../05-errors.md`](../05-errors.md#sandbox-lifecycle--simulation).
+
+**Result envelope types** (SDK-only — these aren't exported from `@txnod/shared`):
+
+```ts
+interface SandboxSimulateResult {
+  event_id: string | null;                  // outbox row id; null when no webhook is enqueued (e.g. simulateDuplicateDelivery re-emits an existing event)
+  status: string;                           // resulting invoice status — narrowed per-method in the table above
+}
+
+interface SandboxClockAdvanceResult {
+  advanced: number;                         // count of detected→terminal transitions this call performed
+  remaining: number;                        // detected invoices still under threshold after the bump
+}
+
+interface SandboxLifecycleResult {
+  status: 'reset' | 'deleted';              // discriminant for which lifecycle op completed
+}
+```
+
+Each method's worked example lives on its JSDoc — IDE hovers surface the full snippet (e.g. hover `client.sandbox.simulatePaid` to see the imports + a runnable invocation).
+
+---
+
+# `verifyWebhookSignature`
+
+Synchronously verifies an inbound webhook, parses the body, and returns the typed `WebhookEvent`. See [`../04-webhooks.md`](../04-webhooks.md).
+
+**Signature**
+
+```ts
+function verifyWebhookSignature(
+  headers: Headers | Record<string, string> | Record<string, string[]>,
+  rawBody: string,
+  secret: string,
+): WebhookEvent
+```
+
+**Throws** (all are `TxnodError` subclasses):
+
+- `TxnodSignatureFormatError` — header absent or not `t=<int>,v1=<hex>`
+- `TxnodTimestampError` — `|now - t| > 300` seconds; `.skew_seconds` is signed delta
+- `TxnodHmacError` — computed HMAC mismatch
+- `TxnodWebhookPayloadParseError` — HMAC passed but body is not valid JSON; `.cause` carries the underlying `SyntaxError`. Treat as 401-class (do not parse, do not act)
+
+**Example**
+
+```ts
+const event = verifyWebhookSignature(
+  request.headers,
+  await request.text(),
+  process.env.TXNOD_WEBHOOK_SECRET!,
+);
+```
+
+---
+
+# Named exports
+
+Also exported from `@txnod/sdk`:
+
+- `PACKAGE_NAME` — the literal `'@txnod/sdk'`.
+- `SDK_VERSION` — the current version string, in sync with `package.json`.
+- Type re-exports: `Coin`, `Chain`, `Network`, `InvoiceStatus`, `WebhookEvent`, `WebhookEventType` (definitions are fully expanded plain-TypeScript aliases inside this tarball — no `zod`, no `@txnod/*` needed at install or typecheck time). Use them when annotating wrappers around `createInvoice` / `searchInvoices` so the union literals stay in sync with the SDK.
+- `verifyAddress(input)` and the corresponding `VerifyAddressInput` / `VerificationResult` types — invoked automatically by `createInvoice` when the matching `TXNOD_<chain>_XPUB` env var is set, but exported so partners can run the same check on a stored invoice off-flow.
+- `AddressVerificationError` — thrown by `verifyAddress` (and by `createInvoice` post-response) on mismatch. Not a `TxnodError` subclass; carries `expected_address` / `derived_address`.
+- Every `Txnod*` error class — see [`errors.md`](./errors.md).

package/docs/reference/errors.md

@@ -0,0 +1,161 @@
+---
+title: "Error class catalogue"
+description: "Complete error_code → class lookup and the narrative groups."
+sdk_version: 1.0.0
+---
+
+# Error class catalogue
+
+All classes extend `TxnodError` and are exported from `@txnod/sdk`. The base class carries `error_code`, `status`, `request_id`, and the full RFC 7807 `raw` envelope. See [`../05-errors.md`](../05-errors.md) for usage patterns.
+
+## `error_code` → class
+
+The 55-row lookup below covers every server-emitted code in `ERROR_CODES` (58 entries, see [`packages/shared/src/errors/error-codes.ts`](../../../shared/src/errors/error-codes.ts)) that the SDK can surface. Three server-only auth codes (`otp_expired` / `otp_used` / `invite_invalid`) are intentionally not mapped — they only fire from dashboard auth/invite routes that no `TxnodClient` method can reach. If a server bug leaks one of those, `parseProblemDetails` falls through to a generic `TxnodError` via the `degraded()` branch.
+
+### Validation / config
+
+| `error_code` | Class | HTTP status | Notes |
+|---|---|---|---|
+| `validation_error` | `TxnodValidationError` | 400 | `err.raw.errors` carries per-field issues |
+| `invalid_coin` | `TxnodInvalidCoinError` | 400 | |
+| `invalid_xpub_format` | `TxnodInvalidXpubFormatError` | 400 | |
+| `invalid_webhook_url` | `TxnodInvalidWebhookUrlError` | 400 | |
+| `coin_not_enabled` | `TxnodCoinNotEnabledError` | 422 | Check enabled coins via `getRates()` |
+| `amount_out_of_range` | `TxnodAmountOutOfRangeError` | 422 | Respect project min/max |
+| `xpub_not_verified` | `TxnodXpubNotVerifiedError` | 409 | Complete verification challenge first |
+| `invoice_not_cancellable` | `TxnodInvoiceNotCancellableError` | 409 | |
+| `invalid_state_transition` | `TxnodInvalidStateTransitionError` | 409 | |
+
+### Auth / identity
+
+| `error_code` | Class | HTTP status | Notes |
+|---|---|---|---|
+| `auth_invalid` | `TxnodAuthInvalidError` | 401 | Missing / wrong headers |
+| `signature_invalid` | `TxnodSignatureInvalidError` | 401 | HMAC mismatch |
+| `signature_replayed` | `TxnodSignatureReplayedError` | 401 | Same `(timestamp, signature)` seen before — caller must mint a fresh nonce per attempt |
+| `timestamp_out_of_window` | `TxnodTimestampOutOfWindowError` | 401 | Fix NTP |
+| `key_suspended` | `TxnodKeySuspendedError` | 403 | Operator action |
+| `key_revoked` | `TxnodKeyRevokedError` | 403 | Rotate to new key |
+| `project_suspended` | `TxnodProjectSuspendedError` | 403 | Operator action |
+| `permission_denied` | `TxnodPermissionDeniedError` | 403 | Missing capability |
+| `subscription_expired` | `TxnodSubscriptionExpiredError` | 402 | Operator subscription not `active`; writes blocked. Renew via dashboard `/billing` |
+
+### Not found
+
+| `error_code` | Class | HTTP status | Notes |
+|---|---|---|---|
+| `invoice_not_found` | `TxnodInvoiceNotFoundError` | 404 | |
+| `project_not_found` | `TxnodProjectNotFoundError` | 404 | |
+| `wallet_not_found` | `TxnodWalletNotFoundError` | 404 | |
+| `orphan_not_found` | `TxnodOrphanNotFoundError` | 404 | |
+| `event_not_found` | `TxnodEventNotFoundError` | 404 | |
+
+### Conflict / idempotent
+
+| `error_code` | Class | HTTP status | Notes |
+|---|---|---|---|
+| `external_id_conflict` | `TxnodExternalIdConflictError` | 409 | **Idempotent** — fetch existing |
+| `orphan_already_attributed` | `TxnodOrphanAlreadyAttributedError` | 409 | **Idempotent** — treat as success |
+| `wallet_not_bound` | `TxnodWalletNotBoundError` | 422 | Operator must bind a verified wallet of matching kind for the requested chain before invoice creation succeeds |
+| `wallet_not_owned` | `TxnodWalletNotOwnedError` | 403 | **Dashboard-only** — never reaches partner API |
+| `wallet_has_active_bindings` | `TxnodWalletHasActiveBindingsError` | 409 | **Dashboard-only** — never reaches partner API |
+| `wallet_kind_mismatch` | `TxnodWalletKindMismatchError` | 422 | **Dashboard-only** — cross-kind bind attempt blocked |
+
+### Chain-runtime — TRON / TON
+
+| `error_code` | Class | HTTP status | Notes |
+|---|---|---|---|
+| `tron_no_activated_addresses_available` | `TxnodTronNoActivatedAddressesError` | 422 | TRON pool has zero activated rows; `.walletId` carries the operator wallet id. Operator-action-required |
+| `ton_operator_wallet_not_deployed` | `TxnodTonOperatorWalletNotDeployedError` | 422 | TON operator wallet has not been broadcast on-chain yet — operator must perform the first send to deploy `StateInit` |
+| `ton_invalid_wallet_version` | `TxnodTonInvalidWalletVersionError` | 422 | Configured `TXNOD_TON_WALLET_VERSION` does not match the deployed wallet contract |
+| `ton_jetton_resolve_failed` | `TxnodTonJettonResolveFailedError` | 503 | Toncenter/TONAPI hiccup resolving the jetton master/wallet pair — retry with backoff |
+| `ton_comment_parse_failed` | `TxnodTonCommentParseFailedError` | 422 | Inbound TON tx carried a malformed `payment_token` comment |
+
+### TonConnect (operator-onboarding)
+
+These never reach partner methods — they fire on the operator's TonConnect signing flow during xpub onboarding. Exported so the dashboard's typed-error catch can branch correctly.
+
+| `error_code` | Class | HTTP status | Notes |
+|---|---|---|---|
+| `tonconnect_payload_expired` | `TxnodTonConnectPayloadExpiredError` | 400 | Challenge payload signed past TTL |
+| `tonconnect_payload_unknown` | `TxnodTonConnectPayloadUnknownError` | 400 | Replay or stale browser tab |
+| `tonconnect_domain_mismatch` | `TxnodTonConnectDomainMismatchError` | 400 | `proof.domain.value` vs `TXNOD_TONCONNECT_DOMAIN` mismatch |
+| `tonconnect_timestamp_skew` | `TxnodTonConnectTimestampSkewError` | 400 | Wallet clock skew outside window |
+| `tonconnect_unknown_wallet_version` | `TxnodTonConnectUnknownWalletVersionError` | 400 | Unrecognised `walletStateInit` version |
+| `tonconnect_signature_invalid` | `TxnodTonConnectSignatureInvalidError` | 400 | Ed25519 verification failed |
+| `tonconnect_network_mismatch` | `TxnodTonConnectNetworkMismatchError` | 400 | Wallet on `-3` (testnet) vs server-configured mainnet, or vice versa |
+
+### Sandbox (lifecycle + simulation)
+
+Surfaced by `/api/v1/sandbox/*` REST endpoints, the 14 `client.sandbox.*` SDK methods, and the `sandbox:simulate`-scoped MCP tools.
+
+| `error_code` | Class | HTTP status | Notes |
+|---|---|---|---|
+| `sandbox_project_required` | `TxnodSandboxProjectRequiredError` | 403 | Sandbox endpoint hit against a `kind: 'production'` project |
+| `sandbox_per_operator_cap_reached` | `TxnodSandboxPerOperatorCapReachedError` | 422 | Operator at the per-operator sandbox-project cap |
+| `sandbox_key_against_production_project` | `TxnodSandboxKeyAgainstProductionProjectError` | 400 | `sk_sandbox_` secret used against a production project |
+| `production_key_against_sandbox_project` | `TxnodProductionKeyAgainstSandboxProjectError` | 400 | Production secret used against a sandbox project |
+| `sandbox_provisioning_failed` | `TxnodSandboxProvisioningFailedError` | 500 | Server failed to provision the sandbox shell — retry |
+| `sandbox_invoice_transition_invalid` | `TxnodSandboxInvoiceTransitionInvalidError` | 422 | `simulate*` against an invoice in a state that disallows the transition |
+| `sandbox_invoice_not_found` | `TxnodSandboxInvoiceNotFoundError` | 404 | Sandbox invoice not in this sandbox project (oracle-safe across miss reasons) |
+| `sandbox_invoice_terminal` | `TxnodSandboxInvoiceTerminalError` | 422 | `simulateDuplicateDelivery` requires a prior terminal webhook |
+| `sandbox_rate_limit_exceeded` | `TxnodSandboxRateLimitExceededError` | 429 | Per-project sandbox cap hit (e.g. `clockAdvance` ≤ 10/min) |
+| `sandbox_reset_failed` | `TxnodSandboxResetFailedError` | 500 | `client.sandbox.reset` failed mid-purge — retry |
+| `sandbox_delete_failed` | `TxnodSandboxDeleteFailedError` | 500 | `client.sandbox.destroy` failed mid-delete — retry |
+| `sandbox_active_invoice_cap_reached` | `TxnodSandboxActiveInvoiceCapReachedError` | 422 | Sandbox project has too many concurrently-open invoices — finalise or expire some first |
+
+### Transient
+
+| `error_code` | Class | HTTP status | Notes |
+|---|---|---|---|
+| `rate_limit_exceeded` | `TxnodRateLimitError` | 429 | `.retry_after_seconds` |
+| `pool_exhausted` | `TxnodPoolExhaustedError` | 503 | `.retry_after_seconds` — hard-cap hit, wait for cooldown |
+| `webhook_capacity_exhausted` | `TxnodWebhookCapacityExhaustedError` | 503 | `.retry_after_seconds` always `0` — partner retry alone won't free capacity, treat as transient outage |
+| `internal_error` | `TxnodServerError` | 5xx | Log `request_id`, retryable |
+
+### SDK-local synthesised (no `error_code` — init-time / verify-time guards)
+
+These have no `error_code` in the runtime `CODE_TO_CTOR` map — they synthesise a `ProblemDetails` envelope locally so the `instanceof TxnodError` invariant holds. Catch them around `new TxnodClient(...)`, `parseXpubConfig(...)`, and `verifyWebhookSignature(...)`.
+
+The `Synthetic status` column carries a representative HTTP code so the envelope shape stays uniform with server-emitted errors — no HTTP exchange actually happens for the init-time classes (they fire before any request leaves the process); for the verify-time webhook trio, 401 reflects the canonical "treat as unauthenticated" disposition partners should map them to.
+
+| Class | `kind` | Synthetic status | When |
+|---|---|---|---|
+| `TxnodSignatureFormatError` | `signature_format` | 401 | `verifyWebhookSignature` — header missing or not `t=<int>,v1=<hex>` |
+| `TxnodHmacError` | `hmac` | 401 | `verifyWebhookSignature` — computed HMAC mismatch |
+| `TxnodTimestampError` | `timestamp` | 401 | `verifyWebhookSignature` — `\|now − t\| > 300`; `.skew_seconds` exposes signed delta |
+| `TxnodWebhookPayloadParseError` | `webhook_payload_parse` | 401 | `verifyWebhookSignature` — HMAC passed but body is not valid JSON; `.cause` is the underlying `SyntaxError` |
+| `TxnodSandboxKeyInProductionError` | `sandbox_key_in_production` | 401 | `new TxnodClient(...)` — `sk_sandbox_` secret with `environment: 'production'` (or production-detected `NODE_ENV`); `.signal`, `.secretPrefix`, `.detectedEnvironment` |
+| `TxnodEnvironmentUnknownError` | `environment_unknown` | 401 | `new TxnodClient(...)` — `sk_sandbox_` secret without explicit `environment` and `NODE_ENV` unset/unknown |
+| `TxnodSandboxXpubInProductionError` | `sandbox_xpub_in_production` | 401 | `parseXpubConfig` / `parseTonConfig` — testnet xpub loaded for a chain whose env-detected mode is production; `.chain`, `.xpubPrefix`, `.detectedEnvironment` |
+
+## Fields on specific classes
+
+- `TxnodRateLimitError.retry_after_seconds: number` — value of the `Retry-After` header (0 when absent).
+- `TxnodPoolExhaustedError.retry_after_seconds: number` — value of the `Retry-After` header (0 when absent). Server derives it from the soonest `locked_until` across locked pool rows, falling back to the project's configured cooldown.
+- `TxnodWebhookCapacityExhaustedError.retry_after_seconds: number` — always `0`. The server cannot tell when the operator will add a webhook shard; the actionable signal is the operator-side admin alert raised on every rejection, not partner-side retry timing. `.kind` carries the `error_code` literal; the underlying `chain` is also surfaced in the problem-details body.
+- `TxnodTimestampError.skew_seconds: number` — `now - t`; negative means the webhook timestamp is in the future.
+- `TxnodValidationError.raw.errors` — server-emitted per-field Zod issues.
+- `TxnodTronNoActivatedAddressesError.walletId: string` — operator wallet id (ULID, guaranteed non-empty). The constructor fails fast if the server omits it. Use it to deep-link the operator into `/wallets/{walletId}` for in-dashboard activation.
+
+## Narrative grouping
+
+Grouped by branching strategy in [`../05-errors.md`](../05-errors.md):
+
+- Fatal — fix inputs / configuration
+- Fatal — auth / identity
+- Fatal — not found
+- Idempotent — treat as success
+- Transient — retry
+- TON-chain runtime
+- TonConnect operator-onboarding
+- Sandbox lifecycle + simulation
+- SDK-local synthesised (init-time guards)
+- Dashboard-only (exported but not reachable from `TxnodClient`)
+- Webhook-local (thrown by `verifyWebhookSignature` only)
+
+## Related
+
+- [`../05-errors.md`](../05-errors.md) — branching patterns
+- [`../01-authentication.md`](../01-authentication.md) — auth-family context
+- [`../04-webhooks.md`](../04-webhooks.md) — webhook-local errors