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

Company API предназначен для интеграций B2B: программная генерация TRON-кошельков, выполнение переводов TRX и USDT (TRC20) с оптимизацией энергии для стейблкоина, прозрачный биллинг по балансу API-ключа и журнал операций. Все методы доступны только с валидной парой учётных данных в заголовках запроса.

Доступ и поддержка

Выдача API-ключей (идентификатор клиента X-Client-Id и секрет X-Client-Api-Key), пополнение баланса TRX на ключе и сопровождение по интеграции выполняются только через службу поддержки RombPay — публичной саморегистрации нет.

Напишите в Telegram: @finkonory. Укажите компанию, ожидаемые объёмы и сценарий (TRX / USDT / оба) — мы выдадим ключи и условия подключения.

Формат ответов

Успешные ответы обычно имеют вид { "code": 0, "msg": "OK", "result": ... }. Поле result содержит полезную нагрузку. Ошибки аутентификации и валидации чаще возвращаются без обёртки code — см. тело ответа и HTTP-код.

Интерактивная спецификация OpenAPI (Swagger UI): https://api.rombpay.io/docs. На этой странице — обзор продуктовой логики и примеры для интеграторов.

Базовый адрес API

Все методы Company API располагаются под префиксом /v1/api относительно хоста.

https://api.rombpay.io/v1/api/...

Аутентификация

На каждый запрос передавайте два заголовка. Значение X-Client-Api-Key — ровно тот же 32-символьный ключ, что хранится в базе (буквы и цифры), без хэширования. Отдельный внутренний API-ключ для этих маршрутов не используется.

X-Client-Id: <10_DIGIT_CLIENT_ID>
X-Client-Api-Key: <32_CHAR_API_KEY_SAME_AS_IN_DB>
Content-Type: application/json (for POST with body)

В curl не разрывайте значение ключа переносом строки внутри кавычек — иначе libcurl вернёт ошибку.

Тарификация и баланс

POST /v1/api/wallet/generate — 0 TRX с баланса API-ключа; операция записывается в журнал с price_trx = 0.
POST /v1/api/transactions/execute — для USDT после успешной цепочки (энергия + перевод) с баланса ключа списывается 6.5 TRX (тариф можно согласовать при подключении); для TRX баланс ключа не используется — в ответе chargedTrx: "0", сеть TRON по-прежнему взимает комиссию с кошелька отправителя.

Проверка достаточности баланса и HTTP 402 выполняются только для запросов с asset: "usdt".

Эндпоинты

Генерация TRON-кошелька

POSThttps://api.rombpay.io/v1/api/wallet/generate

Развернуть

Создаёт новую пару ключей TRON и возвращает адрес, публичный и приватный ключ. Счётчик генераций на API-ключе увеличивается; в таблице api_jobs создаётся запись типа wallet_generate со статусом success и нулевой стоимостью.

Request

curl -X POST "https://api.rombpay.io/v1/api/wallet/generate" \
  -H "X-Client-Id: <10_DIGIT_CLIENT_ID>" \
  -H "X-Client-Api-Key: <32_CHAR_KEY_AS_IN_DATABASE>"

Успешный ответ

{
  "code": 0,
  "msg": "OK",
  "result": {
    "address": "TFPTizeJ9J1WJDaBz1f7gyjPW7lybfrFHk",
    "publicKey": "<PUBLIC_KEY>",
    "privateKey": "<PRIVATE_KEY>"
  },
  "priceTrx": "0"
}

Пример ошибки

{
  "error": "Unauthorized"
}

Исполнение перевода (TRX или USDT)

POSThttps://api.rombpay.io/v1/api/transactions/execute

Развернуть

Единая точка входа для нативного TRX и для USDT TRC20. Для USDT сервер сначала обеспечивает энергию на адрес отправителя (через интеграцию с поставщиком энергии), затем формирует и отправляет транзакцию контракта. Для TRX выполняется стандартная транзакция перевода.

Тело запроса (JSON)

Поле	Описание
fromPrivateKey	Приватный ключ кошелька отправителя в hex (64 символа). Передаётся только по HTTPS; храните и логируйте в соответствии с вашей политикой безопасности.
toAddress	Адрес получателя в base58 (TRON).
amount	Сумма: для USDT — в токенах (например 10.08 USDT), для TRX — в TRX. Должна быть положительной.
asset	`trx` — нативный перевод TRX. `usdt` — TRC20 USDT (сначала подготовка энергии через инфраструктуру RombPay, затем вызов контракта).
minTariff	Необязательно, только для USDT: целое число 1 или 2 — уровень объёма энергии для аренды (больше тариф — больше запас энергии на перевод). По умолчанию 1.

Ниже два примера curl: USDT (с minTariff) и TRX (без minTariff).

Request

# USDT
curl -X POST "https://api.rombpay.io/v1/api/transactions/execute" \
  -H "X-Client-Id: <10_DIGIT_CLIENT_ID>" \
  -H "X-Client-Api-Key: <32_CHAR_KEY_AS_IN_DATABASE>" \
  -H "Content-Type: application/json" \
  -d '{
  "fromPrivateKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "toAddress": "TRFUoibJ8J7TREaAz2y6gtxRE4llstiTMo",
  "amount": 10.08,
  "asset": "usdt",
  "minTariff": 1
}'

