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
- Accept a payment
- Read your deposits and balance
- Payment links
- API keys
- Webhooks
- Verify the signature
- Events
- Withdrawals
- Errors and limits
- Checklist before going live
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"}'
external_user_idis your own id for the customer, up to 255 characters. Do not use names or email addresses. It may not start withlink:.chainandassetare optional and default tobscandUSDT, the only pair live today.metadatais an optional JSON object stored with the address.Idempotency-Keyis optional. A retry with the same key and the same body returns the stored response withIdempotent-Replay: true. The same key with a different body is refused with409.
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:
- Network: BNB Smart Chain (BEP-20). Anything sent on another network, or any other token, is not credited.
- Asset: USDT.
- Minimum:
min_deposit_formattedUSDT (1 USDT today). Smaller transfers are ignored.
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:
- Key:
deposit_idtogether withlifecycle_versionfrom thedeposit.confirmedevent. - Amount:
net_amountfrom the API response, in base units. Our 0.5% fee is already deducted. - Customer:
external_user_id, the id you gave when you created the address.
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.
Payment links
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"}'
nameis 3 to 60 characters and is shown to the payer.amountis in base units (the example is 25 USDT).- The response has
pay_url, the page to send your customer, andexpires_at. A link is offered for 1 hour. statusis one ofawaiting,confirming,paid,overpaid,underpaid,expiredorcancelled.GET /v1/payment-links,GET /v1/payment-links/{id}andPOST /v1/payment-links/{id}/cancellist, read and cancel links.Idempotency-Keyworks here as it does for addresses.
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 |
- At most 10 active keys per business. Keys do not expire.
- After creation only the prefix (
sk_live_xxxx…) is shown. Last used tells you whether a key is still in use.
If a key leaks:
- Revoke it in the dashboard. Requests with it are refused from that moment.
- 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.
- The endpoint must be
https://, use a domain name (not an IP address), and resolve only to public internet addresses. - The signing secret (
whsec_…) is shown once. Store it like a password. - At most 5 enabled endpoints per business.
- Send test sends a
test.ping, so you can check your code before real money arrives. - New secret replaces the secret. For 24 hours both the old and the new secret sign every notice, so you can deploy the new one without missing a callback.
- Disable stops all delivery to that 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
- Success is any
2xxwithin 15 seconds. - Retries: anything else is retried with backoff (1m, 3m, 10m, 30m, 1h, 2h, 4h, 6h, 12h, 24h), 12 attempts over about a day.
- A
4xxother than408or429is final and is not retried. Answer400only when you mean "never send this again", for example a bad signature. - Redirects are not followed. Give the final URL.
- Order is not guaranteed. A retried
deposit.detectedcan arrive afterdeposit.confirmed. - Answer fast: store the event, reply
200, then process it.
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.
- 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.
- Compute
HMAC-SHA256(key = your whsec_… secret, message = "<t>." + raw body), hex-encoded. The key is the whole secret string, includingwhsec_. - Accept the request if any
v1equals your result, compared in constant time. - Reject it if
tis more than 5 minutes from your clock. This stops replays of captured requests. - 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"
}
deposit.detectedanddeposit.reinstatedcarry the same fields exceptnet_formattedandlifecycle_version;statusis"detected",confirmationsis0, andrequired_confirmationsis added.deposit.orphanedcarriesevent,deposit_id,external_user_id,tx_hash,status("orphaned"),reason,was_creditedandlifecycle_version.test.pingis{"test": true, "note": "…", "at": "…"}and has noeventfield.
Withdrawals
Withdrawals are made in the dashboard, not with a dashboard API key, and each step needs a fresh code from your authenticator app.
- 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.
- Request a withdrawal to a registered address. The owner is emailed again.
- 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 |
- Rate limit: 50 requests per second, bursts up to 100, per client IP.
- Every response carries an
X-Request-Idheader. Quote it to support and we can find the exact request.
Checklist before going live
- The API key is in an environment variable on your server, nowhere else.
- The webhook secret is in an environment variable. The signature is verified on the raw body, and a bad signature gets
400. - A
tolder than 5 minutes is rejected, and events are deduplicated onX-Event-Id. - Goods are delivered only after
deposit.confirmedandGET /v1/deposits/{id}saysconfirmed. Each deposit is credited once. - Amounts are handled as integer strings, never floats.
- Your handler replies
200within 15 seconds and does the work afterwards. - Send test reached your endpoint, and your code accepted it.
- Your deposit page shows the network (BEP-20), the asset (USDT) and the minimum.