Guides

Build with NITY0X

Task-focused walkthroughs, not a full reference. Each guide links back to the exact endpoints it uses — see the API reference for every parameter and response shape.

14 min · 4 steps

Accept your first payment

Create a payment, show the hosted checkout, confirm on-chain.

23 min · 3 steps

Verify webhook signatures

Confirm a webhook actually came from NITY0X before you act on it.

33 min · 3 steps

Send a payout

Withdraw a confirmed balance to an on-chain address.

Guide 1 of 3 · 4 min read

Accept your first payment

Create a payment, show the hosted checkout, confirm on-chain.

1
Create an API key
Every request authenticates with a Bearer token. Generate one from Dashboard → API Keys → Create key. The key is shown once — copy it immediately, since only its hash is stored afterward. Sandbox keys start with `mnt_test_sk_` and settle against local chain forks, so nothing you do here moves real funds.
2
Create a payment
A payment is the thing your customer pays. Amounts are USDT decimal strings with 6 decimal places — 25 USDT is the string `"25.000000"`, not the integer 25. The response includes a `checkout_url` (a hosted page you can redirect to) and a `deposit_address` (if you're building your own UI instead).
bashcurl
```
curl -X POST https://api.nity0x.io/v1/payments \
  -H "Authorization: Bearer mnt_test_sk_your_key_here" \
  -H "Idempotency-Key: order_001" \
  -H "Content-Type: application/json" \
  -d '{"amount":"25.000000","chain":"eth"}'
```
3
Send the customer to checkout
Redirect to `payment.checkout_url`. It's a single-use page scoped to this payment — the customer picks a network (if you didn't specify one), sees a deposit address and QR code, and watches the confirmation count up in real time.
4
Confirm the payment
You'll know it's done one of two ways: a `payment.confirmed` webhook fires the moment funds settle, or you poll `GET /v1/payments/:id` until `status` reads `confirmed`. Webhooks are the better default — polling is there for scripts and sandboxes where standing up a public endpoint isn't worth it yet.
jsonGET /v1/payments/:id → 200 OK
```
{
  "id": "pay_3kf9d2a1b7c4",
  "object": "payment",
  "status": "confirmed",
  "chain": "eth",
  "amount": "25.000000",
  "currency": "USDT",
  "confirmed_at": "2026-06-20T12:04:11Z"
}
```

Guide 2 of 3 · 3 min read

Verify webhook signatures

Confirm a webhook actually came from NITY0X before you act on it.

1
Register an endpoint
Give NITY0X a public HTTPS URL to call. The response includes a `secret` — store it securely, since it's returned exactly once and never shown again. This secret is what you use to verify every future delivery.
bashcurl
```
curl -X POST https://api.nity0x.io/v1/webhooks \
  -H "Authorization: Bearer mnt_test_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/nityox",
    "events": ["payment.confirmed", "payment.failed", "payout.confirmed"]
  }'
```
2
Never trust a delivery you haven't verified
Every request carries a `nityox-signature` header. Reconstruct the HMAC-SHA256 signature from the raw request body and compare it with a timing-safe check — never a plain `===`, which leaks timing information an attacker can use to guess the signature byte by byte.
tsTypeScript (Next.js Route Handler)
```
import crypto from "crypto";

export async function POST(req: Request) {
  const body = await req.text();
  const sig  = req.headers.get("nityox-signature") ?? "";
  const expected = crypto
    .createHmac("sha256", process.env.NITYOX_WEBHOOK_SECRET!)
    .update(body)
    .digest("hex");

  const valid = crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expected)
  );
  if (!valid) return new Response("Invalid signature", { status: 400 });

  const event = JSON.parse(body);
  // handle event.type, e.g. "payment.confirmed"
  return new Response("ok", { status: 200 });
}
```
3
Respond fast, handle idempotently
Acknowledge with an HTTP 2xx within 10 seconds — if your handler does real work (database writes, emails), queue it and respond immediately. Retries reuse the same event id, so treat every handler as idempotent: processing the same event twice should be a no-op, not a duplicate charge or double-sent email.

Guide 3 of 3 · 3 min read

Send a payout

Withdraw a confirmed balance to an on-chain address.

1
Confirm you have a settled balance
Only confirmed (settled) balances can be withdrawn — funds still in `pending` or `confirming` aren't eligible yet. Check `GET /v1/balances` before initiating a payout if you're not already tracking balance state yourself.
2
Create the payout
Always send an `Idempotency-Key` — payouts move real value, and a retried request without one could double-send. The payout moves through `pending → processing → confirmed`; a `payout.confirmed` webhook fires on settlement, same pattern as payments.
bashcurl
```
curl -X POST https://api.nity0x.io/v1/payouts \
  -H "Authorization: Bearer mnt_test_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout_20260619_001" \
  -d '{
    "chain": "eth",
    "to_address": "0xYourWallet...1234",
    "amount": "100.000000",
    "description": "Weekly settlement"
  }'
```
3
Mind the rate limit
Payout endpoints are limited to 10 requests/minute — if you're batching withdrawals for many merchants, space out the calls rather than firing them all at once.

curl -X POST https://api.nity0x.io/v1/payments \ -H "Authorization: Bearer mnt_test_sk_your_key_here" \ -H "Idempotency-Key: order_001" \ -H "Content-Type: application/json" \ -d '{"amount":"25.000000","chain":"eth"}'

curl -X POST https://api.nity0x.io/v1/webhooks \ -H "Authorization: Bearer mnt_test_sk_..." \ -H "Content-Type: application/json" \ -d '{ "url": "https://yourapp.com/webhooks/nityox", "events": ["payment.confirmed", "payment.failed", "payout.confirmed"] }'

import crypto from "crypto"; export async function POST(req: Request) { const body = await req.text(); const sig = req.headers.get("nityox-signature") ?? ""; const expected = crypto .createHmac("sha256", process.env.NITYOX_WEBHOOK_SECRET!) .update(body) .digest("hex"); const valid = crypto.timingSafeEqual( Buffer.from(sig), Buffer.from(expected) ); if (!valid) return new Response("Invalid signature", { status: 400 }); const event = JSON.parse(body); // handle event.type, e.g. "payment.confirmed" return new Response("ok", { status: 200 }); }

curl -X POST https://api.nity0x.io/v1/payouts \ -H "Authorization: Bearer mnt_test_sk_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: payout_20260619_001" \ -d '{ "chain": "eth", "to_address": "0xYourWallet...1234", "amount": "100.000000", "description": "Weekly settlement" }'

Build with NITY0X

Accept your first payment

Verify webhook signatures

Send a payout

Accept your first payment

Create an API key

Create a payment

Send the customer to checkout

Confirm the payment

Verify webhook signatures

Register an endpoint

Never trust a delivery you haven't verified

Respond fast, handle idempotently

Send a payout

Confirm you have a settled balance

Create the payout

Mind the rate limit

Build with NITY0X

Accept your first payment

Verify webhook signatures

Send a payout

Accept your first payment

Create an API key

Create a payment

Send the customer to checkout

Confirm the payment

Verify webhook signatures

Register an endpoint

Never trust a delivery you haven't verified

Respond fast, handle idempotently

Send a payout

Confirm you have a settled balance

Create the payout

Mind the rate limit