# TRX
curl -X POST "https://api.rombpay.io/v1/api/transactions/execute" \
  -H "X-Client-Id: <10_DIGIT_CLIENT_ID>" \
  -H "X-Client-Api-Key: <32_CHAR_KEY_AS_IN_DATABASE>" \
  -H "Content-Type: application/json" \
  -d '{
  "fromPrivateKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "toAddress": "TRFUoibJ8J7TREaAz2y6gtxRE4llstiTMo",
  "amount": 1.5,
  "asset": "trx"
}'

Успешный ответ

{
  "code": 0,
  "msg": "OK",
  "result": {
    "txHash": "<TX_ID>",
    "from": "<SENDER_BASE58>",
    "chargedTrx": "6.5",
    "balanceTrx": "93.5"
  }
}

Пример ошибки

{
  "error": "Insufficient API key balance",
  "requiredTrx": "6.5",
  "balanceTrx": "2.0"
}

Баланс и счётчики API-ключа

GEThttps://api.rombpay.io/v1/api/balance

Развернуть

Возвращает текущее состояние биллинга для ключа из заголовков.

Поле в result	Значение
balanceTrx	Остаток TRX на балансе ключа (списания только за успешные USDT-переводы по тарифу).
walletsGeneratedCount	Сколько раз вызывали wallet/generate с этим ключом (успешные генерации).
transactionsCount	Число успешных платных исполнений USDT (increment при списании с баланса ключа). Переводы TRX через execute сюда не входят.
spentTrxTotal	Суммарно списано TRX с баланса ключа за USDT-операции.
lastUsedAt	Метка последнего использования ключа (ISO 8601) или null.

Request

curl -X GET "https://api.rombpay.io/v1/api/balance" \
  -H "X-Client-Id: <10_DIGIT_CLIENT_ID>" \
  -H "X-Client-Api-Key: <32_CHAR_KEY_AS_IN_DATABASE>"

Успешный ответ

{
  "code": 0,
  "msg": "OK",
  "result": {
    "balanceTrx": "93.5",
    "walletsGeneratedCount": "12",
    "transactionsCount": "1",
    "spentTrxTotal": "6.5",
    "lastUsedAt": "2026-04-09T18:42:11.000Z"
  }
}

Пример ошибки

{
  "error": "Unauthorized"
}

Журнал операций (api_jobs)

GEThttps://api.rombpay.io/v1/api/jobs

Развернуть

Список записей по текущему API-ключу, от новых к старым. Каждая строка отражает генерацию кошелька или попытку execute; для неуспеха смотрите errorText.

Query-параметры

Параметр	Описание
limit	Необязательно, по умолчанию 20. Максимум 100 записей за запрос.
offset	Необязательно, по умолчанию 0. Смещение для постраничного просмотра.
jobType	Необязательно: `wallet_generate` или `transaction_prepare_transfer`.
status	Необязательно: `success` или `failed`.

Поле в элементе result[]	Описание
jobType	Тип операции (см. фильтр jobType).
status	success или failed.
priceTrx	Сумма, отнесённая на биллинг ключа (0 для wallet и для успешного TRX-execute).
walletAddress	Для wallet_generate — новый адрес; иначе обычно null.
txHash	Идентификатор транзакции в сети, если уже известен.
errorText	Текст ошибки при status failed.
createdAt	Время создания записи (ISO 8601).

Request

curl -X GET "https://api.rombpay.io/v1/api/jobs?limit=20&offset=0&jobType=wallet_generate&status=success" \
  -H "X-Client-Id: <10_DIGIT_CLIENT_ID>" \
  -H "X-Client-Api-Key: <32_CHAR_KEY_AS_IN_DATABASE>"

Успешный ответ

{
  "code": 0,
  "msg": "OK",
  "result": [
    {
      "id": "<UUID>",
      "jobType": "transaction_prepare_transfer",
      "status": "success",
      "priceTrx": "6.5",
      "walletAddress": null,
      "txHash": "<TX_ID>",
      "errorText": null,
      "createdAt": "2026-04-09T18:42:11.000Z"
    },
    {
      "id": "<UUID>",
      "jobType": "wallet_generate",
      "status": "success",
      "priceTrx": "0.00000000",
      "walletAddress": "T...",
      "txHash": null,
      "errorText": null,
      "createdAt": "2026-04-09T18:42:10.000Z"
    }
  ]
}

Пример ошибки

{
  "error": "Invalid query",
  "details": { ... }
}

HTTP-коды и типовые ошибки

HTTP	Сообщение	Когда возникает	Действия
401	Unauthorized / Invalid client credentials	Неверная пара X-Client-Id и X-Client-Api-Key, опечатка, ключ отключён.	Сверьте заголовки с выданными поддержкой значениями; ключ — одна строка из 32 символов.
400	Invalid body / Invalid query	Невалидный JSON, типы полей, адрес, asset или query-параметры jobs.	Сверьтесь с таблицами полей выше; для jobs смотрите details в ответе.
402	Insufficient API key balance	Только для USDT: перед execute на ключе недостаточно TRX для тарифа.	Пополнение баланса — через поддержку: @finkonory.
404	API key not found	Редкий случай: запись ключа отсутствует в БД при валидной аутентификации.	Обратитесь в поддержку.
409	Concurrent balance change	Гонка при списании баланса (несколько USDT-execute одновременно).	Повторите запрос безопасно (idempotency на вашей стороне).

Безопасность

Используйте только HTTPS к api.rombpay.io; не передавайте приватные ключи по незашифрованным каналам.
Секрет X-Client-Api-Key и приватные ключи кошельков храните в секрет-хранилище, не коммитьте в репозиторий.
Ограничьте доступ к продакшен-ключам по IP или среде выполнения, ведите аудит вызовов через журнал jobs.