API documentation

GET /api/v1/me

Returns the authenticated user id, name, email, and wallet address (if a wallet exists).

POST /api/v1/invoices

Create a deposit invoice. Body (JSON):

{
  "amount": "100.50",
  "order_id": "order_123",
  "network": "mainnet",
  "ipn_callback_url": "https://yoursite.com/webhooks/nova"
}

• network — mainnet or testnet
• order_id — unique per account; pattern [a-zA-Z0-9._-]+
• ipn_callback_url — optional HTTPS URL for confirmed-payment webhooks
• callback_url — also supported as backward-compatible alias

Each invoice is issued its own single-use pay_address. Quote that address to your customer — never your own wallet address, and never an address from a previous invoice. Funds paid there are swept to your NovaPayments wallet automatically once the order settles.

Because no two open invoices share an address, a payment is attributed to exactly one order: two customers paying the same amount at the same time can no longer be confused for one another. Payments still accumulate against the invoice, so a partial payment is recorded rather than ignored — see Partial and over payments below.

GET /api/v1/invoices

Paginated list of invoices (data + meta).

GET /api/v1/invoices/{invoice_id}

invoice_id is the public id (e.g. inv_…). Refreshes chain sync for your account when called.

Includes amount_received, amount_remaining, amount_overpaid, and a payments array listing each on-chain transfer applied to the invoice.

pay_address is fixed for the life of the invoice, so it is safe to cache alongside the order or render into a QR code.

POST /api/v1/withdrawals

Request a USDT payout from your NovaPayments wallet. Body (JSON):

{
  "amount": "50.00",
  "network": "mainnet",
  "to_address": "0x…",
  "reference": "payout_456",
  "callback_url": "https://yoursite.com/webhooks/nova"
}

• amount — gross amount debited from your wallet. The platform fee (2.00%) is taken out of it, so the destination receives net_amount = amount − fee_amount (request 30 → destination receives 29.4).
• to_address — optional; defaults to the withdrawal wallet address on your account
• reference — unique per account; pattern [a-zA-Z0-9._-]+
• callback_url — optional HTTPS URL for payout webhooks

Returns 201 with the payout in pending. Nothing is broadcast during the request — the scheduler picks it up within a minute. Reposting the same reference returns 200 with the original payout instead of sending twice, so retries are safe.

GET /api/v1/withdrawals

Paginated list of payouts (data + meta). Optional ?status= and ?network= filters.

GET /api/v1/withdrawals/{withdrawal_id}

Accepts the public id (wd_…) or your own reference. Refreshes the on-chain receipt when called.

Status flow: pending → processing → sent → confirmed or failed. A payout still pending can be cancelled.

POST /api/v1/withdrawals/{withdrawal_id}/cancel

Cancels a payout that has not been broadcast yet. Returns 409 once it has reached processing or later.