TopUP API

Version 1. Every field in the API reference is checked automatically against the implementation, so the reference and the API cannot drift apart.

Overview

• Network and token: USDT on TRON (TRC20) only. Amounts are decimal strings with up to 6 decimals, e.g. "100.5".
• Base URL: https://{BASE_URL}/api/v1/ — every path ends with "/". Requests without the trailing slash are redirected, which some HTTP clients do not follow for POST.
• Collect by customer: each of your customers gets one permanent address (deposit callbacks). With order mode on, create orders for a customer and deposits are matched to them automatically (order-matched callbacks).
• A deposit counts after 19 confirmations (about 1 minute). Callbacks are normally sent within 2 minutes of payment.
• Every withdrawal is reviewed manually. Working hours are 8:00–23:00 (UTC+8): requests in working hours are processed within 1 hour; others at the start of the next working period.

Authentication

Every request carries three headers. The Secret is shown once in the dashboard (API settings); keep it on your server only.

Node.js

import crypto from 'node:crypto';

const BASE = process.env.TOPUP_BASE || 'https://{BASE_URL}/api/v1/';
const KEY = process.env.TOPUP_KEY, SECRET = process.env.TOPUP_SECRET;

async function topup(method, path, body) {
  const ts = Math.floor(Date.now() / 1000).toString();
  const raw = body ? JSON.stringify(body) : '';
  const bodyHash = crypto.createHash('sha256').update(raw).digest('hex');
  const url = new URL(path, BASE);
  const toSign = [ts, method, url.pathname + url.search, bodyHash].join('\n');
  const sig = crypto.createHmac('sha256', SECRET).update(toSign).digest('hex');
  const res = await fetch(url, {
    method,
    headers: {
      'content-type': 'application/json',
      'X-TopUP-Key': KEY, 'X-TopUP-Timestamp': ts, 'X-TopUP-Signature': sig,
      ...(method === 'POST' ? { 'Idempotency-Key': crypto.randomUUID() } : {}),
    },
    body: raw || undefined,
  });
  return res.json();
}

const order = await topup('POST', 'orders/', { customer_id: 'user_88213', merchant_order_no: `ACME-${Date.now()}`, amount: '100.00' });
console.log(order.pay_url);

Python

import hashlib, hmac, json, os, time, uuid, requests

BASE = os.environ.get("TOPUP_BASE_URL", "https://{BASE_URL}")
KEY, SECRET = os.environ["TOPUP_KEY"], os.environ["TOPUP_SECRET"].encode()

def topup(method, path, body=None):
    ts = str(int(time.time()))
    raw = json.dumps(body, separators=(",", ":")) if body else ""
    body_hash = hashlib.sha256(raw.encode()).hexdigest()
    to_sign = "\n".join([ts, method, "/api/v1/" + path, body_hash])
    sig = hmac.new(SECRET, to_sign.encode(), hashlib.sha256).hexdigest()
    headers = {"content-type": "application/json", "X-TopUP-Key": KEY,
               "X-TopUP-Timestamp": ts, "X-TopUP-Signature": sig}
    if method == "POST":
        headers["Idempotency-Key"] = str(uuid.uuid4())
    return requests.request(method, BASE + "/api/v1/" + path, data=raw or None, headers=headers).json()

print(topup("GET", "balance/"))

Orders

POST /api/v1/orders/
{
  "customer_id": "user_88213",          // required: your own ID for this customer
  "customer_name": "Lin Trading",       // optional, used only if the customer is new
  "customer_email": "lin@lintrading.example",
  "merchant_order_no": "ACME-88513",
  "amount": "100.00"
}

{
  "order_no": "ORD-20260929-0413",
  "merchant_order_no": "ACME-88513",
  "customer_id": "user_88213",
  "amount": "100.00",
  "matched": "0.00",
  "address": "TMa7yK2d9Qp4XvB8sN1cF6rH3wZ5jL0eUt",   // the customer's permanent address
  "network": "TRON",
  "token": "USDT",
  "status": "pending",
  "created_at": "2026-09-29T09:00:00.000Z",
  "expires_at": "2026-09-29T09:30:00.000Z",
  "deposits": [],
  "pay_url": "https://{BASE_URL}/pay/ORD-20260929-0413/"
}

• customer_id is required. A new customer_id creates the customer and its permanent address. merchant_order_no must be unique in your account.
• The expiry time and matching thresholds are set for your account by the platform (shown in API settings). Orders require order mode; otherwise the endpoint returns 403 order_mode_disabled.
• Send your customer to pay_url, or show the address yourself.
• The response can already show status completed if earlier deposits from this customer matched when the order was created. See Matching rules.

Customers

POST /api/v1/customers/
{ "customer_id": "user_88213", "name": "Lin Trading", "email": "lin@lintrading.example" }

→ {
  "customer_id": "user_88213", "name": "Lin Trading", "email": "lin@lintrading.example", "remark": "",
  "address": "TXk8fQ2m9sR7ZcY1hN4vB6pW3aLd5Z3wQe",
  "total": "0.00", "count": 0, "fees": "0.00", "unmatched": "0.00",
  "last_payment_at": null, "created_at": "2026-09-11T02:10:00.000Z"
}

