Invoices

Create

Legacy dashboard API /invoices: provide amount as a positive decimal string, assetId, and an existing reusable walletId or an explicitly selected chain default. The first added wallet is the default; POST /wallets/:id/default changes it for new invoices only. DELETE /wallets/:id archives it; old destinations stay immutable and watched. Optional externalId, expiresInSeconds, metadata and idempotencyKey are supported. Retry with the same key and payload. Historical exact amounts are never recycled; exhaustion returns 409.

{
  "amount": "49.99",
  "walletId": "uuid",
  "assetId": "uuid",
  "externalId": "order-1024",
  "expiresInSeconds": 3600,
  "idempotencyKey": "order-1024"
}

Lifecycle

New invoices use attributionVersion 3: only one exact transfer to a unique eligible invoice settles PAID. Partials, underpayments and overpayments stay unmatched; they never accumulate or trigger invoice.paid. Expired and cancelled invoices are not payable. Version 1 needs review; historical version 2 retains its dedicated address policy. Shared addresses have no cryptographic invoice identity: an incorrectly intended transfer that exactly matches another eligible invoice can settle it. This is an accepted MVP product risk. Verify secure webhook v2 before fulfillment.

Money format

All monetary fields are decimal strings. Never serialize amounts as JavaScript numbers — precision matters for on-chain matching.