@txnod/sdk 1.0.1

package/AGENTS.md

@@ -0,0 +1,29 @@
+---
+title: "@txnod/sdk — agent entry point"
+description: "How AI coding agents should consume @txnod/sdk documentation shipped inside the npm tarball."
+sdk_version: 1.0.0
+---
+
+# @txnod/sdk — agent entry point
+
+You are looking at an AI-agent-targeted documentation bundle shipped inside the `@txnod/sdk` npm tarball. Everything you need to integrate the SDK correctly is under [`./docs/`](./docs/) as plain markdown with relative links — no network access is required.
+
+## Read order
+
+1. [`./docs/index.md`](./docs/index.md) — full table of contents and 30-second overview.
+2. [`./docs/00-getting-started.md`](./docs/00-getting-started.md) — install, env vars, first invoice, first verified webhook.
+3. The numbered guide that matches the current task (`01-authentication` through `05-sandbox` through `06-idempotency`).
+4. [`./docs/reference/client.md`](./docs/reference/client.md) — exact signature of every `TxnodClient` method.
+
+## Non-negotiable invariants
+
+- **Never pass a private key, mnemonic, seed, or signing material to anything in this package.** The SDK is non-custodial by construction. `apiSecret` is an HMAC secret, not a wallet key.
+- **Always verify inbound webhooks with [`verifyWebhookSignature`](./docs/04-webhooks.md).** Never parse `req.body` before verification succeeds.
+- **Treat every webhook as idempotent by `event_id`.** See [`./docs/06-idempotency.md`](./docs/06-idempotency.md).
+- **Never hardcode `baseUrl`.** Omit it (defaults to `https://txnod.com`), or read from `TXNOD_BASE_URL` when overriding. Override is only warranted for a staging deployment or when pointing at a self-hosted TxNod-compatible API — the scheme is endpoint-agnostic, so the SDK works unchanged against any origin.
+
+## What is authoritative
+
+- **This bundle is frozen at the SDK version printed in the front-matter (`sdk_version`).** It matches the installed package exactly — no drift with a remote docs site.
+- **Source of truth for types** is the TypeScript declarations in [`./dist/index.d.ts`](./dist/index.d.ts) (shipped alongside these docs). When markdown and `.d.ts` disagree, trust `.d.ts` and flag the discrepancy.
+- **Link format.** All cross-references inside `./docs/` are relative `.md` paths so they resolve identically in the editor, on GitHub, and from `node_modules/@txnod/sdk/docs/` at runtime.

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `@txnod/sdk` are documented here. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.1] - 2026-05-05
+
+Initial public release of `@txnod/sdk` — the official TypeScript client for the txnod non-custodial crypto payment gateway.
+
+This release ships the complete partner-integration surface for the seven supported chains (BTC, ETH +ERC-20 USDT/USDC, TRON +TRC-20 USDT, Cardano, Polygon PoS +POL +Polygon USDT/USDC, BNB Smart Chain +BNB +BEP-20 USDT/USDC, TON +jetton USDT):
+
+- `TxnodClient` — fully typed REST client covering invoice lifecycle (`create`, `get`, `cancel`, `list`), project introspection, and the `client.sandbox.*` namespace for deterministic integration testing without on-chain spend.
+- `verifyWebhookSignature` — constant-time HMAC verifier for inbound `txnod-signature` webhook deliveries. Verify before parsing.
+- `verifyAddress` — automatic per-invoice address verification against the operator's xpub-derived path; throws `AddressVerificationError` on mismatch. Includes `verifyTonAddress` for TON's single-wallet-per-project shape.
+- `Txnod*Error` family — typed exceptions for every server `error_code`, including `TxnodWalletKindMismatchError` (HTTP 422, raised when a wallet's `kind` doesn't match its project's `kind`), `TxnodWalletNotBoundError` (HTTP 422, raised when the project has no verified wallet bound for the invoice's chain), and `TxnodWebhookCapacityExhaustedError` (HTTP 503, raised when the chain's webhook fleet has no spare slots — `retry_after_seconds` is `0` because partner retry alone won't free capacity; treat as a transient outage).
+- Project / wallet `kind` discriminator — `'production' | 'testnet' | 'sandbox'`; cross-kind binding is rejected server-side. `WalletEdgeKind` (`'production' | 'testnet'`) is the type used at the kind→network edge (TonConnect, BIP32 derivation, provider URL selection).
+- Webhook envelope `mode` field — `'production' | 'testnet' | 'sandbox'`. Branch on `event.mode` to route sandbox / testnet events away from production billing logic.
+- **Zero peer dependencies and zero `@txnod/*` runtime coupling.** The 6 runtime deps are pure crypto primitives (`@noble/curves`, `@noble/ed25519`, `@noble/hashes`, `@scure/base`, `@scure/bip32`) and `pino` — all enforced by the [`packages/sdk/.dep-allowlist.json`](.dep-allowlist.json) audit gate; no transitive deps. All shared types are pre-expanded into `dist/_shared/index.d.ts` at build time, so the SDK works alongside any version of zod (v3, v4, v5+) — or with no zod installed at all.
+- Bundled `AGENTS.md` + `docs/` documentation pack inside the tarball — discoverable by AI coding agents at `node_modules/@txnod/sdk/`.
+
+Install: `npm install @txnod/sdk`. Quickstart: see the README on this package's npm page.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TxNod <support@txnod.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,434 @@
+# @txnod/sdk
+
+Fully-typed REST client and webhook verifier for [TxNod](https://txnod.com) — a non-custodial crypto payment gateway. Zero cryptocurrency runtime dependencies, automatic HMAC signing on every API call, RFC 7807 → typed error mapping covering every server `error_code`, and a `verifyWebhookSignature` helper with a ±300-second timestamp window. Pure Node ≥ 20 — runs unchanged in Express, Fastify, Hono, Koa, NestJS, plain `node:http`, Next.js (App Router or Pages), Nuxt, SvelteKit, Remix, Astro endpoints, or any other server-side framework. Production and testnet are both supported end-to-end, including SDK-side address verification — pick at project-create time, never per-invoice.
+
+## Install
+
+```bash
+npm install @txnod/sdk
+pnpm add @txnod/sdk
+yarn add @txnod/sdk
+bun add @txnod/sdk
+```
+
+Node ≥ 20 is required. Zero runtime and zero peer dependencies — `@txnod/sdk` is the only package you install. Types are fully expanded to plain TypeScript in the published tarball, so the SDK is compatible with any zod version your project uses (or no zod at all).
+
+## Environment setup
+
+```bash
+# .env.local
+TXNOD_PROJECT_ID=01JXXXXXXXXXXXXXXXXXXXXXXX
+TXNOD_API_SECRET=<64-hex-character API secret>
+TXNOD_WEBHOOK_SECRET=<same as TXNOD_API_SECRET — see docs>
+
+# Optional — defaults to https://txnod.com.
+# TXNOD_BASE_URL=https://pay.mycompany.com
+```
+
+The operator generates the project id and API secret in the TxNod dashboard ([API Keys → Generate](https://docs.txnod.com/dashboard/api-keys)). The secret is shown exactly once — copy it into your secrets manager immediately. The webhook secret is the same value as the API secret; the dashboard surfaces both names so partners can wire two distinct env vars without re-deriving the relationship.
+
+`TXNOD_BASE_URL` is only needed when targeting a non-default origin — a staging deployment, or a self-hosted txnod-compatible gateway. The SDK's HMAC scheme, retry logic, and webhook verifier are endpoint-agnostic.
+
+## Testing without a real wallet — sandbox mode
+
+Sandbox projects work end-to-end without on-chain interaction: create one in the dashboard, drive `client.sandbox.simulate*` to walk the state machine, and your webhook handler receives real signed events with `mode: 'sandbox'`. The SDK surface is documented in `docs/05-sandbox.md` (bundled in this tarball at `node_modules/@txnod/sdk/docs/05-sandbox.md`); an end-to-end Vitest harness covering all seven webhook event types is at `docs/examples/sandbox-vitest-suite.md`.
+
+## Supported coins
+
+Operators enable coins per-project in the TxNod dashboard; a single `TxnodClient` instance can create invoices for any enabled coin — no SDK-level coin-capability toggle. The `coin` value passed to `createInvoice` must be one of the 15 literals below.
+
+| Coin enum | Chain | Description |
+|---|---|---|
+| `btc` | `btc` | Bitcoin native (BTC). |
+| `eth` | `eth` | Ethereum native (ETH). |
+| `usdt_erc20` | `eth` | Tether USD, ERC-20 on Ethereum. |
+| `usdc_erc20` | `eth` | USD Coin, ERC-20 on Ethereum. |
+| `trx` | `tron` | TRON native (TRX). |
+| `usdt_trc20` | `tron` | Tether USD, TRC-20 on TRON. |
+| `ada` | `ada` | Cardano native (ADA). |
+| `pol` | `polygon` | Polygon PoS native (POL). |
+| `usdt_polygon` | `polygon` | Tether USD, ERC-20 on Polygon PoS. |
+| `usdc_polygon` | `polygon` | USD Coin, ERC-20 on Polygon PoS. |
+| `bnb` | `bsc` | BNB Smart Chain native (BNB). |
+| `usdt_bep20` | `bsc` | Tether USD, BEP-20 on BNB Smart Chain. |
+| `usdc_bep20` | `bsc` | USD Coin, BEP-20 on BNB Smart Chain. |
+| `ton` | `ton` | TON native (Toncoin). |
+| `usdt_ton` | `ton` | Tether USD jetton on TON. |
+
+## SDK-side address verification (`TXNOD_<chain>_XPUB`)
+
+When the matching env var is set, `createInvoice` automatically derives the expected deposit address from the operator's xpub at the invoice's `derivation_path` and rejects with `AddressVerificationError` on mismatch. This is the SDK's defense against a compromised gateway silently swapping the deposit address. Set per chain you accept; omit to skip verification on that chain.
+
+| Chain | Env var | Format |
+|---|---|---|
+| BTC | `TXNOD_BTC_XPUB` | `zpub` (mainnet) / `vpub`/`tpub` (testnet) |
+| ETH + ERC-20 | `TXNOD_ETH_XPUB` | `xpub` (mainnet) / `tpub` (testnet) |
+| TRON | `TXNOD_TRON_XPUB` | `xpub` / `tpub` |
+| Cardano | `TXNOD_CARDANO_ACCOUNT_PUBKEY` | CIP-5 `acct_xvk` bech32 |
+| Polygon PoS | `TXNOD_POLYGON_XPUB` | `xpub` / `tpub` |
+| BNB Smart Chain | `TXNOD_BNB_XPUB` | `xpub` / `tpub` |
+| TON | `TXNOD_TON_PUBKEY` (+ siblings) | 64-hex Ed25519 pubkey — see below |
+
+> **Hardware-wallet users (Ledger or Trezor):** ETH, Polygon PoS, and BNB Smart Chain share BIP-44 `coin_type 60`. One device account → one xpub → set the same value on all three env vars (`TXNOD_ETH_XPUB`, `TXNOD_POLYGON_XPUB`, `TXNOD_BNB_XPUB`). The wizard's "EVM" hint mirrors this; the SDK's per-chain address derivation differs in chain-id only. (TRON and TON are Ledger-only on the hardware-wallet side — Trezor doesn't speak either chain. Cardano via Trezor requires Model T or newer.)
+
+Each xpub env var accepts three formats:
+
+- **Single xpub** — the most common case: `TXNOD_BTC_XPUB=zpub6r…`.
+- **CSV (newest-first)** — for wallet rotations where multiple xpubs must be accepted in parallel: `TXNOD_BTC_XPUB=zpub6_new,zpub6_old`. Verification iterates newest-first and accepts on the first match; an `AddressVerificationError` is raised only when *every* configured xpub fails to derive the address.
+- **JSON array** — equivalent to CSV when you prefer explicit shape: `TXNOD_BTC_XPUB=["zpub6_new","zpub6_old"]`.
+
+For TON the operator's wallet has no HD derivation — the address is fully determined by `(walletPublicKey, walletVersion, subwalletId, workchain)`. Configure via four env vars (defaults match a stock Ledger TON setup):
+
+| Env var | Required | Default |
+|---|---|---|
+| `TXNOD_TON_PUBKEY` | yes (enables auto-verify) | — |
+| `TXNOD_TON_WALLET_VERSION` | no | `v4R2` (allowed: `v3R2`, `v4R2`, `v5R1`) |
+| `TXNOD_TON_SUBWALLET_ID` | no | `698983191` (standard for v3R2/v4R2) |
+| `TXNOD_TON_WORKCHAIN` | no | `0` (basechain; allowed: `0`, `-1`) |
+
+The pubkey is the 32-byte Ed25519 public key the operator's wallet device exports — the same value Ledger Live, Tonkeeper, etc. expose under "show recovery key" / "wallet pubkey". **Never the secret key.** When `TXNOD_TON_PUBKEY` is unset, TON verification is skipped silently — the SDK will emit one `warn` line per unverified TON invoice so operators do not silently coast on server trust.
+
+Wallet rotations: after changing the env value in a long-lived process, call `client.refreshXpubConfig()` to pick up the new values without restarting.
+
+### TRON requires per-address activation
+
+TRON is the only chain in the list that charges the recipient to "activate" each fresh address before it can hold balance. TxNod's operator dashboard handles activation on the operator side; partners do nothing extra. The only partner-visible artifact is a single typed error: when an operator's TRON address pool has zero activated rows at invoice creation time, `createInvoice({ coin: 'trx' | 'usdt_trc20' })` raises `TxnodTronNoActivatedAddressesError`. The error's `walletId` field carries the operator wallet id — surface a "your operator has not finished TRON wallet setup" message and do not auto-retry; the operator must activate addresses through the dashboard before TRON invoices succeed. The canonical handler example is in `docs/02-invoices.md` (bundled in this tarball).
+
+### TON: payment-token matching
+
+TON is a memo chain — every TON invoice shares the operator's single deposit address and is disambiguated by an 8-hex `payment_token` placed in the on-chain transaction comment. `createInvoice({ coin: 'ton' | 'usdt_ton' })` returns the token alongside the deposit address:
+
+```ts
+import { TxnodClient } from '@txnod/sdk';
+
+declare const client: TxnodClient;
+// `qrcode` is partner-installed; the SDK does not depend on it.
+declare const qrcode: { toDataURL: (input: string) => Promise<string> };
+
+const invoice = await client.createInvoice({
+  amount_usd: 5,
+  coin: 'ton',
+  external_id: 'order-ton-1',
+});
+// invoice.payment_token === 'a1b2c3d4'  (8 lowercase hex chars)
+// invoice.payment_uri   === 'ton://transfer/UQ.../?amount=5000000000&text=a1b2c3d4'
+
+// Render the URI as a QR code on the checkout page:
+const dataUrl: string = await qrcode.toDataURL(invoice.payment_uri);
+```
+
+The wallet apps (Tonkeeper, MyTonWallet, Ledger Live) auto-fill the `payment_token` into the comment field when the user follows the URI or scans the QR — no manual paste required. **If the user types the address into a wallet by hand and forgets the comment, the deposit lands on the operator's wallet but cannot be matched to the invoice.** Such deposits surface in the operator dashboard's "Unattributed deposits" view rather than as `invoice.paid` webhooks. Surface a "scan the QR or copy the entire `payment_uri`" instruction at checkout to keep this rare. For HD chains (BTC / ETH / TRON / ADA / Polygon / BSC), `invoice.payment_token` is always `null`.
+
+## Quickstart — create an invoice
+
+A complete `app/api/checkout/route.ts` against the Next.js App Router:
+
+```ts
+import { randomUUID } from 'node:crypto';
+import { TxnodClient, TxnodCoinNotEnabledError, TxnodError } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+  // baseUrl defaults to 'https://txnod.com'. Override for a self-hosted or
+  // staging deployment (see TXNOD_BASE_URL above):
+  ...(process.env.TXNOD_BASE_URL ? { baseUrl: process.env.TXNOD_BASE_URL } : {}),
+});
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const invoice = await client.createInvoice({
+      amount_usd: 9.99,
+      coin: 'usdt_trc20',
+      external_id: randomUUID(),
+      callback_url: new URL('/api/txnod-webhook', request.url).toString(),
+    });
+    return Response.json({
+      invoice_id: invoice.id,
+      pay_to: invoice.address,
+      amount_crypto: invoice.amount_crypto,
+      payment_uri: invoice.payment_uri,
+      expires_at: invoice.expires_at,
+    });
+  } catch (err) {
+    if (err instanceof TxnodCoinNotEnabledError) {
+      return Response.json(
+        { error: 'coin_not_enabled', request_id: err.request_id },
+        { status: 422 },
+      );
+    }
+    if (err instanceof TxnodError) {
+      return Response.json(
+        { error: err.error_code, request_id: err.request_id },
+        { status: err.status },
+      );
+    }
+    throw err;
+  }
+}
+```
+
+## Quickstart — verify a webhook
+
+A complete `app/api/txnod-webhook/route.ts` that validates the inbound HMAC and narrows the typed event:
+
+```ts
+import {
+  verifyWebhookSignature,
+  TxnodHmacError,
+  TxnodTimestampError,
+} from '@txnod/sdk';
+
+export async function POST(request: Request): Promise<Response> {
+  const rawBody = await request.text();
+  try {
+    const event = verifyWebhookSignature(
+      request.headers,
+      rawBody,
+      process.env.TXNOD_WEBHOOK_SECRET!,
+    );
+    if (event.event_type === 'invoice.paid') {
+      // event.data is fully typed under the `invoice.paid` discriminant.
+      console.log('paid invoice', event.data.invoice_id, 'at', event.created_at_iso);
+    }
+    return Response.json({ ok: true });
+  } catch (err) {
+    if (err instanceof TxnodHmacError) {
+      return new Response('bad signature', { status: 401 });
+    }
+    if (err instanceof TxnodTimestampError) {
+      console.warn('clock skew', err.skew_seconds);
+      return new Response('stale signature', { status: 401 });
+    }
+    throw err;
+  }
+}
+```
+
+## Polygon PoS — create and verify (usdt_polygon)
+
+Polygon PoS invoices settle after 128 blocks — the Heimdall checkpoint depth at which the SDK marks an `invoice.paid` event terminal. The snippet below creates a USDT-Polygon invoice and, in the webhook route, matches the inbound `invoice.paid` event against the invoice id.
+
+```ts
+import { randomUUID } from 'node:crypto';
+import { TxnodClient, verifyWebhookSignature, TxnodError } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+});
+
+const invoice = await client.createInvoice({
+  amount_usd: 25.0,
+  coin: 'usdt_polygon',
+  external_id: randomUUID(),
+  callback_url: 'https://my-site.com/api/txnod-webhook',
+});
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const event = verifyWebhookSignature(request.headers, await request.text(), process.env.TXNOD_WEBHOOK_SECRET!);
+    if (event.event_type === 'invoice.paid' && event.data.invoice_id === invoice.id) {
+      console.log('Polygon USDT payment confirmed after 128 blocks.');
+    }
+    return Response.json({ ok: true });
+  } catch (err) {
+    if (err instanceof TxnodError) console.error(err.error_code, err.request_id);
+    throw err;
+  }
+}
+```
+
+## BNB Smart Chain — create and verify (usdc_bep20)
+
+BNB Smart Chain invoices settle after 15 blocks (BEP-126 fast-finality plus the Binance deposit convention). Note the **18-decimal trap**: `usdt_bep20` and `usdc_bep20` use 18 decimals on-chain, unlike their 6-decimal ETH / Polygon / TRON counterparts — `invoice.amount_crypto` already reflects this, so render it verbatim rather than re-scaling it.
+
+```ts
+import { randomUUID } from 'node:crypto';
+import { TxnodClient, verifyWebhookSignature, TxnodError } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+});
+
+const invoice = await client.createInvoice({
+  amount_usd: 25.0,
+  coin: 'usdc_bep20',
+  external_id: randomUUID(),
+  callback_url: 'https://my-site.com/api/txnod-webhook',
+});
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const event = verifyWebhookSignature(request.headers, await request.text(), process.env.TXNOD_WEBHOOK_SECRET!);
+    if (event.event_type === 'invoice.paid' && event.data.invoice_id === invoice.id) {
+      console.log('BSC USDC payment confirmed after 15 blocks.');
+    }
+    return Response.json({ ok: true });
+  } catch (err) {
+    if (err instanceof TxnodError) console.error(err.error_code, err.request_id);
+    throw err;
+  }
+}
+```
+
+## Testnet — staging integrations
+
+The kind discriminator (`'production' | 'testnet'`) is fixed at **project create time** on the dashboard, not per-invoice. Each project is bound to one kind for its entire lifetime; the SDK call site does not change between production and testnet — it is the project credential (`projectId` / `apiSecret`) that selects the chain network. To run a staging integration, create a separate testnet-kind project on the dashboard and use that project's secrets in your staging environment.
+
+```ts
+import { TxnodClient } from '@txnod/sdk';
+
+// Same SDK code path. The kind is implied by the testnet project credential.
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_TESTNET_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_TESTNET_API_SECRET!,
+});
+
+const invoice = await client.createInvoice({
+  amount_usd: 5.0,
+  coin: 'btc',
+  external_id: 'staging-order-1',
+  callback_url: 'https://staging.example.com/api/txnod-webhook',
+});
+// The webhook envelope's `mode` field carries 'testnet' for events
+// emitted from a testnet-kind project — branch on it if your handler
+// processes both staging and production traffic from one webhook URL.
+```
+
+The matching operator wallet on the dashboard side must be registered with the **testnet** kind (testnet-prefix xpub: `tpub`/`vpub`/`zpub` for BTC, `tpub` for ETH/Polygon/BSC/TRON, `addr_test1...` stake for Cardano). Cross-kind binding (production wallet → testnet project, or vice versa) is rejected by the server with a typed `wallet_kind_mismatch` (HTTP 422) error. Address verification on the SDK side accepts each kind's prefixes for the matching project — no flag, no separate setup. Use a testnet faucet to fund the deposit address; everything else (webhooks, finalization thresholds, idempotency) behaves the same as production, just on testnet confirmations.
+
+## Operator-side errors your code MUST handle
+
+Two classes of failure are caused by the operator's side, not the partner's. They cannot be auto-retried; surface them as a structured "checkout temporarily unavailable" state and notify the operator out-of-band.
+
+| Class | When | Recovery |
+|---|---|---|
+| `TxnodSubscriptionExpiredError` (HTTP 402) | Operator's TxNod subscription is not `active` — writes (createInvoice, cancelInvoice, attribute) are blocked. Reads keep working | Operator renews via dashboard `/billing`. Do NOT retry |
+| `TxnodTronNoActivatedAddressesError` (HTTP 422) | TRON-only: operator's address pool has zero activated rows | Operator activates from dashboard. Do NOT retry. `.walletId` field carries the operator wallet id for deep-link UX |
+
+```ts
+import {
+  TxnodClient,
+  TxnodSubscriptionExpiredError,
+  TxnodTronNoActivatedAddressesError,
+} from '@txnod/sdk';
+
+declare const client: TxnodClient;
+
+export async function POST(_request: Request): Promise<Response> {
+  try {
+    await client.createInvoice({
+      external_id: 'order-1',
+      coin: 'usdt_trc20',
+      amount_usd: 9.99,
+    });
+    return Response.json({ ok: true });
+  } catch (err) {
+    if (err instanceof TxnodSubscriptionExpiredError) {
+      return Response.json({ error: 'gateway_unavailable_billing' }, { status: 503 });
+    }
+    if (err instanceof TxnodTronNoActivatedAddressesError) {
+      return Response.json(
+        { error: 'gateway_unavailable_tron', wallet_id: err.walletId },
+        { status: 503 },
+      );
+    }
+    throw err;
+  }
+}
+```
+
+## Client tuning options
+
+```ts
+import { TxnodClient } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+  // Per-attempt HTTP timeout (default 30 s). Aborts via AbortSignal.timeout —
+  // protects against a hung upstream that would otherwise stall your request.
+  requestTimeoutMs: 15_000,
+  // Hard cap on response body size (default 1 MiB). Over-cap responses are
+  // surfaced as a typed 502 — the SDK never buffers an unbounded body.
+  maxResponseBytes: 256 * 1024,
+  // Per-attempt observer. One entry per HTTP call (success and each retry).
+  // Errors thrown from the logger are swallowed.
+  requestLogger: (e) => {
+    console.log('txnod', e.method, e.path, e.status, `${e.durationMs}ms`, e.requestId);
+  },
+});
+console.log(client.lastRequestId);
+```
+
+`TXNOD_SDK_LOG_LEVEL` controls the SDK's internal pino logger (default `warn`). Set to `info`/`debug` for more verbose internals. The logger redacts `xpub` and `apiSecret` keys.
+
+## Idempotent invoice creation — `createOrGetInvoice`
+
+If your checkout flow may retry the same `external_id` (network glitch, queue at-least-once delivery), `createOrGetInvoice` collapses the "create-then-conflict-then-search" pattern into one call:
+
+```ts
+import { TxnodClient } from '@txnod/sdk';
+
+declare const client: TxnodClient;
+
+const invoice = await client.createOrGetInvoice({
+  external_id: 'order-42',
+  coin: 'usdt_trc20',
+  amount_usd: 9.99,
+  callback_url: 'https://your-site.com/api/txnod-webhook',
+});
+// On TxnodExternalIdConflictError, the SDK fetches the pre-existing invoice
+// via searchInvoices({ external_id }) and returns it. Same return shape.
+console.log(invoice.id);
+```
+
+Use the underlying `createInvoice` if you need the `external_id_conflict` error to bubble up — for example to distinguish first-create from retried-create in your audit log.
+
+## Error handling
+
+Every method on `TxnodClient` throws a subclass of `TxnodError` on a non-2xx response. The base class carries `error_code`, `status`, `request_id`, and the raw RFC 7807 envelope as `raw`. The SDK ships a typed subclass for every server `error_code` (full table in `docs/reference/errors.md`, bundled in this tarball); the four most operationally useful are shown below.
+
+```ts
+import {
+  TxnodAuthInvalidError,
+  TxnodError,
+  TxnodPoolExhaustedError,
+  TxnodRateLimitError,
+  TxnodValidationError,
+} from '@txnod/sdk';
+
+export async function safeCreateInvoice(create: () => Promise<unknown>): Promise<unknown> {
+  try {
+    return await create();
+  } catch (err) {
+    if (
+      err instanceof TxnodRateLimitError ||
+      err instanceof TxnodPoolExhaustedError
+    ) {
+      await new Promise((r) => setTimeout(r, err.retry_after_seconds * 1000));
+      return await create();
+    }
+    if (err instanceof TxnodValidationError) {
+      console.warn('validation failed', err.raw.errors);
+      throw err;
+    }
+    if (err instanceof TxnodAuthInvalidError) {
+      throw new Error('Re-check TXNOD_PROJECT_ID and TXNOD_API_SECRET.');
+    }
+    if (err instanceof TxnodError) {
+      console.error(err.error_code, err.request_id, err.status);
+    }
+    throw err;
+  }
+}
+```
+
+The IDE-hover JSDoc on each error class — visible in any TypeScript-aware editor — is the canonical reference. The full error matrix is documented at [docs.txnod.com/api](https://docs.txnod.com/api).
+
+## Links
+
+- Documentation: <https://docs.txnod.com/>
+- API reference: <https://docs.txnod.com/api>

package/dist/_shared/index.d.ts

@@ -0,0 +1,68 @@
+// Auto-generated by scripts/bundle-shared-types.mjs — do not edit.
+// Fully-expanded plain TypeScript types for @txnod/sdk.
+// No zod / drizzle / @txnod/* references — safe for ANY consumer
+// regardless of what zod (or other internal deps) they already have.
+
+export type InvoiceStatus = "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled";
+
+export type InvoiceCreateRequest = { external_id: string; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; amount_usd?: number | undefined; amount_crypto?: string | undefined; callback_url?: string | undefined; metadata?: Record<string, unknown> | undefined; };
+
+export type InvoiceResponse = { id: string; project_id: string; external_id: string; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; address: string; amount_crypto: string; amount_crypto_units: string; amount_usd: number | null; rate_snapshot: { rate: string; source: "coingecko"; quoted_at: string; rate_is_stale: boolean; rate_age_seconds: number; } | null; payment_token: string | null; payment_uri: string; callback_url: string | null; metadata: Record<string, unknown> | null; matching_mode: "any" | "exact" | "at_least"; confirmation_threshold: number; status: "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled"; expires_at: number; expires_at_iso: string; created_at: number; created_at_iso: string; derivation_path?: string | undefined; verification_standard?: "bip84" | "bip44" | "cip1852" | "bip44_ed25519" | undefined; transactions?: { id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; tx_hash: string; to_address: string | null; tx_output_index: number | null; amount_units: string; block_height: number | null; confirmations: number; received_at: number; received_at_iso: string; orphaned_at: number | null; orphaned_at_iso: string | null; }[] | undefined; confirmations?: number | undefined; };
+
+export type InvoiceSearchQuery = { external_id?: string | undefined; address?: string | undefined; tx_hash?: string | undefined; amount?: string | undefined; status?: "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled" | undefined; date_from?: string | undefined; date_to?: string | undefined; cursor?: string | undefined; limit?: number | undefined; };
+
+export type CursorPaginatedInvoiceResponse = { items: { id: string; project_id: string; external_id: string; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; address: string; amount_crypto: string; amount_crypto_units: string; amount_usd: number | null; rate_snapshot: { rate: string; source: "coingecko"; quoted_at: string; rate_is_stale: boolean; rate_age_seconds: number; } | null; payment_token: string | null; payment_uri: string; callback_url: string | null; metadata: Record<string, unknown> | null; matching_mode: "any" | "exact" | "at_least"; confirmation_threshold: number; status: "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled"; expires_at: number; expires_at_iso: string; created_at: number; created_at_iso: string; derivation_path?: string | undefined; verification_standard?: "bip84" | "bip44" | "cip1852" | "bip44_ed25519" | undefined; transactions?: { id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; tx_hash: string; to_address: string | null; tx_output_index: number | null; amount_units: string; block_height: number | null; confirmations: number; received_at: number; received_at_iso: string; orphaned_at: number | null; orphaned_at_iso: string | null; }[] | undefined; confirmations?: number | undefined; }[]; next_cursor?: string | undefined; };
+
+export type OrphanPaymentListQuery = { attributed?: boolean | undefined; chain?: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc" | undefined; tx_hash?: string | undefined; date_from?: string | undefined; date_to?: string | undefined; amount_units_gte?: string | undefined; amount_units_lte?: string | undefined; cursor?: string | undefined; limit?: number | undefined; };
+
+export type CursorPaginatedOrphanPaymentResponse = { items: { id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; tx_hash: string; to_address: string; tx_output_index: number; amount_units: string; block_height: number | null; received_at: number; received_at_iso: string; attributed: boolean; attributed_invoice_id: string | null; attributed_external_id: string | null; attributed_at: number | null; attributed_at_iso: string | null; }[]; next_cursor?: string | undefined; };
+
+export type OrphanAttributeRequest = { external_id: string; user_id?: string | undefined; metadata?: Record<string, unknown> | undefined; to_address?: string | undefined; tx_output_index?: number | undefined; };
+
+export type WebhookEventListApiQuery = { status?: "delivered" | "retrying" | "dlq" | "skipped" | undefined; event_type?: "invoice.detected" | "invoice.paid" | "invoice.overpaid" | "invoice.partial" | "invoice.expired" | "invoice.expired_paid_late" | "invoice.reverted" | undefined; since?: string | undefined; invoice_id?: string | undefined; cursor?: string | undefined; limit?: number | undefined; };
+
+export type WebhookEventListResponse = { items: { id: string; event_type: "invoice.detected" | "invoice.paid" | "invoice.overpaid" | "invoice.partial" | "invoice.expired" | "invoice.expired_paid_late" | "invoice.reverted"; status: "delivered" | "retrying" | "dlq" | "skipped"; created_at: string; target_url: string | null; attempt_count: number; last_response_status: number | null; invoice_id: string | null; dlq_at: string | null; delivered_at: string | null; skip_reason: "not_subscribed" | "no_target_url" | null; }[]; next_cursor?: string | undefined; };
+
+export type WebhookEventResendResponse = { event_id: string; original_event_id: string; event_type: "invoice.detected" | "invoice.paid" | "invoice.overpaid" | "invoice.partial" | "invoice.expired" | "invoice.expired_paid_late" | "invoice.reverted"; project_id: string; invoice_id: string | null; target_url: string | null; created_at: number; created_at_iso: string; };
+
+export type WebhookEvent = { event_id: string; event_type: "invoice.detected"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.paid"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.overpaid"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.partial"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.expired"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.expired_paid_late"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.reverted"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; };
+
+export type WebhookEventData = { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; };
+
+export type WebhookEventMode = "production" | "testnet" | "sandbox";
+
+export type WebhookEventType = "invoice.detected" | "invoice.paid" | "invoice.overpaid" | "invoice.partial" | "invoice.expired" | "invoice.expired_paid_late" | "invoice.reverted";
+
+export type RatesQuery = { coins?: string | undefined; };
+
+export type RatesResponse = { quoted_at: string; source: "coingecko"; rates: Partial<Record<"btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton", { rate: string; rate_is_stale: boolean; rate_age_seconds: number; }>>; indicative_notice: string; };
+
+export type QuoteQuery = { amount_usd: number; coins?: string | undefined; };
+
+export type QuoteResponse = { amount_usd: number; quoted_at: string; source: "coingecko"; quotes: Partial<Record<"btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton", { amount_crypto: string; amount_crypto_units: string; rate: string; rate_is_stale: boolean; rate_age_seconds: number; }>>; indicative_notice: string; };
+
+export type ErrorCode = "validation_error" | "invalid_coin" | "invalid_xpub_format" | "invalid_webhook_url" | "auth_invalid" | "signature_invalid" | "signature_replayed" | "timestamp_out_of_window" | "key_suspended" | "project_suspended" | "permission_denied" | "key_revoked" | "invoice_not_found" | "project_not_found" | "wallet_not_found" | "external_id_conflict" | "xpub_not_verified" | "coin_not_enabled" | "amount_out_of_range" | "rate_limit_exceeded" | "pool_exhausted" | "webhook_capacity_exhausted" | "duplicate_provider_webhook_id" | "otp_expired" | "otp_used" | "invite_invalid" | "internal_error" | "invoice_not_cancellable" | "invalid_state_transition" | "orphan_not_found" | "orphan_already_attributed" | "event_not_found" | "wallet_not_bound" | "wallet_not_owned" | "wallet_has_active_bindings" | "wallet_kind_mismatch" | "subscription_expired" | "tron_no_activated_addresses_available" | "ton_operator_wallet_not_deployed" | "ton_invalid_wallet_version" | "ton_jetton_resolve_failed" | "ton_comment_parse_failed" | "tonconnect_payload_expired" | "tonconnect_payload_unknown" | "tonconnect_domain_mismatch" | "tonconnect_timestamp_skew" | "tonconnect_unknown_wallet_version" | "tonconnect_signature_invalid" | "tonconnect_network_mismatch" | "sandbox_project_required" | "production_project_required" | "sandbox_per_operator_cap_reached" | "sandbox_key_against_production_project" | "production_key_against_sandbox_project" | "sandbox_provisioning_failed" | "sandbox_invoice_transition_invalid" | "sandbox_invoice_not_found" | "sandbox_invoice_terminal" | "sandbox_rate_limit_exceeded" | "sandbox_reset_failed" | "sandbox_delete_failed" | "sandbox_active_invoice_cap_reached";
+
+export type ProblemDetails = { type: "about:blank"; title: string; status: number; error_code: "validation_error" | "invalid_coin" | "invalid_xpub_format" | "invalid_webhook_url" | "auth_invalid" | "signature_invalid" | "signature_replayed" | "timestamp_out_of_window" | "key_suspended" | "project_suspended" | "permission_denied" | "key_revoked" | "invoice_not_found" | "project_not_found" | "wallet_not_found" | "external_id_conflict" | "xpub_not_verified" | "coin_not_enabled" | "amount_out_of_range" | "rate_limit_exceeded" | "pool_exhausted" | "webhook_capacity_exhausted" | "duplicate_provider_webhook_id" | "otp_expired" | "otp_used" | "invite_invalid" | "internal_error" | "invoice_not_cancellable" | "invalid_state_transition" | "orphan_not_found" | "orphan_already_attributed" | "event_not_found" | "wallet_not_bound" | "wallet_not_owned" | "wallet_has_active_bindings" | "wallet_kind_mismatch" | "subscription_expired" | "tron_no_activated_addresses_available" | "ton_operator_wallet_not_deployed" | "ton_invalid_wallet_version" | "ton_jetton_resolve_failed" | "ton_comment_parse_failed" | "tonconnect_payload_expired" | "tonconnect_payload_unknown" | "tonconnect_domain_mismatch" | "tonconnect_timestamp_skew" | "tonconnect_unknown_wallet_version" | "tonconnect_signature_invalid" | "tonconnect_network_mismatch" | "sandbox_project_required" | "production_project_required" | "sandbox_per_operator_cap_reached" | "sandbox_key_against_production_project" | "production_key_against_sandbox_project" | "sandbox_provisioning_failed" | "sandbox_invoice_transition_invalid" | "sandbox_invoice_not_found" | "sandbox_invoice_terminal" | "sandbox_rate_limit_exceeded" | "sandbox_reset_failed" | "sandbox_delete_failed" | "sandbox_active_invoice_cap_reached"; request_id: string; errors?: unknown[] | undefined; wallet_id?: string | undefined; current_status?: string | undefined; requested_event?: string | undefined; current_count?: number | undefined; reset_url?: string | undefined; failed_step?: string | null | undefined; wallet_kind?: "production" | "testnet" | "sandbox" | undefined; project_kind?: "production" | "testnet" | "sandbox" | undefined; };
+
+export type Chain = "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc";
+
+export type Coin = "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton";
+
+export type WalletEdgeKind = "production" | "testnet";
+
+export type ClockAdvance = { chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; blocks: number; };
+
+export type SimulateEvent = { eventType: "invoice.detected" | "invoice.paid" | "invoice.overpaid" | "invoice.partial" | "invoice.expired" | "invoice.expired_paid_late" | "invoice.reverted"; amountUnits: string; confirmations: number; blockHeight: number; expectedCurrentStatus: "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled"; chainSpecific?: unknown; seed?: string | undefined; };
+
+export type SimulateLatePayment = { amountUnits?: string | undefined; seed?: string | undefined; };
+
+export type SimulateOverpaid = { multiplier?: number | undefined; extraUnits?: string | undefined; seed?: string | undefined; };
+
+export type SimulatePartial = { fraction?: number | undefined; amountUnits?: string | undefined; seed?: string | undefined; };
+
+export type WalletsListResponse = { items: { chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; xpub: string | null; derivation_path: string; stake_address: string | null; ed25519_pubkey_hex: string | null; }[]; };
+
+export declare const ERROR_CODES: readonly ["validation_error", "invalid_coin", "invalid_xpub_format", "invalid_webhook_url", "auth_invalid", "signature_invalid", "signature_replayed", "timestamp_out_of_window", "key_suspended", "project_suspended", "permission_denied", "key_revoked", "invoice_not_found", "project_not_found", "wallet_not_found", "external_id_conflict", "xpub_not_verified", "coin_not_enabled", "amount_out_of_range", "rate_limit_exceeded", "pool_exhausted", "webhook_capacity_exhausted", "duplicate_provider_webhook_id", "otp_expired", "otp_used", "invite_invalid", "internal_error", "invoice_not_cancellable", "invalid_state_transition", "orphan_not_found", "orphan_already_attributed", "event_not_found", "wallet_not_bound", "wallet_not_owned", "wallet_has_active_bindings", "wallet_kind_mismatch", "subscription_expired", "tron_no_activated_addresses_available", "ton_operator_wallet_not_deployed", "ton_invalid_wallet_version", "ton_jetton_resolve_failed", "ton_comment_parse_failed", "tonconnect_payload_expired", "tonconnect_payload_unknown", "tonconnect_domain_mismatch", "tonconnect_timestamp_skew", "tonconnect_unknown_wallet_version", "tonconnect_signature_invalid", "tonconnect_network_mismatch", "sandbox_project_required", "production_project_required", "sandbox_per_operator_cap_reached", "sandbox_key_against_production_project", "production_key_against_sandbox_project", "sandbox_provisioning_failed", "sandbox_invoice_transition_invalid", "sandbox_invoice_not_found", "sandbox_invoice_terminal", "sandbox_rate_limit_exceeded", "sandbox_reset_failed", "sandbox_delete_failed", "sandbox_active_invoice_cap_reached"];
+
+export declare const ERROR_CODE_STATUS: { readonly validation_error: 400; readonly invalid_coin: 400; readonly invalid_xpub_format: 400; readonly invalid_webhook_url: 400; readonly auth_invalid: 401; readonly signature_invalid: 401; readonly signature_replayed: 401; readonly timestamp_out_of_window: 401; readonly key_suspended: 403; readonly project_suspended: 403; readonly permission_denied: 403; readonly key_revoked: 403; readonly invoice_not_found: 404; readonly project_not_found: 404; readonly wallet_not_found: 404; readonly external_id_conflict: 409; readonly xpub_not_verified: 409; readonly coin_not_enabled: 422; readonly amount_out_of_range: 422; readonly rate_limit_exceeded: 429; readonly pool_exhausted: 503; readonly webhook_capacity_exhausted: 503; readonly duplicate_provider_webhook_id: 409; readonly otp_expired: 400; readonly otp_used: 400; readonly invite_invalid: 400; readonly internal_error: 500; readonly invoice_not_cancellable: 409; readonly invalid_state_transition: 409; readonly orphan_not_found: 404; readonly orphan_already_attributed: 409; readonly event_not_found: 404; readonly wallet_not_bound: 422; readonly wallet_not_owned: 403; readonly wallet_has_active_bindings: 409; readonly wallet_kind_mismatch: 422; readonly subscription_expired: 402; readonly tron_no_activated_addresses_available: 422; readonly ton_operator_wallet_not_deployed: 422; readonly ton_invalid_wallet_version: 422; readonly ton_jetton_resolve_failed: 503; readonly ton_comment_parse_failed: 422; readonly tonconnect_payload_expired: 400; readonly tonconnect_payload_unknown: 400; readonly tonconnect_domain_mismatch: 400; readonly tonconnect_timestamp_skew: 400; readonly tonconnect_unknown_wallet_version: 400; readonly tonconnect_signature_invalid: 400; readonly tonconnect_network_mismatch: 400; readonly sandbox_project_required: 403; readonly production_project_required: 403; readonly sandbox_per_operator_cap_reached: 422; readonly sandbox_key_against_production_project: 400; readonly production_key_against_sandbox_project: 400; readonly sandbox_provisioning_failed: 500; readonly sandbox_invoice_transition_invalid: 422; readonly sandbox_invoice_not_found: 404; readonly sandbox_invoice_terminal: 422; readonly sandbox_rate_limit_exceeded: 429; readonly sandbox_reset_failed: 500; readonly sandbox_delete_failed: 500; readonly sandbox_active_invoice_cap_reached: 422; };