Invoice

An invoice is a payment request: a deposit address, a token, and an expected amount. When a matching on-chain deposit is first seen, you receive deposit.invoice.pending_confirmation. After block confirmations, the invoice is marked paid and your off-chain balance is credited. All endpoints require authentication.

Balance type: Invoices do not return balance fields. Payment arrives on-chain at recipientAddress. Use deposit.invoice.pending_confirmation for a realtime “seen” signal, and deposit.invoice.paid / Assets after confirmation when activeBalance increases.

Create Invoice

POST /api/v1/invoices

Request Body

{
  "amount": 100,
  "tokenCode": "usdt-ethereum",
  "reference": "order-555"
}

Response 201

{
  "data": {
    "id": "inv_abc123",
    "expiresAt": "2026-01-01T01:00:00Z",
    "token": {
      "tokenCode": "USDT",
      "network": "ethereum",
      "tokenAddress": "0x...",
      "symbol": "USDT",
      "decimals": 6
    },
    "walletId": "wal_1",
    "walletNetwork": "ethereum",
    "recipientAddress": "0xabc...",
    "recipientAddressType": "evm",
    "amount": 100,
    "amountInDecimals": "100000000",
    "reference": "order-555",
    "status": "pending",
    "createdAt": "2026-01-01T00:00:00Z"
  }
}

Invoice object fields

List Invoices

GET /api/v1/invoices

Query Parameters

Response 200

{
  "data": {
    "items": [ /* invoice objects */ ],
    "total": 42,
    "page": 1,
    "limit": 10
  }
}

Get Invoice

GET /api/v1/invoices/:id → { "data": { /* invoice */ } }

Cancel Invoice

POST /api/v1/invoices/:id/cancel (no body). Returns the updated invoice with status: "cancelled".