CryptoWay CryptoWay docs

CryptoWay API Documentation

Введение

API интеграции

Endpoint: https://api.cryptoway.com

CryptoWay API подписывается по схеме HMAC-SHA256. Документация состоит из четырёх разделов:

Подпись

Подпись

Ключи

КлючГде взятьДля чего
API key ID + secretЛичный кабинет, раздел API keysПодпись запросов к API
callback_keyЛичный кабинет, профильПроверка webhook

Для webhook используйте callback_key, не secret API key.

Получение ключей API

Один API key можно использовать для всех методов API, если при создании включены нужные разрешения.

Параметры при создании ключа

ПараметрОписание
descriptionНазвание ключа
allowed_ipsСписок разрешённых IP. Можно оставить пустым
is_deposit_allowedРазрешить операции с депозитами
is_withdrawal_allowedРазрешить выводы

Если allowed_ips пуст, первый успешный запрос с API автоматически добавит текущий IP в список.

Инструкция

  1. Зарегистрируйтесь в сервисе.
  2. Перейдите во вкладку «API ключи».
  3. Нажмите «Создать API ключ».
  4. Укажите название, разрешения и IP в форме создания.
  5. После сохранения сразу запишите ключи из модального окна. Secret показывается один раз.
  6. Готово.

В запросах используйте id ключа как X-API-Key-ID, secret — для подписи.

callback_key

Ключ для проверки webhook находится в профиле личного кабинета. Он не совпадает с secret API key.

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

ЗаголовокОписание
X-API-Key-IDUUID ключа
X-TimestampUnix timestamp, секунды
X-SignatureHMAC-SHA256 hex

Подпись обязательна для всех публичных эндпоинтов (метод GET, POST и др.).

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

  1. Соберите объект:
{
  "params": "url_encoded_query_string",
  "body": {},
  "path": "/user/balance/"
}
  • params — query string как в URL (search_query=foo, без ?)
  • body — JSON тела запроса; {} если тела нет
  • path — путь запроса, например /user/balance/
  1. Сериализуйте объект: json.dumps(data, separators=(",", ":"), sort_keys=True)
  2. Подпись:
signature = HMAC-SHA256(key=API_KEY_SECRET, message=timestamp + json_string)
  1. Timestamp должен быть в пределах ±15 секунд от серверного времени.

Если allowlist ключа пуст, при первом успешном запросе текущий IP записывается в allowlist. Дальнейшие запросы принимаются только с IP из списка.

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

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

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

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

curl "https://api.cryptoway.com/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"}'

Генерация подписи

:::tabs

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": "/user/address/"}
ts = int(time.time())
signature = sign(API_KEY_SECRET, ts, data)
$data = ["params" => "", "body" => ["symbol_id" => "USDTBEP20"], "path" => "/user/address/"];
ksort($data);
$json = json_encode($data, JSON_UNESCAPED_SLASHES);
$signature = hash_hmac("sha256", time() . $json, $API_KEY_SECRET);

:::

Webhook: проверка подписи

На ваш callback_url приходит POST.

Заголовки:

ЗаголовокОписание
X-SignatureHMAC-SHA256 hex
X-TimestampUnix timestamp

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

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

Допустимое отклонение timestamp: ±15 секунд.

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 депозита и вывода:

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 счёта:

data = await request.json()
verify(request.headers["X-Signature"], CALLBACK_KEY, int(request.headers["X-Timestamp"]), data)

Общая функция verify:

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)

Депозиты

Депозиты

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

Начало работы

Перед интеграцией создайте API key (раздел «Подпись»). Без ключа запросы к API не проходят.

Выбор типа интеграции

Доступны два способа приёма депозитов.

Счёт на оплату (Invoice)

Подходит для оплаты товара или услуги на фиксированную сумму.

Создание: POST /invoice/. Укажите сумму в фиате (target_value_fiat) или в крипте (target_value_symbol).

Символ и адрес

  • Если при создании указан symbol_id, сразу генерируется адрес и ссылка pay_url.
  • Если symbol_id не указан, плательщик выбирает символ и сеть на странице оплаты. Адрес появится после выбора.

Уведомления

СобытиеWebhook
Поступил on-chain переводWebhook депозита: сумма, hash, статус транзакции
Сумма по счёту набранаWebhook счёта: status: executed
Истёк срок счёта без полной оплатыWebhook счёта: status: expired

Статусы счёта: active, executed, expired, cancelled. Промежуточных статусов частичной оплаты (paid_over, wrong_amount и т.п.) нет. Частичные переводы приходят как отдельные webhook депозита; счёт переходит в executed, когда сумма депозитов достигает цели, или в expired по deadline_at.

