Wirnora API

Last updated: 27 October 2026

This page covers everything needed to take USDT payments with Wirnora: authenticating, giving each customer a deposit address, being told when they pay, and checking a payment before you deliver. Questions: [email protected].

Before you start

Base URL: https://api.wirnora.com/v1

Every request is authenticated with an API key in the Authorization header:

Authorization: Bearer sk_live_…

Create a key in the dashboard under Businesses → API keys → Create key. The full key is shown once.

Amounts are integer strings in the asset's smallest unit. USDT on BNB Smart Chain has 18 decimals, so "1000000000000000000" is 1 USDT. Fields ending in _formatted are for display only. Never use floating-point numbers for money.

Responses put a single object or a list under data. Lists also carry meta (see paging).

Accept a payment

Step 1: give the customer an address

Create an address once per customer, the first time they open your deposit page. The address is theirs for good, so store it or ask again: calling this twice for the same external_user_id returns the same address.

curl https://api.wirnora.com/v1/addresses \
  -H "Authorization: Bearer $WIRNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: address:user_60" \
  -d '{"external_user_id": "user_60"}'
201 Created

{
  "data": {
    "id": "a3f1c2d8-…",
    "external_user_id": "user_60",
    "chain": "bsc",
    "asset": "USDT",
    "address": "0x8dfe…1426",
    "memo": null,
    "min_deposit": "1000000000000000000",
    "min_deposit_formatted": "1",
    "decimals": 18,
    "required_confirmations": 15,
    "status": "active",
    "created_at": "2026-10-24T09:12:03Z"
  }
}

Step 2: show it, with the network and the minimum

Tell your customer three things next to the address:

Step 3: wait for deposit.confirmed

When the customer pays you receive deposit.detected within seconds, then deposit.confirmed at 15 confirmations, when the amount is credited to your balance. See Webhooks.

Step 4: confirm with the API, then deliver

A valid signature proves the notice came from Wirnora. Base the decision to deliver on the deposit itself:

async function confirmDeposit(depositId) {
  const res = await fetch(`https://api.wirnora.com/v1/deposits/${encodeURIComponent(depositId)}`, {
    headers: { Authorization: `Bearer ${process.env.WIRNORA_API_KEY}` },
  });
  if (res.status === 404) return null;                       // not yours, or no such deposit
  if (!res.ok) throw new Error(`Wirnora API ${res.status}`); // retry later
  const body = await res.json();
  const d = body.data ?? body;
  return d.status === 'confirmed' ? d : null;
}

GET /v1/deposits/{id} currently returns the deposit object at the top level, not under data. Reading body.data ?? body keeps working either way.

Then credit once:

Read your deposits and balance

Request What it returns
GET /v1/deposits Your deposits, newest first. Filters: status (detected, confirmed, orphaned), external_user_id
GET /v1/deposits/{id} One deposit, including sender_address
GET /v1/addresses Your addresses, with deposit_count
GET /v1/addresses/{id} One address
GET /v1/balances Your balance per asset: balance and balance_formatted
GET /v1/assets Assets you can use, with decimals, required_confirmations and min_deposit

A deposit carries amount, fee and net_amount (with _formatted versions), tx_hash, block_number, confirmations, status, detected_at and confirmed_at.

Paging. Lists take limit (1 to 200, default 50) and offset, and answer with:

"meta": {"limit": 50, "offset": 0, "count": 50, "has_more": true}

count is the length of this page, not a total. Ask for the next page while has_more is true.

A payment link is a hosted pay page for one amount, for when you have no checkout of your own: an invoice, a chat, a one-off sale. Create one in the dashboard, or with the API:

curl https://api.wirnora.com/v1/payment-links \
  -H "Authorization: Bearer $WIRNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Order 1042", "amount": "25000000000000000000"}'

API keys

Keep the key on your server only. Do not put it in browser JavaScript, a mobile or desktop app, a public repository, a URL or a log line. Anything shipped to a customer's device can be read by that customer. Read it from an environment variable or a secret manager.

Keys created in the dashboard carry the read and write permissions:

With a dashboard key you can You cannot
Create deposit addresses and payment links Request a withdrawal: that is done in the dashboard, with your authenticator code
Read deposits, balances, addresses, payment links and payouts Approve or send anything
Re-send a webhook event Read or change webhook signing secrets

