Invoice

An invoice is a payment request: a deposit address, a token, and an expected amount. When a matching deposit arrives, the invoice is marked paid. All endpoints require authentication.

Create Invoice

POST /api/v1/invoices

Request Body

Field	Type	Required	Description
`amount`	number	Yes	Expected amount (> 0)
`tokenCode`	string	Yes	Token to receive, e.g. `USDT`
`reference`	string	No	Your external reference
`expiresAt`	string (RFC3339)	No	Defaults to the app's configured expiry

{
  "amount": 100,
  "tokenCode": "USDT",
  "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"
  }
}

status can be pending, paid, expired, cancelled, or failed.

Code	Meaning
400	Validation error, inactive token, or invalid amount/expiry
404	Token not found
409	No available wallet

List Invoices

GET /api/v1/invoices

Query Parameters

Param	Type	Default	Description
`page`	int	1	Page number
`limit`	int	10	Items per page
`status`	string	—	Filter by status
`startDate`	string	—	RFC3339 or `YYYY-MM-DD`
`endDate`	string	—	RFC3339 or `YYYY-MM-DD`
`walletId`	string	—	Filter by wallet
`tokenCode`	string	—	Filter by token

Response `200`

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

Get Invoice

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

Code	Meaning
404	Invoice not found

Cancel Invoice

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

Code	Meaning
404	Invoice not found
409	Only `pending` invoices can be cancelled

Listen Wallet Withdraw