Постоянный адрес

Подходит для пополнения баланса без фиксированной суммы.

Создание: POST /user/address/. Укажите symbol_id и при необходимости external_id (ваш идентификатор адреса).

На адрес можно отправлять переводы любой суммы выше min_deposit_amount. Каждый перевод создаёт депозит и отдельный webhook.

Общий порядок

  1. Создайте счёт или постоянный адрес.
  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/user/transaction/История (type=deposit)
GET/user/transaction/{encoded_id}/Одна транзакция

POST /user/address/

Запрос

ПолеТипОписание
symbol_id*stringИдентификатор символа: валюта в конкретной сети, например USDTBEP20, BNBBEP20. Список значений: GET /symbol/ (раздел 4)
callback_urlstringURL для webhook депозита
descriptionstringМетка адреса
external_idstringВаш ID

Виртуальные символы (USDT) не принимаются. Указывайте символ с привязкой к сети.

Ответ

ПолеОписание
idID адреса
valueАдрес кошелька
symbol_idИдентификатор символа
callback_urlURL webhook
external_idВаш ID
created_atДата создания

POST /invoice/

Запрос

ПолеТипОписание
name*stringНазвание
symbol_idstringИдентификатор символа для оплаты
target_value_fiatdecimalСумма в фиате
target_currency_fiatstringФиат, по умолчанию USD
target_value_symboldecimalСумма в крипте
deadline_atdatetimeСрок счёта
callback_urlstringURL webhook статуса счёта
external_idstringВаш ID
is_payer_feeboolКомиссию платит плательщик
descriptionstringОписание

Нужно указать target_value_fiat или target_value_symbol.

Ответ

Адрес оплаты в target_wallet.value, текущий status, ссылка на оплату в pay_url.

GET /user/transaction/

Фильтры для депозитов:

ПараметрОписание
typedeposit
symbol_idИдентификатор символа
external_idВаш ID
statuspending, executed, dirty_lock, cancelled
in_processingtrue — только транзакции в обработке; false — завершённые
begin_at, end_atПериод

Webhook депозита

POST на callback_url, указанный при создании адреса. Для депозита по счёту используется callback_url счёта.

Тело (основные поля):

ПолеОписание
typedeposit
statusСтатус транзакции
symbol_idИдентификатор символа
amountСумма зачисления на баланс
service_feeКомиссия сервиса
net_amountСумма on-chain перевода (amount + service_fee)
blockchain_data.hashTx hash
blockchain_data.from_addressОтправитель
blockchain_data.to_addressПолучатель (ваш адрес)
external_idВаш ID из адреса
invoiceДанные счёта, если депозит по invoice
aml_orderСтатус AML, если проверка включена
callback_orderСтатус последней доставки webhook (last_status_code, last_response_data)

Пример

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

Webhook счёта

Отдельный callback при смене статуса счёта (executed, expired). Формат тела и проверка подписи описаны в разделе «Webhook счёта (invoice)».

Статусы депозита

statusОписание
pendingОжидание AML или подтверждений сети
executedЗачислено на баланс
dirty_lockАдрес помечен dirty, депозит заблокирован
cancelledОтменён

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

statusОписание
activeОжидает оплаты
executedОплачен
expiredИстёк срок
cancelledОтменён

Доставка webhook

При неуспешном ответе вашего сервера webhook повторяется автоматически.

Если сервер уже ответил 2xx на первый webhook, повтор при смене статуса на executed не отправляется. При AML или ожидании подтверждений первый webhook может прийти со статусом pending.

Актуальный статус транзакции запрашивайте через GET /user/transaction/ или GET /user/transaction/{encoded_id}/.

Минимальная сумма

Депозиты ниже min_deposit_amount игнорируются. Актуальное значение: GET /setting/fees/ (раздел 4).

Выводы

Выводы

Эндпоинты

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

Отдельного GET /withdrawal/{id} нет. Используйте transaction API.

POST /user/balance/withdrawal/

Query

ПараметрОписание
totp_codeOTP из email. Не нужен при авторизации API key

Запрос

ПолеТипОписание
symbol_id*stringИдентификатор символа, например USDTTRC20. Список значений: GET /symbol/ (раздел 4)
to_address*stringАдрес получателя
amount*decimalСумма получателю (net)
external_idstringВаш ID
callback_urlstringURL webhook
extra.memostringMemo/tag (если сеть поддерживает)

Виртуальные символы не принимаются.

