Invoices

Base URL: https://txnod.com/api/v1. Every request must carry the three HMAC headers:

• X-Project-Id — the API Key ID (sent in the X-Project-Id header).
• X-Timestamp — current Unix timestamp (seconds). Requests outside the ±300-second window are rejected with timestamp_out_of_window.
• X-Signature — HMAC-SHA256 hex digest of ${method}\n${pathname}\n${timestamp}\n${rawBody} using the project’s API secret. Binding method + path makes a captured (X-Timestamp, X-Signature) pair non-replayable across endpoints.

The SDK (@txnod/sdk) handles signing transparently — prefer it over hand-rolled cURL except for smoke tests.

These endpoints serve production and testnet projects only — a sandbox project is rejected with production_project_required (403). Sandbox projects use the mirrored /api/v1/sandbox/invoices surface (client.sandbox.createInvoice and friends in the SDK).

Create an invoice

POST https://txnod.com/api/v1/invoices — creates a new invoice. Idempotent on (project_id, external_id): a replayed request returns the existing invoice with HTTP 200 instead of 201.

Request

Request body (application/json)

amount_usd must be between 0.01 and 1,000,000,000 (inclusive); values outside that range are rejected at the schema edge with a 400 validation_error.

matching_mode (optional) overrides the project’s default amount-matching policy for this invoice. exact requires the deposit amount to equal the invoice amount; at_least accepts any amount ≥ the invoice amount (overpayment OK); any accepts any amount (donations / pay-what-you-want). Omit the field to inherit the project’s configured default. When the operator’s address pool is saturated such that the invoice would share a deposit address with another invoice, only exact can disambiguate by amount — at_least and any are then rejected with 422 overlay_matching_mode_required_exact. The resolved mode is returned on every invoice response as matching_mode.

Response

200 — Idempotent replay — existing invoice returned unchanged

201 — Invoice created

Errors

Examples

curl -X POST https://txnod.com/api/v1/invoices \
  -H "X-Project-Id: $TXNOD_API_KEY_ID" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: <hex>" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"order-123","amount_usd":10.0,"coin":"btc"}'

import { TxnodClient } from '@txnod/sdk';
 
const client = new TxnodClient({
  projectId: process.env.TXNOD_API_KEY_ID!,
  apiSecret: process.env.TXNOD_API_SECRET!,
});
 
const invoice = await client.createInvoice({
  external_id: 'order-123',
  amount_usd: 10.0,
  coin: 'btc',
});

Search invoices

GET https://txnod.com/api/v1/invoices — cursor-paginated search over the caller project’s invoices.

Request

Query parameters

Response

200 — Cursor-paginated invoice list

Errors

Examples

curl "https://txnod.com/api/v1/invoices?status=paid&limit=20" \
  -H "X-Project-Id: $TXNOD_API_KEY_ID" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: <hex>"

import { TxnodClient } from '@txnod/sdk';
 
const client = new TxnodClient({
  projectId: process.env.TXNOD_API_KEY_ID!,
  apiSecret: process.env.TXNOD_API_SECRET!,
});
 
const page = await client.searchInvoices({ status: 'paid', limit: 20 });
for (const invoice of page.items) console.log(invoice.id);

Retrieve an invoice

GET https://txnod.com/api/v1/invoices/{id} — fetch a single invoice by ULID. Returns 404 on cross-project lookups (no enumeration).

Request

Path parameters

Response

200 — Invoice detail including transactions + confirmations

Errors

Examples

curl https://txnod.com/api/v1/invoices/01HK8MAR2QEXAMPLE000000000 \
  -H "X-Project-Id: $TXNOD_API_KEY_ID" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: <hex>"

import { TxnodClient } from '@txnod/sdk';
 
const client = new TxnodClient({
  projectId: process.env.TXNOD_API_KEY_ID!,
  apiSecret: process.env.TXNOD_API_SECRET!,
});
 
const invoice = await client.getInvoice('01HK8MAR2QEXAMPLE000000000');
console.log(invoice.status);

Cancel an invoice

POST https://txnod.com/api/v1/invoices/{id}/cancel — cancels an invoice in pending or detected state and releases its pool address into cooldown. Terminal-status invoices return 409 invoice_not_cancellable.

Request

Path parameters

Response

200 — Invoice cancelled

Errors

Examples

curl -X POST https://txnod.com/api/v1/invoices/01HK8MAR2QEXAMPLE000000000/cancel \
  -H "X-Project-Id: $TXNOD_API_KEY_ID" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: <hex>"

import { TxnodClient } from '@txnod/sdk';
 
const client = new TxnodClient({
  projectId: process.env.TXNOD_API_KEY_ID!,
  apiSecret: process.env.TXNOD_API_SECRET!,
});
 
const cancelled = await client.cancelInvoice('01HK8MAR2QEXAMPLE000000000');
console.log(cancelled.status);