API reference

Base URL: https://api.toknex.space. All requests and responses are JSON over HTTPS. The machine-readable spec is at /docs/openapi.yaml.

Authentication

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create and revoke keys in your dashboard under API keys. Keys are secret: use them from your server only. If an IP allow-list is set under Account, requests from other IPs are rejected with 403.

Note: sk_test_ keys behave exactly like live keys on this deployment: the label is only there to help you organise keys. For a sandbox on BSC testnet, ask us for the staging URL.

Conventions

• Amounts are decimal strings ("500.000000000000000000") plus amount_raw, the exact integer in token base units (USDT on BSC has 18 decimals). Never use floats.
• Ids: {id} in user paths accepts our numeric user id or your external_id.
• Timestamps are ISO-8601 in UTC.
• Addresses are returned in checksum format (mixed case). Compare them case-insensitively.
• Idempotency: POST requests accept Idempotency-Key: <8–100 chars of A-Z a-z 0-9 _ - : .>. Repeating a request with the same key and body returns the original response, with the header Idempotent-Replayed: true. The same key with a different body returns 422 idempotency_conflict. Keys are kept for 7 days.
• Rate limit: account-configured rate limit requests per minute per key. Above that you get 429 rate_limited with retry_after (seconds).
• Pagination (list endpoints): limit (1–100, default 50), starting_after=<id> (older items) or since_id=<id> (newer items). Responses contain data and has_more.

Errors

{ "error": { "code": "validation_failed", "message": "Validation failed.", "fields": { "email": "Enter a valid email address." } } }

Status

GET /api/v1/status

Public (no key). Network and service status.

{ "network": "BSC", "network_name": "BNB Smart Chain", "chain_id": 56, "token": "USDT", "token_standard": "BEP-20",
  "token_contract": "0x55d3…", "required_confirmations": account-configured confirmations, "minimum_deposit": "account-configured min deposit", "collection_paused": false }

When collection_paused is true, show customers a notice and ask them not to send funds until it is false again.

Users

POST /api/v1/users

Create a customer and (by default) their deposit address. If external_id already exists, the existing user is returned with 200 instead of 201.

Response 201: the user object plus deposit_wallet (see below).

GET /api/v1/users/{id}

{ "id": 4821, "external_id": "10025", "name": "Asha Patel", "email": "[email protected]", "status": "ACTIVE", "created_at": "2026-10-25T09:00:00+00:00" }

POST /api/v1/users/{id}/deposit-wallet · GET /api/v1/users/{id}/deposit-wallet

POST creates the address if the user has none (201), otherwise returns it (200). GET returns 404 if none exists yet.

{ "user_id": 4821, "external_id": "10025", "network": "BSC", "network_name": "BNB Smart Chain", "chain_id": 56,
  "token": "USDT", "token_standard": "BEP-20", "token_contract": "0x55d398326f99059fF775485246999027B3197955",
  "deposit_address": "0x3fA1…", "deployed": false, "status": "ACTIVE",
  "minimum_deposit": "account-configured min deposit", "required_confirmations": account-configured confirmations, "qr_payload": "0x3fA1…" }

GET /api/v1/users/{id}/balance

{ "user_id": 4821, "token": "USDT",
  "confirmed_balance": "500.000000000000000000", "confirmed_balance_raw": "500000000000000000000",
  "pending_confirmation": "0.000000000000000000", "pending_confirmation_raw": "0",
  "awaiting_collection": "500.000000000000000000", "awaiting_collection_raw": "500000000000000000000" }

confirmed_balance is the total of all confirmed, credited deposits for this customer (lifetime). Keep your own spendable balance in your system.

GET /api/v1/users/{id}/deposits

A list of deposit objects for one customer (pagination and status filter supported).

GET /api/v1/users/{id}/collections

Sweeps of this customer's address to the treasury: id, tx_hash, amount, amount_raw, treasury_address, status, block_number, confirmed_at.

POST /api/v1/users/{id}/portal-link

One-time link to the hosted deposit page (valid 30 minutes, single use).

{ "url": "https://api.toknex.space/portal/link/…", "expires_at": "2026-10-25T09:30:00+00:00" }

Deposits

GET /api/v1/deposits

All deposits across your customers. Query: status, limit, starting_after, since_id.

GET /api/v1/deposits/{depositId}

The deposit object

Merchant balance

GET /api/v1/balance

{ "token": "USDT", "balance": "1234.500000000000000000", "balance_raw": "1234500000000000000000", "available_for_settlement": "1234.500000000000000000" }

Payouts are requested in the dashboard under Settlements. See Fees & settlements.

Webhooks

Event types: deposit.detected, deposit.confirmed, deposit.collected, settlement.approved, settlement.paid, ping. See Webhooks for the payloads, signature verification and retries.