Документация API
Документация по интеграции открытого API Tovanix, разделённая по сервисам: Мультичейн-платежи, Аренда энергии, SMTP API, API ИИ, Виртуальная карта, Электронная почта, Объектное хранилище, Верификация и риски транзакций, Доступ MCP. Лаборатории: Студия контрактов, Воспроизведение платежей, Лаборатория маршрутизации ИИ.
- Мультичейн-платежи
- Аренда энергии
- SMTP API
- API ИИ
- Виртуальная карта
- Электронная почта
- Объектное хранилище
- Верификация и риски транзакций
- Доступ MCP
USDT / USDC / ETH / TRX / BTC · TRON / EVM / Bitcoin · Две подписи: HMAC-SHA256 (платёж) + RSA-2048 (выплата) · Push о расчёте за 30 секунд
Интеграция за 3 шага
- 1 Зарегистрировать учётную запись + создать приложение Получите app_id и app_key в разделе «Мои приложения» консоли, затем настройте notify_url Зарегистрироваться бесплатно →
- 2 Реализовать функцию подписи Платежи используют HMAC-SHA256 (симметричный), выплаты — RSA-2048 (асимметричный). Официальный SDK реализует оба с полными примерами для разных языков.
- 3 Выбрать режим и выполнить первую транзакцию Один к одному (адрес привязан к пользователю, подходит для кошельков/пополнений) · Ротация (адрес создаётся для заказа, подходит для оплаты в интернет-магазине)
Обзор
Tovanix поддерживает два режима платежей, которые можно включить одновременно:
Режим один к одному
Пользователи привязывают постоянный адрес; все поступления автоматически передаются уведомлениями. Подходит для пополнений и приёма средств.
- Пользователь привязывает постоянный адрес получения
- Push-уведомления о поступлениях в реальном времени
- Поддержка повторных платежей
- Независимая проверка подписи
Режим ротации
При создании заказа динамически назначается адрес получения, который освобождается по истечении времени ожидания. Подходит для разовых платежей.
- Динамическое назначение адресов
- Управление сроком заказа
- Автоматическое преобразование по курсу
- Страница оплаты
Алгоритм подписи
Push-уведомления режима один к одному подписываются с webhook_secret, а не с app_key.
1. Используйте HMAC-SHA256 с секретом в параметре ключа HMAC (не добавляйте его в строку)
2. Подпись — шестнадцатеричная строка из 64 символов в нижнем регистре; сравнение учитывает регистр
3. При создании заказа amount оформляется с двумя десятичными знаками (например 100.00), timeout — строкой целого числа; даже если timeout не передан, нужно подписать timeout=0 (сервер всегда включает timeout в строку подписи)
4. Поля с пустыми значениями исключаются из вычисления подписи
Защита от повторного воспроизведения
Для предотвращения повторного воспроизведения перехваченных запросов можно передавать временную метку и nonce; оба включаются в подпись. Закрытие заказа, привязка и отвязка адреса требуют их и возвращают 400 при отсутствии; для остальных конечных точек они необязательны.
/api/v1/pay/close: обязательны timestamp и nonce. /api/v1/pay/bind-address и /api/v1/pay/unbind-address: обязательны sign_ts и nonce (временная метка также допускает имя timestamp). /api/v1/pay/get-address тоже использует sign_ts, но необязательный. Создание, запрос заказа и конфигурация приложения используют необязательный timestamp: если переданы и метка, и nonce, сервер проверяет временное окно и nonce; если только один или ни одного — лишь подпись.
timestamp должен отличаться от времени сервера не более чем на 300 секунд; синхронизируйте серверы через NTP. nonce нельзя повторно использовать в течение 5 минут. Запрос вне временного окна или с повторным nonce отклоняется: создание и запрос заказа возвращают HTTP 400, остальные конечные точки — 401; поле сообщения ответа содержит причину.
Привязать адрес
POST /api/v1/pay/bind-address
Назначает пользователю постоянный адрес оплаты. Если уже привязан, возвращается существующий адрес.
Запросить привязку
POST /api/v1/pay/get-address
Запрашивает адрес оплаты, привязанный к пользователю.
Отвязать адрес
POST /api/v1/pay/unbind-address
Отвязывает адрес оплаты пользователя.
Создать заказ
POST /api/v1/pay/create
Создаёт заказ оплаты; система автоматически назначает адрес получения.
Поля ответа
amount принимает число и строку: 100 или "100". Для подписи всегда используйте два десятичных знака, например "100.00".
Запросить заказ
GET /api/v1/pay/query
Запрашивает состояние заказа по вашему идентификатору заказа. Параметры — в строке запроса URL.
Закрыть заказ
POST /api/v1/pay/close
Закрывает неоплаченный заказ вручную; адрес освобождается. Закрыть можно только ожидающие заказы (status=0).
Запросить конфигурацию приложения
GET /api/v1/pay/app-config
Запрашивает режимы приложения, включённые токены, настройки push-уведомлений и др. Конфиденциальные данные не раскрываются.
Push-уведомление режима один к одному
Когда привязанный адрес получает перевод, система отправляет POST-запрос на настроенный notify_url.
Push-уведомления подписываются с webhook_secret, который можно просмотреть или создать заново на странице приложения.
Поля push-уведомления
При получении верните HTTP 200 или {"code": 0}; иначе система повторит автоматически (до 10 раз с экспоненциальной задержкой).
Уведомление обратного вызова заказа
После оплаты заказа в режиме ротации система отправляет обратный вызов на notify_url.
Уведомления обратного вызова подписываются с webhook_secret, который можно просмотреть или сбросить на странице приложения.
Поля обратного вызова
Любой статус 2xx считается доставкой; тело ответа не проверяется (ответ {"code": 0} со статусом не 2xx — всё равно ошибка). Статус не 2xx, отсутствие ответа в течение 10 секунд, ошибка соединения и перенаправление считаются неудачей; платформа повторяет через 30 секунд, 1, 2 и 5 минут, затем каждые 10 минут, до 10 раз. Повторы сохраняют тот же notify_id, но несут новые sign_ts, nonce и подпись — убирайте дубликаты по notify_id.
Получить обменный курс
GET /api/v1/rate
Получить текущий обменный курс между двумя валютами
Преобразовать сумму
POST /api/v1/convert
Преобразовать сумму по текущему курсу
Пакетный запрос курсов
GET /api/v1/rates
Запросить курсы нескольких валют (коды через запятую)
Все обменные курсы
GET /api/v1/rates/all
Получить список курсов всех поддерживаемых валют
Курсы фиатных валют
GET /api/v1/rates/fiat
Получить все фиатные курсы относительно выбранной фиатной валюты (более 30 валют, сгруппированы по регионам)
Статус заказов
Заказы проходят следующие состояния:
Коды ошибок
Единые коды ошибок API платежей (/api/v1/pay/*); коды ошибок API выплат — в разделе справочника.
Обзор выплат / Предварительные требования
API выплат обеспечивает вывод средств продукта мультисетевых платежей: программно отправляет на внешние адреса активы, уже собранные в центральный кошелёк. Взаимные подписи RSA-2048 + список разрешённых IP + отложенная трансляция + многоканальные уведомления для остановки операции + обратный вызов после подтверждения в блокчейне.
API выплат расходует только активы, собранные в центральном кошельке в режиме хранения системой. Если приложение использует режим самостоятельного хранения — средства поступают прямо на ваши адреса, а платформа их не собирает — баланс «собрано, ожидает выплаты» не возникает, и выплаты через этот API невозможны.
Включение за 4 шага
- Откройте настройки «Мультисетевые платежи → Выплаты через API» в консоли
- Сгенерируйте пару ключей RSA-2048 локально и загрузите нам открытый ключ
- Добавьте хотя бы один IP в список разрешённых (обязательно); при необходимости настройте разрешённые адреса, лимит на операцию и задержку выплаты
- Включите главный переключатель; система создаст пару ключей платформы для аккаунта. Скопируйте открытый ключ платформы на свою сторону для проверки обратных вызовов
Подпись · RSA-2048 (выплата)
Все интерфейсы /api/v1/withdraw* должны содержать следующие заголовки. В отличие от симметричного HMAC платёжного API, выплаты используют асимметричный RSA: платформа хранит только ваш открытый ключ, поэтому риск возникает при утечке вашего закрытого ключа.
- X-API-Key — API-ключ платформы (в консоли: Инструменты и настройки → Управление API); ключ должен иметь разрешение withdraw
- X-Timestamp — Текущее время Unix в мс; расхождение с сервером должно быть ≤ 60 секунд
- X-Nonce — Одноразовый nonce (uuid); нельзя повторно использовать в течение 5 минут
- X-Withdraw-Signature — RSA-PKCS1v15-SHA256(caller_private_key, signString), Base64
Правило объединения строки для подписи
Здесь BODY — исходное тело HTTP (строка JSON без изменений; не сериализуйте заново). Для GET-запросов BODY — пустая строка.
Помимо описанных RSA-подписи и разрешённых IP аккаунта, API-ключ должен иметь разрешение withdraw и соответствовать собственному списку исходных IP: отсутствие разрешения — 403 / 4032, IP вне списка ключа — 403 / 4033. Обе проверки действуют для /api/v1/withdraw, /api/v1/balance/withdrawable и /api/v1/fee/quote. Существовавшие ранее ключи получают withdraw автоматически; для новых выберите его в Инструменты и настройки → Управление API. Разрешения можно проверить через GET /api/v1/whoami (с X-API-Key + X-Secret-Key или HMAC-подписью).
Обратный вызов результата выплаты
При создании заказа можно передать callback_url в теле; после завершения, сбоя или отмены выплаты платформа отправляет результат на этот URL методом POST.
- Тело обратного вызова подписывается закрытым ключом платформы, подпись передаётся в заголовке X-Platform-Signature
- Проверяйте подпись открытым ключом платформы (доступен в настройках); алгоритм проверки тот же, что для запросов
- При ошибке повторы выполняются через 1m / 5m / 30m / 2h / 6h / 24h — всего 6 раз, затем прекращаются и передаются на ручную обработку
- Ваша сторона должна вернуть HTTP 2xx; любой другой ответ считается ошибкой
Заголовки
- X-Timestamp — Текущая метка времени unix в миллисекундах
- X-Platform-Signature — Base64(RSA-PKCS1v15-SHA256(закрытый ключ платформы, строка подписи))
Правило объединения строки для подписи
PATH — путь из callback_url (без хоста и строки запроса), BODY — исходное тело запроса, не сериализуйте его заново. Проверяйте открытым ключом платформы со страницы настроек.
status: completed / failed / failed_onchain / cancelled; суммы и комиссии — строки; created_at и completed_at — секунды unix, 0, если времени завершения нет. Тело не меняется между повторами одного заказа — убирайте дубликаты по order_id.
Начать выплату
POST /api/v1/withdraw
После создания заказ получает статус pending; по истечении задержки фоновый процесс автоматически транслирует транзакцию. В этот период заказ можно приостановить, ускорить или отменить в консоли.
Описание полей
- chain — string — Да — tron / eth / bsc / polygon / arbitrum / base / optimism / avax / xlayer / btc
- symbol — string — Да — USDT / TRX / ETH и т. д.
- amount — string — Да — До 18 десятичных знаков; используйте строку во избежание ошибок чисел с плавающей точкой
- to_address — string — Да — Адрес назначения (при включённом списке разрешённых адресов сначала добавьте его в консоли)
- memo — string — Нет — Описание (≤500 символов); передаётся пользователю аккаунта вместе с уведомлением
- callback_url — string — Нет — URL обратного вызова с результатом; если пустой, обратный вызов не отправляется
- request_id — string — Настоятельно рекомендуется — Ключ идемпотентности; повтор того же значения для того же аккаунта возвращает исходный заказ; если сеть, монета, адрес или сумма отличаются, возвращается 409 и заказ не создаётся Без него нет защиты идемпотентности: повтор после тайм-аута или ответа 5xx создаст вторую реальную выплату.
Поля ответа
- order_id — string — ID заказа на вывод; используется в интерфейсе запроса отдельного вывода
- status — string — Текущий статус заказа со значениями, совпадающими с status_label в интерфейсе запроса. Новый заказ — pending (баланс списан, ожидаются задержка контроля рисков и трансляция); повтор с тем же request_id возвращает фактический статус, который уже может быть completed, failed и т. д.
- amount — string — Сумма вывода (строка)
- fee — string — Ожидаемая комиссия (зафиксирована при создании заказа)
- fee_mode — string — in_amount = вычитается из суммы (получено = amount − fee, списано с баланса amount); out_amount = взимается отдельно (получено = amount, списано amount + fee)
- delayed_until — string | null — Планируемое время трансляции (задержка контроля рисков); null = без задержки
Запрос статуса отдельной выплаты
GET /api/v1/withdraw/:id
Возвращает сведения о заказе; можно использовать для периодического опроса статуса (обратный вызов по-прежнему рекомендуется).
Поля ответа
- id — string — ID заказа на вывод
- request_id — string — Переданный вами ключ идемпотентности
- chain / symbol — string — Сеть / символ токена
- amount / expected_fee / fee_mode — string — Сумма вывода / ожидаемая комиссия, зафиксированная при создании / режим комиссии (in_amount, out_amount)
- to_address — string — Адрес назначения
- memo — string — Примечание (TAG/Memo)
- status / status_label — int / string — Код статуса и текстовая метка; см. «Статусы заказов» ниже
- tx_hash — string — Хеш транзакции в блокчейне (устанавливается после трансляции)
- fail_reason — string — Причина ошибки (устанавливается при сбое)
- delayed_until / broadcast_at / confirmed_at / paused_at / cancelled_at — string | null — Время этапов: запланированная трансляция / трансляция / подтверждение в блокчейне / приостановка / отмена; null, если этап не достигнут
- callback_url / callback_retry — string / int — URL обратного вызова / текущее число повторов
- callback_state — string — Статус обратного вызова: pending = ещё не вызван или повторяется, success = получен 2xx, giveup = повторы исчерпаны, no_url = обратный вызов не настроен
- created_at — string — Время создания
Запросить доступный баланс
GET /api/v1/balance/withdrawable
Возвращает баланс «собрано, ожидает выплаты» аккаунта по каждой сети и активу. Только эта часть доступна для выплат через API.
Двухуровневая структура: сеть → символ токена → доступный для вывода баланс (строка); возвращаются только записи с балансом больше 0.
Оценка комиссии
Возвращает предварительно удерживаемую комиссию, настроенную администратором для пары сеть × символ (фиксированное значение по модели OKX).
Поля ответа
- chain / symbol / amount — string — Повтор переданных параметров: chain / symbol / amount
- fee_amount — string — Сумма комиссии
- fee_asset — string — Актив для расчёта комиссии
Полный пример cURL
Полный процесс подписи и запроса; скопируйте прямо в терминал для проверки.
Состояние заказа · Выплата
Автомат состояний: pending → broadcasted → completed / failed_onchain; промежуточно возможны paused / cancelled / failed.
- 0 — pending — Баланс списан; ожидается окончание задержки / ещё не транслировано
- 1 — completed — Транзакция в блокчейне успешно подтверждена (доступен обратный вызов)
- 2 — failed — Ошибка до трансляции (баланс возвращён)
- 3 — broadcasted — Транслировано; ожидается подтверждение в блокчейне
- 4 — failed_onchain — Ошибка в блокчейне (откат / длительное отсутствие включения в блок; баланс возвращён)
- 5 — paused — Приостановлено пользователем вручную; можно возобновить или отменить
- 6 — cancelled — Отменено пользователем вручную; баланс возвращён
- 7 — broadcasting — Транслируется (краткое переходное состояние, предотвращающее двойную трансляцию)
Коды ошибок · API выплат
- 400 — Недопустимые параметры / недостаточный баланс / сумма вне лимитов пары сеть × символ / ошибка проверки адреса
- 401 — Недопустимый API-ключ / слишком большое расхождение времени / nonce уже использован / ошибка проверки подписи
- 403 — Выплаты через API не включены для аккаунта / IP отсутствует в разрешённом списке аккаунта; либо API-ключ не имеет разрешения withdraw (code 4032), либо исходный IP отсутствует в списке этого ключа (code 4033)
- 404 — Заказ не найден
- 429 — Слишком много запросов (до 10 в секунду на аккаунт). Ответ содержит Retry-After: 1; подождите секунду и повторите с тем же request_id
- 5xx — Ошибка платформы; можно повторить (используйте тот же request_id для обеспечения идемпотентности)
Примечания о безопасности выплат
- Храните закрытый ключ локально в безопасном месте; утечка позволит другим выполнять выплаты от вашего имени
- Перед включением выплат через API обязательно настройте список разрешённых IP; IP вне списка отклоняется даже с действительной подписью
- Также рекомендуем включить список разрешённых адресов выплат и заранее добавить известные адреса назначения
- После включения 2FA пользователь аккаунта может подтверждать ею ускорение или отмену заказов в консоли в течение задержки
- Для крупных заказов рассмотрите более длительную задержку (несколько часов), чтобы после уведомлений было время вмешаться вручную
Связанные страницы: Мультичейн-платежи в криптовалюте · Агрегированный SMTP API · ИИ-сервисы
Загрузка…