Комиссия списывается сверх amount. С баланса уходит amount + service_fee.

Ответ

JSON-объект транзакции: "type": "withdrawal", текущий статус вывода в status, идентификатор в encoded_id.

Ошибки

detailПричина
Insufficient balanceНедостаточно средств
Invalid addressНеверный адрес
Minimum withdrawal amount is ...Ниже минимума
TOTP code is requiredНужен totp_code без API key
MEMO doesn't supported on this chain!Memo не поддерживается

Rate limit: 15 запросов за 15 секунд.

GET /user/transaction/

ПараметрОписание
typewithdrawal
statusСтатус вывода
in_processingtrue — только выводы в обработке
external_idВаш ID

Webhook вывода

Отправляется один раз при переходе вывода в статус executed.

Тело

JSON-объект транзакции с "type": "withdrawal". Поля совпадают с объектом в webhook депозита.

ПолеОписание
amountСумма транзакции (получатель + комиссия)
service_feeКомиссия
net_amountСумма получателю (amount - service_fee)
statusexecuted
blockchain_data.hashTx hash
to_addressАдрес получателя
memoMemo, если был
external_idВаш ID

Подпись проверяется ключом callback_key по заголовкам X-Signature, X-Timestamp и структуре данных с полями params и body.

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

statusОписание
compliance_approve_requiredОжидает ручного одобрения
createdВ очереди
aml_order_pendingAML проверка
prepare_pendingПодготовка транзакции
ready_to_transferГотов к отправке
transfer_lockОтправка в сеть
pendingОжидание подтверждений
swap_lockОжидание autoswap
executedВыполнен
cancelledОтменён админом
cancelled_by_riskОтменён по AML
failedОшибка

Фильтр in_processing=true возвращает все статусы, кроме executed, cancelled, cancelled_by_risk, failed.

Ограничения

ПараметрОписание
min_withdrawal_amountМинимум по символу и тарифу. Значение: GET /setting/fees/
withdrawal_fee_amountФиксированная комиссия
withdrawal_fee_percentageПроцент комиссии
totp_codeОбязателен без API key (email OTP, 10 мин)

Повтор запроса с тем же external_id не является идемпотентным.

Справочные эндпоинты

Справочные эндпоинты

Вспомогательные методы, на которые ссылаются операции из других разделов.

Эндпоинты

МетодПутьОписание
GET/symbol/Список символов
GET/symbol/fiat/Список поддерживаемых фиатных валют
GET/user/balance/Баланс по символам
GET/setting/fees/Комиссии и лимиты
GET/currency/rate/Курсы валютных пар
GET/currency/rate/hedge/Курсы к USDT (источник aster_dex)

GET /symbol/

Используйте для получения допустимых значений symbol_id при создании адреса, счёта или вывода.

Query

ПараметрОписание
pageНомер страницы, по умолчанию 1
per_pageРазмер страницы, по умолчанию 100
search_queryПоиск по id, name, short_name
order_typesymbol, short_name, name
order_ascСортировка по возрастанию, по умолчанию true

Ответ

Пагинированный список. Каждый элемент:

ПолеОписание
idИдентификатор символа для API (symbol_id)
nameПолное название
short_nameКраткое название валюты
blockchainСеть: id, name, ссылки на explorer
is_activeДоступен ли символ
is_virtualВиртуальный символ (для API не используйте)
group_symbol_idГруппа баланса, если символ сгруппирован
balance_symbol_idСимвол, по которому ведётся баланс
contract_addressАдрес контракта токена, если есть
precisionТочность

Для запросов с symbol_id выбирайте записи с is_virtual: false и is_active: true.

GET /symbol/fiat/

Список кодов фиатных валют для поля target_currency_fiat при создании счёта.

Ответ

Массив строк, например ["USD", "EUR", ...].

GET /user/balance/

Текущий баланс аккаунта. Удобно перед созданием вывода.

Query

ПараметрОписание
search_queryФильтр по symbol_id

Ответ

Массив объектов:

ПолеОписание
symbol_idИдентификатор символа
valueДоступный баланс

Rate limit: 30 запросов в минуту.

GET /setting/fees/

Комиссии и минимальные суммы по символам.

Query

ПараметрОписание
user_idID пользователя для персональных настроек
tariff_idID тарифа

Без параметров возвращаются глобальные значения. Передайте свой user_id, чтобы получить актуальные лимиты и комиссии.

Ответ

Массив объектов по символам:

