NullSwap Merchant Docs¶

NullSwap lets your backend accept crypto payments. You ask for a deposit address, show it to your customer, and we tell you over a webhook when the money has actually arrived and cleared screening.

Everything on this site describes the merchant API — a machine-to-machine HTTP API authenticated with a single API key. There is no browser flow, no OAuth and no session.

https://api.pay.nullswap.com

The same API also publishes an interactive Swagger reference at api.pay.nullswap.com/docs, generated from the API itself. Use it to check an exact field name or try a call; use this site to understand the flows. See Outside the version prefix.

Two ways to take money¶

The API offers two collection models. They are independent; use either or both.

Start with invoices. Reach for static wallets when you need a long-lived per-customer address rather than a per-order one.

The invoice flow end to end¶

sequenceDiagram
    autonumber
    participant B as Your backend
    participant N as NullSwap
    participant C as Customer
    participant W as Your webhook endpoint

    B->>N: POST /api/v1/invoices (chain, token, expectedAmount)
    N-->>B: 201 { id, depositAddress, expiresAt, status: WAITING }
    B->>C: show depositAddress + exact amount, until expiresAt
    C->>N: sends the tokens on chain

    N->>W: invoice.payment_detected · status PAYMENT_DETECTED
    Note over W: unconfirmed — show progress, ship nothing

    N->>N: confirmation depth reached, AML screening runs
    N->>W: invoice.payment_confirmed · payment CONFIRMED
    N->>W: invoice.paid · status PAID, paidAmount >= expectedAmount
    Note over W: this is the fulfilment signal

    W-->>N: 2xx

Steps 5–9 are all webhook deliveries. Polling GET /api/v1/invoices/{invoiceId} returns the same state, but it is a reconciliation tool for when your endpoint has been down — not the integration.

Getting started¶

1. Get an API key. Open your merchant in the cabinet and copy it from Settings → API key. It starts with sk_live_. Keys, IP whitelists and webhook subscriptions are all created there by a person; the API can read them but never create or change them. See Authentication.
2. Resolve a chain and a token. GET /api/v1/chains and GET /api/v1/tokens give you the UUIDs an invoice is addressed with. Cache them. See Chains and tokens.
3. Create an invoice. POST /api/v1/invoices. The response carries depositAddress — show it, or its QR code, to your customer. See Invoices.
4. Handle the webhook. Verify the HMAC signature, deduplicate on the delivery id, answer 2xx quickly, and fulfil on invoice.paid. See Webhooks.

Two things that trip people up¶

Amounts are strings, never JSON numbers. Every amount crosses the wire as a decimal string of an integer in the token's base units, paired with the token's decimals. 25.50 USDT on TRON is "25500000" with decimals: 6. See Amounts.

Errors are identified by a name, not by prose. The body carries a stable machine-readable name in message; branch on that, never on the HTTP status alone and never on wording.

{
  "statusCode": 422,
  "message": "InvalidInvoiceAmountError",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

See Errors for the full list.

Where to go next¶