If a key leaks:

  1. Revoke it in the dashboard. Requests with it are refused from that moment.
  2. Create a new key and deploy it.

Creating and revoking keys needs your authenticator code, and the account owner is emailed each time. An email you did not expect means someone else is in your account: change your password and reply to that email.

Webhooks

Setting up an endpoint

In the dashboard, Businesses → Webhooks → Add endpoint.

Adding an endpoint, replacing its secret, and disabling or enabling it need your authenticator code. The account owner is emailed for each.

What we send

POST <your endpoint>
Content-Type: application/json
X-Signature: t=1792789267,v1=5d1c…e9a0
X-Event-Id: 0b6e4c52-…
X-Event-Type: deposit.confirmed

{ ...the event as JSON... }

X-Event-Id is the same on every retry and replay of an event.

Delivery rules

Re-sending an event

POST /v1/webhooks/{event_id}/replay puts one of your events back in the queue with a fresh set of retries. {event_id} is the X-Event-Id you received. GET /v1/webhook-endpoints lists your endpoints; secrets are never returned.

Verify the signature

Do this on every request. X-Signature is t=<unix seconds> followed by one or more v1=<hex> values. There is normally one v1; for 24 hours after a secret replacement there are two.

  1. Take the raw request body bytes, exactly as received. Do not parse and re-serialise the JSON: the bytes would change and the check would fail.
  2. Compute HMAC-SHA256(key = your whsec_… secret, message = "<t>." + raw body), hex-encoded. The key is the whole secret string, including whsec_.
  3. Accept the request if any v1 equals your result, compared in constant time.
  4. Reject it if t is more than 5 minutes from your clock. This stops replays of captured requests.
  5. Deduplicate on X-Event-Id.

The three functions below were run against signatures made by Wirnora's own signer: they accept the new and the old secret during an overlap, and reject a wrong secret, a changed body, a 10-minute-old timestamp and an empty or malformed header. The framework code around them is standard and was not run.

Node.js

const crypto = require('crypto');

function verifyWirnora(rawBody, header, secret, toleranceSeconds = 300) {
  if (typeof header !== 'string' || header === '') return false;
  let t = 0;
  const signatures = [];
  for (const part of header.split(',')) {
    const i = part.indexOf('=');
    if (i < 0) continue;
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === 't' && /^\d+$/.test(value)) t = Number(value);
    else if (key === 'v1' && /^[0-9a-f]{64}$/.test(value)) signatures.push(value);
  }
  if (t <= 0 || signatures.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;

  const expected = crypto.createHmac('sha256', secret)
    .update(`${t}.`)
    .update(rawBody)            // the exact bytes you received
    .digest();
  let ok = false;
  for (const s of signatures) {
    if (crypto.timingSafeEqual(Buffer.from(s, 'hex'), expected)) ok = true;
  }
  return ok;
}

// Express: take the body raw for this route only.
app.post('/webhooks/wirnora', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyWirnora(req.body, req.get('X-Signature'), process.env.WIRNORA_WEBHOOK_SECRET)) {
    return res.status(400).send('bad signature');
  }
  const event = JSON.parse(req.body.toString('utf8'));
  // store (X-Event-Id, event), process it after replying
  res.sendStatus(200);
});

PHP

<?php
function wirnora_verify(string $rawBody, ?string $header, string $secret, int $tolerance = 300): bool
{
    if ($header === null || $header === '') {
        return false;
    }
    $t = 0;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        $kv = explode('=', trim($part), 2);
        if (count($kv) !== 2) {
            continue;
        }
        if ($kv[0] === 't' && ctype_digit($kv[1])) {
            $t = (int) $kv[1];
        } elseif ($kv[0] === 'v1' && preg_match('/^[0-9a-f]{64}$/', $kv[1])) {
            $signatures[] = $kv[1];
        }
    }
    if ($t <= 0 || !$signatures || abs(time() - $t) > $tolerance) {
        return false;
    }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    $ok = false;
    foreach ($signatures as $s) {
        if (hash_equals($expected, $s)) {
            $ok = true;
        }
    }
    return $ok;
}