ПолеОписание
symbol_idИдентификатор символа
min_deposit_amountМинимальный депозит
min_withdrawal_amountМинимальный вывод
deposit_fee_amountФиксированная комиссия депозита
deposit_fee_percentageПроцент комиссии депозита
withdrawal_fee_amountФиксированная комиссия вывода
withdrawal_fee_percentageПроцент комиссии вывода

GET /currency/rate/

Курсы валютных пар.

Query

ПараметрОписание
sourceИсточник: coingecko или aster_dex. Без параметра — все источники

Ответ

Массив объектов:

ПолеОписание
from_symbol_idsymbol_id криптовалюты или код фиата (для пар фиат→фиат)
to_symbol_nameКод валюты котировки: фиат (USD, EUR, ...) или USDT
valueКурс: сколько единиц to_symbol_name за 1 единицу from_symbol_id
sourcecoingecko или aster_dex
created_atВремя обновления

Примеры пар

sourcefrom_symbol_idto_symbol_nameСмысл
coingeckoUSDTBEP20USDКриптосимвол к фиату
coingeckoUSDEURФиат к фиату
aster_dexBTCUSDTКриптосимвол к USDT

GET /currency/rate/hedge/

Только курсы from_symbol_idUSDT из источника aster_dex. Формат ответа совпадает с GET /currency/rate/.

Premium Exchange

Как подключить к Premium Exchanger

Подключение CryptoWay к обменному пункту на скрипте Premium Exchanger (v 2.7) — двумя модулями:

  • Мерчант (приём средств) — принимает средства от клиента на ваши счета и автоматически переводит заявку в статус «Оплаченная заявка».
  • Автовыплата — выплачивает средства клиенту с ваших счетов.

Вместе они дают полную автоматизацию обмена. Можно подключить только один модуль — тогда автоматизируется только приём или только выплата.

Полная документация Premium Exchanger: Модули мерчантов и автовыплат

Что понадобится

  • Обменник на Premium Exchanger 2.7.x. Модули несовместимы между версиями: на скрипте 2.7 нужны модули 2.7.*, иначе сайт не откроется.
  • Доступ к серверу через ISP Manager из-под пользователя сайта (не root).
  • API-ключ CryptoWay с разрешениями на депозиты и выводы — API key ID и secret (см. Подпись).

Шаг 1. Файлы модулей

МодульАрхивНазначение
Мерчант (приём средств)m_cryptoway_271.zipПриём криптоплатежей
Автовыплатыpay_cryptoway_271.zipАвтоматические выплаты

Версия модуля должна совпадать с версией вашего скрипта Premium Exchanger (например, 271 — под 2.7.\*).

Шаг 2. Загрузка на сервер

Перед изменением файлов сделайте бэкап корневой папки сайта. Работайте через ISP Manager из-под пользователя сайта (не root).

  1. Папку cryptoway из m_cryptoway_271.zip загрузите в /wp-content/plugins/premiumbox/merchants.
  2. Папку cryptoway из pay_cryptoway_271.zip загрузите в /wp-content/plugins/premiumbox/paymerchants.
  3. При окне о совпадении файлов — нажмите «Заменить».

Шаг 3. Добавление и настройка мерчанта

В разделе «Мерчанты» → «Мерчанты» нажмите «Добавить» (часть мерчантов создана по умолчанию). Заполните форму:

Форма добавления мерчанта в Premium Exchanger

  • Заголовок — название мерчанта в панели управления.
  • Модуль — выберите CryptoWay из выпадающего списка.
  • Статус«активный мерчант».

В настройках модуля укажите ключи из личного кабинета CryptoWay:

  • API ключAPI key ID.
  • Секретный ключsecret вашего API-ключа.

Шаг 4. Автовыплаты

Модуль автовыплат подключается так же: раздел «Автовыплаты»«Добавить», статус «активный», те же ключи CryptoWay (API key ID + secret). Привязывается на вкладке «Мерчанты и выплаты» направления — для валюты «Получаю». Перед включением ознакомьтесь с разделом «Предупреждение о рисках» в документации Premium Exchanger.

Шаг 5. Режимы работы

Изначально обменник работает в ручном режиме. С модулями:

  • Только мерчант на приём — автоматизируется приём: при поступлении средств заявка переходит в «Оплаченная заявка», выплату вы делаете вручную и меняете статус на «Выполненная заявка».
  • Мерчант + автовыплата — полная автоматизация: «Оплаченная заявка» → «Ожидание подтверждения от модуля автовыплат» → «Выполненная заявка».
  • Можно включить кнопку «Перевести» в заявке даже для автоматизированного направления — оператор сможет выплатить вручную, если автовыплата не прошла.

