API Documentation

Introduction

The Waltix API lets you accept and send crypto programmatically: create deposit addresses and invoices, initiate withdrawals, fetch fees and process signed webhooks. Every endpoint lives under a single base URL.

Base URL for all requests:

https://waltix.io/api

Supported networks

USDT on BEP20 and TRC20, BNB (BEP20) and BTC. The full up-to-date list of symbol identifiers is returned by GET /symbol/.

Authentication & keys

Keys

Request headers

Signing algorithm

1. Build an object from params, body and path:

{
  "params": "url_encoded_query_string",
  "body": {},
  "path": "/api/user/balance/"
}

• params — query string as in the URL (search_query=foo, without ?)
• body — JSON request body; {} if there is no body
• path — full request path with the /api/ prefix, e.g. /api/user/balance/

1. Serialize: json.dumps(data, separators=(",", ":"), sort_keys=True)
2. Compute the signature:

signature = HMAC-SHA256(key=API_KEY_SECRET, message=timestamp + json_string)

Example: GET balance

# params пустые, body {}
# path = /api/user/balance/
# data = {"body":{},"params":"","path":"/api/user/balance/"}

curl "https://waltix.io/api/user/balance/" \
  -H "X-API-Key-ID: <UUID>" \
  -H "X-Timestamp: 1718659200" \
  -H "X-Signature: <hex>"

Example: POST address

curl "https://waltix.io/api/user/address/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key-ID: <UUID>" \
  -H "X-Timestamp: 1718659200" \
  -H "X-Signature: <hex>" \
  -d '{"symbol_id":"USDTBEP20","callback_url":"https://example.com/cb","description":"shop"}'

Python: generating the signature

import hashlib, hmac, json, time

def sign(key: str, timestamp: int, data: dict) -> str:
    s = json.dumps(data, separators=(",", ":"), sort_keys=True)
    return hmac.new(key.encode(), f"{timestamp}{s}".encode(), hashlib.sha256).hexdigest()

data = {"params": "", "body": {"symbol_id": "USDTBEP20"}, "path": "/api/user/address/"}
ts = int(time.time())
signature = sign(API_KEY_SECRET, ts, data)

PHP: generating the signature

$data = ["params" => "", "body" => ["symbol_id" => "USDTBEP20"], "path" => "/api/user/address/"];
ksort($data);
$json = json_encode($data, JSON_UNESCAPED_SLASHES);
$signature = hash_hmac("sha256", time() . $json, $API_KEY_SECRET);

Webhooks

A POST is delivered to your callback_url. The signature is verified with callback_key using the X-Signature and X-Timestamp headers. Allowed timestamp drift: ±15 seconds.

Signing payload

{
  "params": "",
  "body": { }
}

• params — query string of your endpoint
• body — parsed JSON body of the POST
• the path field is not used
• callback_key is used for the signature

Deposit / withdrawal webhook

The POST body carries the transaction JSON object (fields described in the relevant sections). For signature verification the object is placed into body, while params stays empty.

Invoice webhook

{
  "params": "",
  "body": {
    "type": "invoice",
    "id": "5ca38db1-00c5-4aba-91e5-6a57bed60aee",
    "status": "executed"
  }
}

The POST body matches the signing object: params and body at the top level. Verify using the parsed request body as-is, without any extra wrapper.

Python: verifying a webhook

# Webhook депозита и вывода / Deposit & withdrawal webhook
body = await request.json()
data = {"params": request.url.query, "body": body}
verify(request.headers["X-Signature"], CALLBACK_KEY, int(request.headers["X-Timestamp"]), data)

# Webhook счёта / Invoice webhook
data = await request.json()
verify(request.headers["X-Signature"], CALLBACK_KEY, int(request.headers["X-Timestamp"]), data)

def verify(signature: str, key: str, timestamp: int, data: dict) -> bool:
    if abs(int(time.time()) - timestamp) > 15:
        return False
    expected = sign(key, timestamp, data)
    return hmac.compare_digest(expected, signature)

Webhook delivery

If your server responds with an error, the webhook is retried automatically. If your server already returned 2xx for the first webhook, no retry is sent when the status changes to executed. With AML or pending confirmations the first webhook may arrive with status pending. Query the current status via GET /user/transaction/.

Deposits

A deposit is registered after an on-chain transfer to an address obtained via the API. The blockchain scanner creates a transaction with type deposit.

1. Create an address: POST /user/address/ or an invoice: POST /invoice/.
2. The payer sends an on-chain transfer to the issued address.
3. The scanner records the deposit. If callback_url is set, a webhook is sent.

Endpoints

• POST/user/address/Permanent address
• GET/user/address/List of addresses
• GET/user/address/balance/{symbol_id}/Latest top-up address for a symbol
• POST/invoice/Invoice with an address
• GET/invoice/List of invoices
• GET/invoice/my/{invoice_id}/A single invoice
• GET/invoice/{invoice_id}/transactions/Deposits for an invoice
• GET/symbol/List of available symbols
• GET/user/transaction/History (type=deposit)
• GET/user/transaction/{encoded_id}/A single transaction

POST /user/address/ — request

POST /user/address/ — response

POST /invoice/ — request

GET /user/transaction/ — deposit filters

Deposit webhook — body

{
  "user_id": 1,
  "type": "deposit",
  "created_at": "2025-11-20T16:08:10.180830+00:00",
  "symbol_id": "USDTBEP20",
  "status": "executed",
  "amount": "4.696700000000000000",
  "service_fee": "0.803300000000000000",
  "net_amount": "5.500000000000000000",
  "blockchain_data": {
    "hash": "0xabc...",
    "from_address": "0x123",
    "to_address": "0x456"
  },
  "external_id": null,
  "callback_url": "https://example.com/cb"
}

Deposit statuses (on-chain / invoice)

Invoice statuses

Withdrawals

Endpoints

• POST/user/balance/withdrawal/Create a withdrawal
• GET/user/transaction/?type=withdrawalHistory and status
• GET/user/transaction/{encoded_id}/A single transaction
• GET/symbol/List of available symbols

POST /user/balance/withdrawal/ — query

POST /user/balance/withdrawal/ — request

BTC fee priority (extra.fee_mode)

If fee_mode is omitted or unknown, the server default (economyFee) is used. Per-mode markup is available in GET /blockchain/ → settings.service_fee_markup_by_fee_mode for the BTC network. For networks other than BTC the field is ignored.

Errors

Withdrawal webhook — body

Sent once when the withdrawal transitions to executed. Transaction JSON object with type: withdrawal.

Withdrawal statuses

Limits

Fees & pricing

Endpoints

• GET/setting/fees/Fees per symbol (public API, API key)
• GET/setting/fees/my/Current user's fees (dashboard session)

GET /setting/fees/ is available without a session, using an API key. The user_id and tariff_id query params are for admin viewing of specific overrides (usually not needed by integrators).

FeesSettingsDTO response fields