Accept USDT
without holding keys.

Overview

Three rules carry most of the integration. The rest of this page is detail.

Send the payer to payment_url. Do not render the address yourself. The hosted page locks the network, draws a QR every wallet reads the same way, and shows the confirmation window — the three things that stop a transfer nobody can recover.

Credit on the webhook, not on the API response. The response means an address was issued, nothing more.

Reconcile. Webhooks are a latency optimisation; the API is the truth.

Getting started

Six steps, in order. The last one is not optional — nothing before it proves the chain actually works end to end.

curl -X POST https://xazum.com/api/v1/invoices \
  -H "X-Api-Key: $XAZUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id":   "topup-8842",
    "amount":     "25.00",
    "return_url": "https://your-site.example/billing/done?o=topup-8842",
    "metadata":   {"user_id": 8842}
  }'

Authentication

One header on every request, including /health. The key is shown once when it is issued and stored as a hash — losing it costs nothing, issue another and revoke the old one.

# every call looks like this
curl https://xazum.com/api/v1/invoices \
  -H "X-Api-Key: xz_live_…" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"topup-8842","amount":"25.00"}'

A missing, unknown or revoked key all answer 401 with the same body. That is deliberate: distinguishing them would tell an attacker which keys once existed.

How a payment works

Worth reading once before the endpoints, because the shape explains why crediting happens where it does.

Other

Webhooks

This is the half of the contract OpenAPI cannot describe, because it describes what we send you rather than what you call — and it is the half that decides whether a payment credits.

X-Xazum-Event:      deposit.screened
X-Xazum-Event-Id:   6bd0a2f4-…            unique per delivery
X-Xazum-Timestamp:  1786296893            unix seconds
X-Xazum-Signature:  v1=9f2c…              HMAC-SHA256, hex

The signature is HMAC-SHA256(secret, "{timestamp}." + raw_body), keyed with your project's webhook secret.

Return 2xx — including for events you have already processed. Delivery is at-least-once: dedupe on X-Xazum-Event-Id and answer 200 for repeats. Returning an error for a duplicate turns a harmless retry into a retry storm. Retries are exponential, twelve attempts, about a day in total — long enough to survive your deploy.

Events

invoice.* events fire only when the invoice actually changes state. A second chunk landing on an already-partial invoice does not re-fire invoice.underpaid — you hear about that payment through deposit.confirmed.

A working receiver

Paste-ready for a Django consumer.

@csrf_exempt          # signed, not cookie-authenticated
@require_POST
def xazum_webhook(request):
    if not _verify(request):
        return HttpResponseForbidden("bad signature")

    if request.headers["X-Xazum-Event"] != "deposit.screened":
        return HttpResponse("ignored")      # 2xx, so it is not retried

    payload = json.loads(request.body)
    try:
        with transaction.atomic():
            # UNIQUE(txid, log_index) is what makes this safe to receive
            # twice — and you will receive it twice, by design.
            Deposit.objects.create(
                txid=payload["txid"],
                log_index=payload["log_index"],
                user_id=payload["metadata"]["user_id"],
                amount=Decimal(payload["amount"]),
            )
            credit_balance(payload["metadata"]["user_id"],
                           Decimal(payload["amount"]))
    except IntegrityError:
        pass                              # already processed; normal

    return HttpResponse("ok")


def _verify(request):
    signature = request.headers.get("X-Xazum-Signature", "")
    timestamp = request.headers.get("X-Xazum-Timestamp", "")
    if not signature.startswith("v1=") or not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > 300:      # replay window
        return False
    expected = hmac.new(
        settings.XAZUM_WEBHOOK_SECRET.encode(),
        f"{timestamp}.".encode() + request.body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature[3:])

(txid, log_index) identifies the transfer on chain and is stable forever. It is the right idempotency key for your ledger too — it is issued by consensus rather than by us, so it survives anything either side does.

Errors

Errors return JSON with a detail field. Log it — the messages are written to say what to do, not merely what went wrong.

Reconciliation

Run a job that finds invoices your side thinks are unpaid and asks GET /invoices/by-order/{order_id}. Anything a webhook lost, this finds. Without it, a delivery failure during a deploy becomes a customer who paid and was never credited — and the only person who notices is them.

GET /health reports scanner_lag_blocks. Alert on it. A lag around 18–19 is normal: that is the distance to the solidified head, which is where we read from. A growing lag means payments are arriving on chain and not being seen, while nothing is technically down.