Шаг 6. Проверка

Проверьте подключение встроенной «Диагностикой мерчанта» (Мерчанты → Мерчанты → диагностика):

Лог и диагностика мерчантов в Premium Exchanger

  • Убедитесь, что на сервере настроен планировщик задач (cron) — без него статусы заявок не меняются автоматически.
  • Если в логе ошибка вида «your IP … not in whitelist» — добавьте IP вашего сервера в whitelist API-ключа CryptoWay (параметр allowed_ips).

Introduction

API Integration

Endpoint: https://api.cryptoway.com

The CryptoWay API is signed with HMAC-SHA256. The documentation is split into four sections:

Signing

Signing

Keys

KeyWhere to find itPurpose
API key ID + secretDashboard → API keysSigning API requests
callback_keyDashboard → profileVerifying webhooks

For webhooks, use callback_key — not the secret API key.

Getting API keys

A single API key works for every API method, as long as you enable the permissions it needs when you create it.

Key creation parameters

ParameterDescription
descriptionKey name
allowed_ipsList of allowed IPs. Can be left empty
is_deposit_allowedAllow deposit operations
is_withdrawal_allowedAllow withdrawals

If allowed_ips is empty, the first successful API request automatically adds the current IP to the list.

Steps

  1. Sign up for the service.
  2. Open the API keys tab.
  3. Click Create API key.
  4. Set the name, permissions, and IPs in the form.
  5. Copy the keys from the modal right away — the secret is shown only once.
  6. Done.

In your requests, use the key id as X-API-Key-ID and the secret for signing.

callback_key

The webhook verification key lives in your dashboard profile. It is not the same as the secret API key.

Request headers

HeaderDescription
X-API-Key-IDKey UUID
X-TimestampUnix timestamp, seconds
X-SignatureHMAC-SHA256 hex

A signature is required for every public endpoint (GET, POST, and others).

Signing algorithm

  1. Build the object:
{
  "params": "url_encoded_query_string",
  "body": {},
  "path": "/user/balance/"
}
  • params — the query string exactly as it appears in the URL (search_query=foo, without the ?)
  • body — the JSON request body; {} when there is no body
  • path — the request path, e.g. /user/balance/
  1. Serialize the object: json.dumps(data, separators=(",", ":"), sort_keys=True)
  2. Sign it:
signature = HMAC-SHA256(key=API_KEY_SECRET, message=timestamp + json_string)
  1. The timestamp must be within ±15 seconds of server time.

If the key's allowlist is empty, the first successful request records the current IP in the allowlist. After that, only requests from a listed IP are accepted.

Example: GET balance

# empty params, body {}
# path = /user/balance/
# data = {"body":{},"params":"","path":"/user/balance/"}

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

Example: POST address

curl "https://api.cryptoway.com/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"}'

Generating a signature

:::tabs

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": "/user/address/"}
ts = int(time.time())
signature = sign(API_KEY_SECRET, ts, data)
$data = ["params" => "", "body" => ["symbol_id" => "USDTBEP20"], "path" => "/user/address/"];
ksort($data);
$json = json_encode($data, JSON_UNESCAPED_SLASHES);
$signature = hash_hmac("sha256", time() . $json, $API_KEY_SECRET);

:::

Verifying a webhook signature

A POST is sent to your callback_url.

Headers:

HeaderDescription
X-SignatureHMAC-SHA256 hex
X-TimestampUnix timestamp

Data to sign:

{
  "params": "",
  "body": { }
}
  • params — the query string of your endpoint
  • body — the parsed JSON POST body
  • the path field is not used
  • the signature uses callback_key

Allowed timestamp drift: ±15 seconds.

Deposit / withdrawal webhook

The POST body is the transaction object as JSON (fields are described below). To verify the signature, place this object in the body field and leave params empty.

Invoice webhook

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

The POST body is identical to the object you sign: params and body at the top level. To verify the signature, use the entire parsed request body as-is, with no extra wrapper.

Verifying webhooks in Python

Deposit and withdrawal webhooks:

body = await request.json()
data = {"params": request.url.query, "body": body}
verify(request.headers["X-Signature"], CALLBACK_KEY, int(request.headers["X-Timestamp"]), data)

Invoice webhook:

data = await request.json()
verify(request.headers["X-Signature"], CALLBACK_KEY, int(request.headers["X-Timestamp"]), data)

Shared verify helper:

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)

Deposits

Deposits

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

Getting started

Before you integrate, create an API key (see the Signing section). Without a key, API requests won't go through.

Choosing an integration type

There are two ways to accept deposits.

