Документация API

Введение

Waltix API позволяет принимать и отправлять криптовалюту программно: создавать адреса и счета для депозитов, инициировать выводы, получать тарифы и обрабатывать подписанные вебхуки. Все эндпоинты работают поверх одного базового URL.

Базовый URL всех запросов:

https://waltix.io/api

Поддерживаемые сети

USDT в сетях BEP20 и TRC20, BNB (BEP20) и BTC. Полный актуальный список идентификаторов символов возвращает GET /symbol/.

Подпись и ключи

Ключи

Заголовки запроса

Алгоритм подписи

1. Соберите объект из полей params, body и path:

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

• params — query string как в URL (search_query=foo, без ?)
• body — JSON тела запроса; {} если тела нет
• path — полный путь запроса с префиксом /api/, например /api/user/balance/

1. Сериализуйте: json.dumps(data, separators=(",", ":"), sort_keys=True)
2. Вычислите подпись:

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

Пример: GET баланс

# 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>"

Пример: POST адрес

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: генерация подписи

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: генерация подписи

$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);

Вебхуки

На ваш callback_url приходит POST. Подпись проверяется ключом callback_key по заголовкам X-Signature и X-Timestamp. Допустимое отклонение timestamp: ±15 секунд.

Данные для подписи

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

• params — query string вашего endpoint
• body — распарсенное JSON тело POST
• поле path не используется
• для подписи используется callback_key

Webhook депозита / вывода

В теле POST передаётся JSON-объект транзакции (поля описаны в соответствующих разделах). Для проверки подписи объект помещается в поле body, поле params оставляют пустым.

Webhook счёта (invoice)

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

Тело POST совпадает с объектом подписи: на верхнем уровне поля params и body. Для проверки используйте распарсенное тело запроса целиком, без дополнительной обёртки.

Python: проверка 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 повторяется автоматически. Если сервер уже ответил 2xx на первый webhook, повтор при смене статуса на executed не отправляется. При AML или ожидании подтверждений первый webhook может прийти со статусом pending. Актуальный статус запрашивайте через GET /user/transaction/.

Депозиты

Депозит регистрируется после on-chain перевода на адрес, полученный через API. Сканер блокчейна создаёт транзакцию с типом deposit.

1. Создайте адрес: POST /user/address/ или счёт POST /invoice/.
2. Плательщик отправляет перевод on-chain на выданный адрес.
3. Сканер фиксирует депозит. Если указан callback_url, отправляется webhook.

Эндпоинты

• POST/user/address/Постоянный адрес
• GET/user/address/Список адресов
• GET/user/address/balance/{symbol_id}/Последний адрес пополнения по символу
• POST/invoice/Счёт с адресом
• GET/invoice/Список счетов
• GET/invoice/my/{invoice_id}/Один счёт
• GET/invoice/{invoice_id}/transactions/Депозиты по счёту
• GET/symbol/Список доступных символов
• GET/user/transaction/История (type=deposit)
• GET/user/transaction/{encoded_id}/Одна транзакция

POST /user/address/ — запрос

POST /user/address/ — ответ

POST /invoice/ — запрос

GET /user/transaction/ — фильтры депозитов

Webhook депозита — тело

{
  "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"
}

Статусы депозита (on-chain / счёт)

Статусы счёта

Выводы

Эндпоинты

• POST/user/balance/withdrawal/Создать вывод
• GET/user/transaction/?type=withdrawalИстория и статус
• GET/user/transaction/{encoded_id}/Одна транзакция
• GET/symbol/Список доступных символов

POST /user/balance/withdrawal/ — query

POST /user/balance/withdrawal/ — запрос

Приоритет комиссии BTC (extra.fee_mode)

Если fee_mode не передан или значение неизвестно, используется серверный дефолт (economyFee). Markup по режимам можно посмотреть в GET /blockchain/ → settings.service_fee_markup_by_fee_mode для сети BTC. Для сетей кроме BTC поле игнорируется.

Ошибки

Webhook вывода — тело

Отправляется один раз при переходе вывода в статус executed. JSON-объект транзакции с type: withdrawal.

Статусы вывода

Ограничения

Тарифы и комиссии

Эндпоинты

• GET/setting/fees/Тарифы по символам (публичный API, API key)
• GET/setting/fees/my/Тарифы текущего пользователя (сессия ЛК)

GET /setting/fees/ доступен без сессии, с API key. Query-параметры user_id и tariff_id — для админского просмотра конкретных override (обычно не нужны интегратору).

Поля ответа FeesSettingsDTO