• Each customer has one permanent address. Every payment to it belongs to that customer, with or without an order. customer_id cannot be changed.
• Payments under 1 USDT are not credited, not matched, trigger no callback and do not appear in your deposits or exports (they are usually spam "dust" transfers).
• customers/stats/ returns received, count, fees and unmatched for a period.

Matching rules

Matching only links deposits to orders; it never changes your balance. It happens only within the same customer, in both directions:

• Deposit first reaches an open order: the deposit goes to the open order where the running total lands between the lower (L) and upper (H) thresholds; otherwise to the oldest open order.
• Order created after deposits: unmatched deposits from the look-back window are added from the oldest; if the total reaches L without exceeding H they are matched, otherwise none are.
• Status: total < L = partial (keeps waiting), L ≤ total ≤ H = completed, total > H = overpaid; at expiry an order below L becomes expired (nothing received) or expired_partial.
• Payments after expiry stay unmatched; match them manually with orders/match/ if needed. Avoid two open orders with similar amounts for the same customer.

Balance & ledger

GET balance/ returns { "available": "48215.40", "frozen": "1002.00" }. The ledger is append-only; each entry has type deposit, fee_in, freeze, unfreeze, withdraw or fee_out. Lists are paginated with cursor.

Withdrawals

POST /api/v1/withdrawals/
{
  "kind": "payout",              // "payout" = to your customer, "cashout" = to your registered wallet
  "customer_id": "user_88213",   // optional, for payouts
  "to": "TXk8fQ2m9sR7ZcY1hN4vB6pW3aLd5Z3wQe",
  "amount": "1000.00",
  "merchant_ref": "PAYOUT-7781"
}

→ {
  "withdrawal_no": "WD-20260929-7F3A21", "kind": "payout", "customer_id": "user_88213",
  "to": "TXk8fQ2m9sR7ZcY1hN4vB6pW3aLd5Z3wQe", "amount": "1000.00", "fee": "2.00",   // 1002.00 is frozen
  "status": "pending", "txid": null, "reason": null, "merchant_ref": "PAYOUT-7781", "source": "api",
  "created_at": "2026-09-29T09:12:00.000Z"
}

• API withdrawals require an IP whitelist (API settings). Without one, the endpoint returns 403 ip_not_allowed.
• Amount + fee is frozen on submit and released if the request is rejected or cancelled.
• Status: pending → approved → broadcast → completed, or rejected / cancelled / failed. Each change sends a withdrawal.updated callback.

Callbacks

POST https://your-server.example/callback
X-TopUP-Timestamp: 1790665800
X-TopUP-Signature: 5f1c…

{
  "id": "evt_9f2a02",
  "type": "order.matched",       // deposit | order.matched | withdrawal.updated
  "created_at": "2026-09-29T09:10:03Z",
  "data": {
    "order_no": "ORD-20260929-0409",
    "merchant_order_no": "ACME-88509",
    "customer_id": "user_88213",
    "status": "completed",       // pending | partial | completed | overpaid | expired | expired_partial
    "amount": "500.00",
    "matched": "500.00",
    "created_at": "2026-09-29T09:05:00.000Z",
    "expires_at": "2026-09-29T09:35:00.000Z",
    "deposits": [{ "id": "1042", "txid": "a3c1…", "amount": "500.00", "matched_by": "deposit", "time": "2026-09-29T09:10:00.000Z" }],
    "manual": false
  }
}

Signature: hex( HMAC-SHA256( Secret, timestamp + "\n" + raw_body ) ). Reply with any 2xx status. Otherwise we retry 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h after the first attempt, then stop; you can resend from the dashboard. The same event can arrive more than once: deduplicate by id.

import crypto from 'node:crypto';

// Verify a TopUP callback. rawBody must be the exact request body you received,
// not an object you parsed and serialised again.
export function verifyCallback(secret, timestamp, signature, rawBody) {
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}\n${rawBody}`).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(String(signature || ''));
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express example:
// app.post('/callback', express.raw({ type: 'application/json' }), (req, res) => {
//   if (!verifyCallback(SECRET, req.get('X-TopUP-Timestamp'), req.get('X-TopUP-Signature'), req.body)) return res.sendStatus(401);
//   const event = JSON.parse(req.body); // the same event may arrive more than once: deduplicate by event.id
//   res.sendStatus(200);
// });

Callback body

deposit

A payment of 1 USDT or more to a customer address is credited. data fields:

order.matched

An order changes because deposits were matched or unmatched. data fields:

withdrawal.updated

A withdrawal is created or changes status. data fields:

API reference

Amounts are decimal strings in USDT (e.g. "100.50"); times are ISO 8601 in UTC. Lists return { items, next_cursor }: pass next_cursor as cursor to get the next page.

OrderDeposit

Used in the deposits array of an order.

Errors

Errors return { "error": { "code": "…", "message": "…", "field": "…" } }.

Sandbox

A sandbox is not available yet. During the early-access period, integrate on production with small amounts (for example 1 USDT).