Invoice

Best for charging a fixed amount for a product or service.

Create one with POST /invoice/. Set the amount in fiat (target_value_fiat) or in crypto (target_value_symbol).

Symbol and address

  • If you pass symbol_id at creation, an address and a pay_url are generated right away.
  • If you omit symbol_id, the payer picks the symbol and network on the payment page. The address appears once they choose.

Notifications

EventWebhook
On-chain transfer receivedDeposit webhook: amount, hash, transaction status
Invoice amount collectedInvoice webhook: status: executed
Invoice expired before full paymentInvoice webhook: status: expired

Invoice statuses: active, executed, expired, cancelled. There are no intermediate partial-payment statuses (paid_over, wrong_amount, etc.). Partial transfers arrive as separate deposit webhooks; the invoice moves to executed once the deposits add up to the target, or to expired at deadline_at.

Permanent address

Best for topping up a balance with no fixed amount.

Create one with POST /user/address/. Pass symbol_id and, optionally, external_id (your own identifier for the address).

You can send transfers of any amount above min_deposit_amount to the address. Each transfer creates a deposit and its own webhook.

Overall flow

  1. Create an invoice or a permanent address.
  2. The payer sends an on-chain transfer.
  3. The scanner registers the deposit. If a callback_url is set, a webhook is sent.

Endpoints

MethodPathDescription
POST/user/address/Permanent address
GET/user/address/List of addresses
GET/user/address/balance/{symbol_id}/Latest balance 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/user/transaction/History (type=deposit)
GET/user/transaction/{encoded_id}/A single transaction

POST /user/address/

Request

FieldTypeDescription
symbol_id*stringSymbol identifier: a currency on a specific network, e.g. USDTBEP20, BNBBEP20. For the list of values, see GET /symbol/ (Reference)
callback_urlstringURL for the deposit webhook
descriptionstringAddress label
external_idstringYour ID

Virtual symbols (USDT) are not accepted. Always pass a network-bound symbol.

Response

FieldDescription
idAddress ID
valueWallet address
symbol_idSymbol identifier
callback_urlWebhook URL
external_idYour ID
created_atCreation date

POST /invoice/

Request

FieldTypeDescription
name*stringName
symbol_idstringSymbol identifier for the payment
target_value_fiatdecimalAmount in fiat
target_currency_fiatstringFiat currency, USD by default
target_value_symboldecimalAmount in crypto
deadline_atdatetimeInvoice expiry
callback_urlstringURL for the invoice status webhook
external_idstringYour ID
is_payer_feeboolThe payer covers the fee
descriptionstringDescription

You must set either target_value_fiat or target_value_symbol.

Response

The payment address is in target_wallet.value, the current status, and the payment link in pay_url.

GET /user/transaction/

Filters for deposits:

ParameterDescription
typedeposit
symbol_idSymbol identifier
external_idYour ID
statuspending, executed, dirty_lock, cancelled
in_processingtrue — in-progress transactions only; false — completed
begin_at, end_atDate range

Deposit webhook

A POST to the callback_url you set when creating the address. For invoice deposits, the invoice's callback_url is used.

Body (main fields):

FieldDescription
typedeposit
statusTransaction status
symbol_idSymbol identifier
amountAmount credited to the balance
service_feeService fee
net_amountOn-chain transfer amount (amount + service_fee)
blockchain_data.hashTx hash
blockchain_data.from_addressSender
blockchain_data.to_addressRecipient (your address)
external_idYour ID from the address
invoiceInvoice data, if the deposit is for an invoice
aml_orderAML status, if the check is enabled
callback_orderStatus of the latest webhook delivery (last_status_code, last_response_data)

Example

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

Invoice webhook

A separate callback fires when the invoice status changes (executed, expired). The body format and signature verification are covered under Invoice webhook in the Signing section.

Deposit statuses

statusDescription
pendingAwaiting AML or network confirmations
executedCredited to the balance
dirty_lockAddress flagged dirty, deposit locked
cancelledCancelled

Invoice statuses

statusDescription
activeAwaiting payment
executedPaid
expiredExpired
cancelledCancelled

Webhook delivery

If your server responds with an error, the webhook is retried automatically.

If your server already returned 2xx to the first webhook, no retry is sent when the status later changes to executed. With AML or pending confirmations, the first webhook may arrive with the pending status.

Query the current transaction status via GET /user/transaction/ or GET /user/transaction/{encoded_id}/.

Minimum amount

Deposits below min_deposit_amount are ignored. For the current value, see GET /setting/fees/ (Reference).

Withdrawals

