Integrate crypto deposit wallets

Overview

JSON API with UTF-8 encoding. CORS allows browser requests with the proper headers. Paths below are relative to the base URL.

Quick start

curl -X POST "https://nxtgatew.com/api/v1/wallets/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -H "X-API-Secret: YOUR_SECRET" \
  -d '{
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "callback": "https://your-site.com/webhooks/nxtgatew",
    "network": "polygon",
    "mode": "ephemeral"
  }'

Authentication

Every merchant endpoint requires both headers:

X-API-Key: YOUR_KEY
X-API-Secret: YOUR_SECRET

Endpoints

All endpoints require X-API-Key + X-API-Secret.

Create deposit wallet

Verify split configuration

Webhooks

The callback URL receives POST JSON. If ipn_token was set, verify header X-IPN-Token.

When you send transaction_id on create, the same value is included on every webhook for that deposit cycle — use it to match IPNs to your internal order (especially client reusable wallets where wallet_id and client_id repeat).

Common fields: wallet_id, deposit_address, ipn_token, wallet_mode, client_id (client mode), transaction_id (when provided on create).

Failed deliveries are retried via cron/dispatch-wallet-webhooks-web.php?token=… (same CRON_SECRET_TOKEN as other URL crons).

Content-Type: application/json
X-IPN-Token: <ipn_token>

Common errors

{
  "success": false,
  "error": "Human-readable message explaining the issue"
}

Wallet lifecycle

Explorer sync indexes deposits; split cron distributes to merchant / platform / affiliates. In client mode, reuse the same address only after the previous cycle reaches split. Send a new transaction_id on each POST /wallets/create so webhooks map to the correct merchant order.

NFT / SBT module

Self-serve NFT layer under /api/v1/nft/* for any registered merchant. Supported asset types: membership (soulbound), digital_license, order_receipt (one NFT per order), plus reward / certificate / collectible. It does not change POST /api/v1/wallets/create.

Mint modes A & B

Two complementary paths. Pick one per payment — never both for the same purchase (that would double-mint).

Mode A — typical flow

1. Optional: POST /wallets/create if you also settle native crypto to a deposit + split.
2. POST /nft/wallets → recipient wallet_id.
3. After payment confirmed → POST /nft/nfts with Idempotency-Key = your order id.
4. Handle nft.minted (or poll GET /operations/{id}).

Mode B — typical flow

1. Collection contract_address set; external minter allowed on-chain if required.
2. External tx mints NFT to the user wallet (same contract as the collection).
3. POST /nft/nfts/import with tx_hash, collection_id, asset_type, rich attributes (name, order_ref, …).
4. Do not call POST /nft/nfts for that tx.

NFT quick start (Mode A)

curl -X POST "$BASE/api/v1/nft/nfts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: KEY" -H "X-API-Secret: SECRET" \
  -H "Idempotency-Key: order_89452_membership" \
  -d '{
    "asset_type": "membership",
    "collection_id": "col_xxx",
    "wallet_id": "wal_xxx",
    "external_user_id": "usr_84521",
    "external_reference": "order_89452",
    "transfer_policy": "soulbound",
    "attributes": {
      "name": "MembershipBronze_usr_84521",
      "membership_level": "bronze",
      "user_id": "usr_84521"
    }
  }'

Mode B import example:

curl -X POST "$BASE/api/v1/nft/nfts/import" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: KEY" -H "X-API-Secret: SECRET" \
  -H "Idempotency-Key: import_0xabc…" \
  -d '{
    "tx_hash": "0x…",
    "collection_id": "col_xxx",
    "network": "polygon",
    "asset_type": "order_receipt",
    "external_user_id": "usr_84521",
    "external_reference": "order_89452",
    "attributes": {
      "name": "Order_order_89452",
      "order_ref": "order_89452",
      "user_id": "usr_84521",
      "amount_pol": "10.5",
      "payment_rail": "external_checkout"
    }
  }'

NFT auth & HMAC

Same X-API-Key + X-API-Secret as deposit wallets. Write ops that create side effects also require Idempotency-Key.

Optional NxtGateW HMAC — if you send X-Api-Signature (or X-Signature), also send X-Timestamp (±5 min) and unique X-Nonce. Replay of a nonce → 401.

METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256(raw_body)
# HMAC-SHA256 hex with api_secret
# PATH example: /api/v1/nft/nfts
# macOS LibreSSL: use awk '{print $NF}' on openssl dgst -hex output

NFT endpoints (summary)

Paused collection → mint rejected. One active membership NFT per wallet (NFT_ALREADY_EXISTS).

NFT webhooks

Register with POST /api/v1/nft/webhooks (url, optional secret, subscribed_events). Manage with PATCH /webhooks/{id} (rotate_secret, status) or DELETE (soft-disable). Deliveries are signed:

X-NxtGateW-Event-Id: evt_…
X-NxtGateW-Timestamp: <unix>
X-NxtGateW-Signature: sha256=<HMAC(timestamp + "." + body, endpoint_secret)>

Local smoke catcher: /tools/webhook-catcher.php (writes logs/webhook-catcher.log). Prefer your own URL over httpbin (often times out).