$raw = file_get_contents('php://input');                 // raw bytes
if (!wirnora_verify($raw, $_SERVER['HTTP_X_SIGNATURE'] ?? null, getenv('WIRNORA_WEBHOOK_SECRET'))) {
    http_response_code(400);
    exit('bad signature');
}
$event = json_decode($raw, true);
// store ($_SERVER['HTTP_X_EVENT_ID'], $event), process it after replying
http_response_code(200);

Python

import hashlib, hmac, json, os, re, time

_HEX64 = re.compile(r"^[0-9a-f]{64}$")

def verify_wirnora(raw_body: bytes, header, secret: str, tolerance: int = 300) -> bool:
    if not header:
        return False
    t, signatures = 0, []
    for part in header.split(","):
        key, sep, value = part.strip().partition("=")
        if not sep:
            continue
        if key == "t" and value.isdigit():
            t = int(value)
        elif key == "v1" and _HEX64.match(value):
            signatures.append(value)
    if t <= 0 or not signatures or abs(int(time.time()) - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    ok = False
    for s in signatures:
        if hmac.compare_digest(expected, s):
            ok = True
    return ok

# Flask
@app.post("/webhooks/wirnora")
def wirnora_webhook():
    raw = request.get_data()                             # raw bytes
    if not verify_wirnora(raw, request.headers.get("X-Signature"), os.environ["WIRNORA_WEBHOOK_SECRET"]):
        return "bad signature", 400
    event = json.loads(raw)
    # store (request.headers["X-Event-Id"], event), process it after replying
    return "", 200

Events

Branch on the X-Event-Type header.

X-Event-Type Meaning What to do
deposit.detected A transfer to one of your addresses was seen on chain, with 0 confirmations Show "payment received, confirming". Do not deliver yet
deposit.confirmed It reached 15 confirmations and was credited to your balance Confirm with the API, then deliver. Credit once per deposit_id + lifecycle_version
deposit.orphaned A blockchain reorganisation removed the transfer If was_credited is true and you already delivered, treat it as reversed
deposit.reinstated An orphaned transfer reappeared on chain Like deposit.detected. A new deposit.confirmed with a higher lifecycle_version follows
test.ping Sent from the dashboard's Send test Verify the signature and reply 200. Nothing else

deposit.confirmed (field order may differ; parse it as JSON):

{
  "event": "deposit.confirmed",
  "deposit_id": "5f0c3c1e-…",
  "external_user_id": "user_60",
  "address": "0x8dfe…1426",
  "chain": "bsc",
  "asset": "USDT",
  "amount": "100000000000000000000",
  "amount_formatted": "100",
  "fee": "500000000000000000",
  "net_amount": "99500000000000000000",
  "net_formatted": "99.5",
  "decimals": 18,
  "tx_hash": "0x…",
  "block_number": 123,
  "confirmations": 15,
  "lifecycle_version": 0,
  "status": "confirmed"
}

Withdrawals

Withdrawals are made in the dashboard, not with a dashboard API key, and each step needs a fresh code from your authenticator app.

  1. Register a payout address under Payout addresses. It can be used 48 hours after it is added. The account owner is emailed the moment it is added, so a stranger's address cannot wait out the 48 hours unnoticed.
  2. Request a withdrawal to a registered address. The owner is emailed again.
  3. Our team reviews and sends it, normally within 24 hours. A first withdrawal to a new address, or one that looks unusual, may take longer while we check it with you.

There is no withdrawal fee, and we pay the network fee: you receive the full amount. GET /v1/payouts and GET /v1/payouts/{id} show each withdrawal and its transaction once sent.

Errors and limits

Errors use the HTTP status and a body like this:

{
  "error": {
    "type": "invalid_request",
    "message": "external_user_id is required.",
    "param": "external_user_id",
    "request_id": "…"
  }
}
Status type Meaning
400 invalid_request The request is wrong; param names the field
401 authentication_error Missing, unknown or revoked key
403 insufficient_scope, permission_error The key may not do this
404 not_found No such object, or it is not yours
409 idempotency_error The Idempotency-Key was used with a different body
429 rate_limit_error Too many requests; wait and retry
5xx Our side; retry with backoff

Checklist before going live