Withdrawals

Endpoints

MethodPathDescription
POST/user/balance/withdrawal/Create a withdrawal
GET/user/transaction/?type=withdrawalHistory and status
GET/user/transaction/{encoded_id}/A single transaction

There is no separate GET /withdrawal/{id}. Use the transaction API.

POST /user/balance/withdrawal/

Query

ParameterDescription
totp_codeEmail OTP. Not required when authenticating with an API key

Request

FieldTypeDescription
symbol_id*stringSymbol identifier, e.g. USDTTRC20. For the list of values, see GET /symbol/ (Reference)
to_address*stringRecipient address
amount*decimalAmount to the recipient (net)
external_idstringYour ID
callback_urlstringWebhook URL
extra.memostringMemo/tag (if the network supports it)

Virtual symbols are not accepted.

The fee is charged on top of amount. Your balance is debited by amount + service_fee.

Response

A transaction object as JSON: "type": "withdrawal", the current withdrawal status in status, and the identifier in encoded_id.

Errors

detailReason
Insufficient balanceNot enough funds
Invalid addressInvalid address
Minimum withdrawal amount is ...Below the minimum
TOTP code is requiredtotp_code required without an API key
MEMO doesn't supported on this chain!Memo not supported

Rate limit: 15 requests per 15 seconds.

GET /user/transaction/

ParameterDescription
typewithdrawal
statusWithdrawal status
in_processingtrue — in-progress withdrawals only
external_idYour ID

Withdrawal webhook

Sent once, when the withdrawal moves to the executed status.

Body

A transaction object as JSON with "type": "withdrawal". The fields match the deposit webhook object.

FieldDescription
amountTransaction amount (recipient + fee)
service_feeFee
net_amountAmount to the recipient (amount - service_fee)
statusexecuted
blockchain_data.hashTx hash
to_addressRecipient address
memoMemo, if any
external_idYour ID

The signature is verified with callback_key, using the X-Signature and X-Timestamp headers and the data structure with params and body.

Withdrawal statuses

statusDescription
compliance_approve_requiredAwaiting manual approval
createdQueued
aml_order_pendingAML check
prepare_pendingPreparing the transaction
ready_to_transferReady to send
transfer_lockSending to the network
pendingAwaiting confirmations
swap_lockAwaiting autoswap
executedCompleted
cancelledCancelled by an admin
cancelled_by_riskCancelled by AML
failedFailed

The in_processing=true filter returns every status except executed, cancelled, cancelled_by_risk, and failed.

Limits

ParameterDescription
min_withdrawal_amountMinimum per symbol and tariff. For the value, see GET /setting/fees/
withdrawal_fee_amountFixed fee
withdrawal_fee_percentagePercentage fee
totp_codeRequired without an API key (email OTP, 10 min)

Repeating a request with the same external_id is not idempotent.

Reference

Reference

Helper methods that the operations in the other sections rely on.

Endpoints

MethodPathDescription
GET/symbol/List of symbols
GET/symbol/fiat/List of supported fiat currencies
GET/user/balance/Balance by symbol
GET/setting/fees/Fees and limits
GET/currency/rate/Currency pair rates
GET/currency/rate/hedge/Rates to USDT (source: aster_dex)

GET /symbol/

Use it to get valid symbol_id values when creating an address, invoice, or withdrawal.

Query

ParameterDescription
pagePage number, 1 by default
per_pagePage size, 100 by default
search_querySearch by id, name, short_name
order_typesymbol, short_name, name
order_ascAscending order, true by default

Response

A paginated list. Each item:

FieldDescription
idSymbol identifier for the API (symbol_id)
nameFull name
short_nameShort currency name
blockchainNetwork: id, name, explorer links
is_activeWhether the symbol is available
is_virtualVirtual symbol (don't use for the API)
group_symbol_idBalance group, if the symbol is grouped
balance_symbol_idSymbol the balance is kept in
contract_addressToken contract address, if any
precisionPrecision

For symbol_id requests, pick records with is_virtual: false and is_active: true.

GET /symbol/fiat/

A list of fiat currency codes for the target_currency_fiat field when creating an invoice.

Response

An array of strings, e.g. ["USD", "EUR", ...].

GET /user/balance/

The account's current balance. Handy before creating a withdrawal.

Query

ParameterDescription
search_queryFilter by symbol_id

Response

An array of objects:

FieldDescription
symbol_idSymbol identifier
valueAvailable balance

Rate limit: 30 requests per minute.

GET /setting/fees/

Fees and minimum amounts by symbol.

Query

ParameterDescription
user_idUser ID for personalized settings
tariff_idTariff ID

Without parameters, global values are returned. Pass your user_id to get your actual limits and fees.

Response

An array of objects by symbol:

FieldDescription
symbol_idSymbol identifier
min_deposit_amountMinimum deposit
min_withdrawal_amountMinimum withdrawal
deposit_fee_amountFixed deposit fee
deposit_fee_percentageDeposit fee percentage
withdrawal_fee_amountFixed withdrawal fee
withdrawal_fee_percentageWithdrawal fee percentage

GET /currency/rate/

Currency pair rates.

Query

ParameterDescription
sourceSource: coingecko or aster_dex. Without the parameter — all sources

Response

An array of objects:

FieldDescription
from_symbol_idThe crypto symbol_id, or a fiat code (for fiat→fiat pairs)
to_symbol_nameQuote currency code: fiat (USD, EUR, ...) or USDT
valueRate: how many units of to_symbol_name per 1 unit of from_symbol_id
sourcecoingecko or aster_dex
created_atUpdate time

Example pairs

sourcefrom_symbol_idto_symbol_nameMeaning
coingeckoUSDTBEP20USDCrypto symbol to fiat
coingeckoUSDEURFiat to fiat
aster_dexBTCUSDTCrypto symbol to USDT

GET /currency/rate/hedge/

Only from_symbol_idUSDT rates from the aster_dex source. The response format matches GET /currency/rate/.

Premium Exchange

How to connect to Premium Exchanger

Connect CryptoWay to an exchange running the Premium Exchanger (v 2.7) script via two modules:

  • Merchant (incoming payments) — receives the client's funds into your accounts and automatically moves the order to the “Paid order” status.
  • Auto-payout — pays the client out from your accounts.

Together they fully automate the exchange. You can connect just one module to automate only the accept side or only the payout side.

Full Premium Exchanger documentation: Merchant and auto-payout modules

What you need

  • An exchanger on Premium Exchanger 2.7.x. Modules are version-locked: a 2.7 script needs 2.7.* modules, otherwise the site won't load.
  • Server access via ISP Manager as the site user (not root).
  • A CryptoWay API key with deposit + withdrawal permissions — the API key ID and secret (see Signing).

Step 1. Module files

ModuleArchivePurpose
Merchant (incoming payments)m_cryptoway_271.zipAccept crypto payments
Auto-payoutspay_cryptoway_271.zipAutomatic payouts

The module version must match your Premium Exchanger script version (e.g. 271 for 2.7.\*).

Step 2. Upload to the server

Back up the site root folder first. Work through ISP Manager as the site user (not root).

  1. Upload the cryptoway folder from m_cryptoway_271.zip to /wp-content/plugins/premiumbox/merchants.
  2. Upload the cryptoway folder from pay_cryptoway_271.zip to /wp-content/plugins/premiumbox/paymerchants.
  3. If a file-conflict dialog appears, click “Replace”.

Step 3. Add and configure the merchant

In “Merchants” → “Merchants” click “Add” (some merchants exist by default). Fill the form:

Add-merchant form in Premium Exchanger

  • Title — the merchant name shown in the admin panel.
  • Module — pick CryptoWay from the dropdown.
  • Status — set “active merchant”.

In the module settings, enter the keys from your CryptoWay dashboard:

  • API keyAPI key ID.
  • Secret key — your API key's secret.

Step 4. Auto-payouts

The auto-payout module is connected the same way: the “Auto-payouts” section → “Add”, status “active”, the same CryptoWay keys (API key ID + secret). It is bound on the “Merchants and payouts” tab of the direction — for the “You get” currency. Before enabling it, read the “Risk warning” section of the Premium Exchanger docs.

Step 5. Operation modes

The exchanger starts in manual mode. With the modules:

  • Merchant only (accept) — accepting is automated: when funds arrive the order moves to “Paid order”, and you pay out manually and set the status to “Completed order”.
  • Merchant + auto-payout — full automation: “Paid order” → “Awaiting confirmation from the auto-payout module” → “Completed order”.
  • You can enable the “Transfer” button on an order even for an automated direction, so an operator can pay out manually if an auto-payout fails.

Step 6. Verify

Check the connection with the built-in “Merchant diagnostics” (Merchants → Merchants → diagnostics):

Merchant log and diagnostics in Premium Exchanger

  • Make sure the server's task scheduler (cron) is configured — without it order statuses won't change automatically.
  • If the log shows a “your IP … not in whitelist” error, add your server's IP to the CryptoWay API key whitelist (the allowed_ips parameter).