Справочник

Ownbit MultiSig API v1 (этап 1)

Ваша система может передавать списки выплат в мультиподпись Ownbit. API-ключ, созданный в веб-консоли, отправляет черновики; подписанты проверяют каждую строку и запускают их на своих телефонах. API никогда не перемещает средства.

Редакция от 2026-11-18 (черновики меняются по lineId; пять статусов черновика). Этот документ описывает этап 1 API. Все ключи, хеши, адреса и IP-адреса в нём — вымышленные примеры (IP-адреса взяты из диапазонов, зарезервированных для документации); адрес контракта USDT-TRC20 — настоящий, общедоступный.

1. Что делает API

Ваша система (далее — «ваш бот») передаёт Ownbit список выплат для одной мультиподписи Ownbit — черновик — и затем читает, что с ним стало: подписант его запустил, отклонил, черновик был отозван или истёк.

API никогда не перемещает средства. Черновик превращается в платежи только тогда, когда подписант мультиподписи открывает его в веб-консоли Ownbit, запускает на своём телефоне и достаточно участников мультиподписи подписывают каждую транзакцию (m из n). Подписанты видят каждую строку до запуска, все проверки, которые Ownbit выполняет для платежа, по-прежнему действуют, и подписант может отклонить черновик. Ключ не может подписывать, запускать платежи, одобрять, отклонять или менять политику, белый список и участников мультиподписи.

Что может ключ:

ВызовРазрешениеЧто делает
GET /whoamidrafts:readОписывает ключ и его мультиподпись, с числом вызовов за сегодня
POST /draftsdrafts:submitОтправляет черновик (от 1 до 500 строк) или меняет черновик, который ещё никто не запустил: добавляет, заменяет и удаляет строки по вашему lineId
GET /draftsdrafts:readПеречисляет черновики этого ключа, начиная с самого давнего изменения, с курсором
GET /drafts/{draftId}drafts:readЧитает один черновик вместе со строками
DELETE /drafts/{draftId}drafts:submitОтзывает черновик, который ещё никто не запустил

2. Состав этапа 1

  • Только мультиподписи в сети TRON. Строки платят в TRX или USDT (USDT-TRC20, контракт TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t); у обоих 6 знаков после запятой.
  • Только IPv4. API доступен только по IPv4 (у api.bittool.com на этапе 1 нет адреса IPv6), и список разрешённых адресов ключа содержит диапазоны IPv4.
  • Без вебхуков. Ваш бот опрашивает API сам (как часто — сказано в разделе 10).
  • Не более 500 строк в черновике. Подписант может запустить большой черновик двумя запросами на своём телефоне; для вас это ничего не меняет.

3. Базовый URL и транспорт

https://api.bittool.com/ownbit/api/v1
  • Только IPv4 на этапе 1: у имени нет адреса IPv6, поэтому сервер, у которого есть и IPv4, и IPv6, обращается по IPv4 и сверяется со своим списком разрешённых адресов IPv4.
  • Только HTTPS. Запрос, пришедший не по HTTPS, отклоняется с 403 https_required и никогда не перенаправляется. Ключ, отправленный по обычному HTTP, следует считать утёкшим: отзовите его и создайте другой. Ответы по HTTPS содержат Strict-Transport-Security: max-age=31536000.
  • JSON в UTF-8. Запросы POST отправляют Content-Type: application/json (суффикс ; charset=utf-8 допустим). Тело запроса — не более 256 КиБ.
  • Время передаётся строками ISO 8601 в UTC с миллисекундами, например 2026-11-17T06:00:00.000Z.
  • Каждый ответ содержит Cache-Control: no-store, Pragma: no-cache и X-Request-Id (req_ и 16 символов из [0-9a-z]). Тела ошибок повторяют его в поле requestId. Указывайте его, когда обращаетесь в поддержку.
  • Без CORS. Ни одна страница в браузере не может вызвать API: вызывайте его со своего сервера.
  • Строгие запросы, открытые ответы. Запрос с полем, которого API не знает, отклоняется (400 invalid_request). В ответах со временем могут появляться новые поля: игнорируйте поля, которых вы не знаете.

4. Ключи

  • Откуда они берутся. Участник мультиподписи создаёт ключ в веб-консоли Ownbit, на вкладке API этой мультиподписи (это может любой участник с ролью подписанта), и подтверждает его на своём телефоне в приложении Ownbit. Ключ показывается один раз, в этой вкладке браузера, сразу после подтверждения на телефоне. Ownbit хранит только его хеш и не может показать его снова: если ключ потерян, отзовите его и создайте другой.
  • Формат. obk_ и 43 символа из [0-9A-Za-z] (всего 47 символов, около 256 бит случайности). Везде, где Ownbit показывает ключ, видны только его последние 4 символа, в виде obk_…defg.
  • Параметры, задаваемые при создании. Название (не более 30 символов, не совпадает с другими ключами мультиподписи); срок действия 30, 90 (по умолчанию), 180 или 365 дней, 2 года или 5 лет, отсчитываемый с момента подтверждения на телефоне; список разрешённых адресов IPv4 — до 20 диапазонов, каждый от /8 до /32 (пустой список означает любой адрес); и наибольшее число строк платежей, которое ключ может отправить за любые 24 часа (от 1 до 10 000, по умолчанию 1 000).
  • Разрешения. У каждого ключа этапа 1 есть drafts:submit и drafts:read.
  • Одна мультиподпись. Ключ охватывает один адрес мультиподписи: его TRX и, если есть, его USDT на этом адресе. Ownbit может показывать один адрес как несколько мультиподписей, по одной на токен; у них общие ключи. Ключ никогда не видит данных другой мультиподписи.
  • Не более 5 ключей на мультиподпись (включая ожидающие подтверждения).
  • Отзыв. Любой участник может отозвать ключ в любой момент — в веб-консоли или в приложении Ownbit. Отозванный или истёкший ключ сразу перестаёт работать. Отзыв ключа также отклоняет его черновики, которые ещё никто не запустил (причина key_revoked); уже запущенные черновики продолжаются.
  • Уведомления. Телефон каждого участника получает уведомление, когда ключ подтверждён или отозван. Если ваша команда видит неожиданное уведомление, отзовите ключ.

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

Передавайте ключ в каждом вызове и только в этом заголовке:

Authorization: Bearer obk_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefg

Никогда не помещайте ключ в URL, строку запроса или тело запроса.

curl -sS https://api.bittool.com/ownbit/api/v1/whoami \
  -H "Authorization: Bearer $OWNBIT_API_KEY"
  • На любую проблему с ключом ответ один и тот же: 401 {"error":{"code":"unauthorized","message":"Invalid or unusable API key"},"requestId":"req_…"}. Сюда входят отсутствующий или неверно сформированный заголовок, неизвестный ключ, ещё не подтверждённый ключ, отозванный или истёкший ключ, адрес вызывающей стороны вне списка разрешённых адресов ключа, создатель ключа, который больше не участник или больше не имеет роли подписанта, и мультиподпись, которая больше не активна. Участники мультиподписи видят в веб-консоли последний отказ каждого ключа и его причину, поэтому спросите их, если не можете понять, в чём дело.
  • Действительный ключ без разрешения, нужного для вызова, получает 403 forbidden.
  • Ответ 401 не исчезнет при повторных попытках. Остановитесь и попросите человека разобраться (раздел 10.4: повторяющиеся неудачи блокируют ваш адрес).

6. Вызовы

6.1 GET /whoami

{"keyId":"kid_0123456789abcdef","name":"Payout bot","hint":"defg","perms":["drafts:submit","drafts:read"],
 "createdAt":"2026-11-17T06:00:00.000Z","expiresAt":"2027-02-15T06:05:00.000Z","ipAllow":["203.0.113.0/24"],
 "dailyLines":1000,"linesUsed24h":200,
 "callsToday":2880,"dailyCalls":10000,"multisigCallsToday":3105,"multisigDailyCalls":20000,
 "callsResetAt":"2026-11-18T00:00:00.000Z",
 "multisig":{"msId":4001,"chain":"TRX","address":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","name":"Payroll",
   "isEnterprise":true,"requiredNum":2,"ownerNum":4,"symbols":["TRX","USDT"],"defaultSymbol":"TRX"}}
  • dailyLines, linesUsed24h: лимит строк ключа и число строк, отправленных им за последние 24 часа.
  • callsToday, dailyCalls: вызовы этого ключа с 00:00 UTC (включая этот вызов) и его дневной лимит вызовов. multisigCallsToday, multisigDailyCalls: то же для всех ключей мультиподписи вместе. callsResetAt: когда дневные счётчики обнуляются (раздел 10).
  • multisig.symbols: символы, в которых можно платить. multisig.defaultSymbol: символ, в котором платит строка без symbol. В мультиподписи TRON это TRX, а не USDT: передавайте symbol в каждой строке (раздел 6.2).
  • requiredNum из ownerNum: подписи, необходимые для каждого платежа.

6.2 POST /drafts

Один вызов создаёт черновик, а последующие вызовы с тем же clientRequestId меняют его: добавляют строки, заменяют строки и удаляют строки, каждая из которых обозначена вашим собственным lineId. Черновик можно менять, только пока его никто не запустил (статус submitted).

Запрос (ровно эти ключи; всё прочее — 400 invalid_request):

{"clientRequestId":"payout-2026-11-17-001",
 "lines":[{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001"},
          {"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT"}]}

Последующий вызов, который добавляет строку, изменяет po-1 и удаляет po-2:

{"clientRequestId":"payout-2026-11-17-001",
 "lines":[{"lineId":"po-3","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"0.03","symbol":"USDT"},
          {"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"130","symbol":"USDT","memo":"INV-1001"}],
 "remove":["po-2"]}
ПолеПравило
clientRequestIdОт 1 до 64 символов из [A-Za-z0-9._:-], ваш собственный идентификатор этого списка выплат. Обозначает один черновик мультиподписи, навсегда (раздел 6.2.2)
linesОт 0 до 500 объектов, каждый только с ключами ниже. Первый вызов должен передать хотя бы один
removeНеобязательно. Значения lineId строк, которые нужно убрать из черновика. lineId, которого в черновике нет, игнорируется, поэтому повторная попытка безопасна. Один и тот же lineId не может быть одновременно в lines и в remove
lineIdОбязательно. От 1 до 64 символов из [A-Za-z0-9._:/-], ваш собственный идентификатор строки, уникальный в пределах черновика (с другим clientRequestId отсчёт начинается заново). lineId, который в черновике уже есть, заменяет эту строку на её месте; новый добавляется в конец. Возвращается вам; никогда не попадает в блокчейн, никогда не показывается подписантам
toАдрес TRON (34 символа, base58check). Не собственный адрес мультиподписи, не нулевой адрес TRON T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb, не контракт USDT (токены, отправленные туда, теряются)
amountСтрока, соответствующая ^(0|[1-9][0-9]*)(\.[0-9]+)?$, больше нуля, не более 6 знаков после запятой в том виде, как отправлено ("1.0000000" отклоняется с amount_decimals; "80.500000" принимается и сохраняется как "80.5"), не более 9223372036854775807 в наименьших единицах. Передавайте строку, никогда не число JSON. Ownbit хранит её в каноническом виде: конечные нули дробной части отбрасываются, затем — оставшаяся одинокая точка ("80.50" становится "80.5", "2.0" становится "2")
symbolTRX или USDT. Передавайте его в каждой строке. Если его не указать, строка платит в defaultSymbol мультиподписи, а в мультиподписи TRON это TRX: выплата в USDT без symbol превратилась бы в выплату того же числа TRX. В мультиподписи должен быть этот символ (в ответе whoami — поле symbols)
memoНеобязательно. Не более 80 символов; без , ' " \; без управляющих символов, переводов строки и невидимых символов; без пробела в начале или в конце; не зарезервированная пометка (начинающаяся с admin:, содержащая -no-broadcast или оканчивающаяся на ***br***, в любом регистре). Отсутствие поля и "" равнозначны

Сначала Ownbit удаляет строки из remove, затем заменяет или добавляет каждую строку из lines, затем проверяет черновик целиком: не более 500 строк, хотя бы одна, и никакие две строки не имеют одинаковые to, канонический amount и symbol (блокчейн отклонил бы вторую как дубликат, пока первая ждёт подписей). Каждая переданная вами строка проверяется так же, как при первом вызове; если что-либо отклонено, ничего не меняется.

Ответы:

СтатусТелоКогда
201{"draft":<draft>}Новый черновик, статус submitted, ревизия 1, все строки pending
200{"draft":<draft>}Черновик изменился (его revision выросла на единицу) или вызов ничего не изменил (повторная попытка): черновик в его текущем виде
409 not_editabledetails.draftId, details.statusЧерновик больше не в статусе submitted (подписант запустил его, или он был отозван, отклонён или истёк): ничего не изменилось
409 idempotency_conflictclientRequestId уже использован другим ключом той же мультиподписи
410 goneЧерновик с этим clientRequestId удалён (срок хранения, раздел 7.3)
422 invalid_linesdetails.errorsОдна или несколько строк недопустимы или черновик остался бы пустым; ничего не изменилось
429 daily_limitdetails.scopeБыл бы превышен лимит строк ключа или мультиподписи за 24 часа (раздел 10). С details.neverFits: true и без Retry-After в одном этом вызове больше строк, чем позволяет лимит, поэтому ожидание никогда не поможет: передавайте меньше строк за вызов

details.errors перечисляет первые 50 проблем в виде {"line":<index in lines>,"lineId":"po-1","field":"amount","reason":"amount_decimals"}. Причины: line_id_invalid, line_id_duplicate, address_invalid, address_self, address_zero, address_contract, amount_invalid, amount_zero, amount_decimals, amount_too_large, symbol_unknown, symbol_unavailable, memo_invalid, memo_reserved, duplicate_line, draft_empty (line и lineId равны null: после удаления не осталось бы ни одной строки; вместо этого отзовите черновик, раздел 6.5).

6.2.1 Черновик

Полная форма (в списке форма без lines):

{"draftId":"drf_0123456789abcdefghijklmn","clientRequestId":"payout-2026-11-17-001","status":"started","revision":1,
 "createdAt":"2026-11-17T06:10:00.000Z","updatedAt":"2026-11-17T06:31:12.000Z","startedAt":"2026-11-17T06:31:12.000Z","lineCount":2,
 "contentHash":"cc43baacd7df98efac68139dd9be5dba47d4fa0343c034e3fd54098409cf59a4",
 "totals":[{"symbol":"USDT","amount":"205.5"}],"counts":{"started":2},"rejection":null,
 "lines":[{"index":0,"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001",
           "repeated":false,"state":"started"},
          {"index":1,"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT","memo":"",
           "repeated":false,"state":"started"}]}
  • draftId: drf_ и 24 символа из [0-9a-z].
  • revision: 1 у нового черновика, на единицу больше после каждого вызова, который его изменил.
  • startedAt: когда подписант впервые запустил черновик на своём телефоне, иначе null. Не меняется, когда подписант запускает его снова.
  • lines[].lineId: ваш идентификатор строки. lines[].index: её текущая позиция, начиная с 0 (она сдвигается, когда удаляется строка перед ней: сопоставляйте строки по lineId). memo равно "", если не задано.
  • lines[].state: всегда следует за статусом черновика (раздел 7.2). На этапе 1 у строки нет идентификатора транзакции, хеша, числа подписей или ошибки: проверяйте платежи так, как сказано в разделе 8.
  • totals: сумма по каждому символу; counts: число строк в каждом состоянии (только состояния, в которых есть строки).
  • repeated: true, если в другом черновике этой мультиподписи за последние 7 дней есть строка с тем же адресом, суммой и символом. Подписанты видят эту отметку и должны подтвердить её перед запуском черновика; увидев её, проверьте свою систему.
  • rejection: {"reason","note","at"}, если черновик отклонён, иначе null. Причины: whitelist, address, amount, duplicate, other (выбирает подписант в веб-консоли, который может добавить однострочное примечание note), phone (подписант отклонил черновик на своём телефоне; без note) и key_revoked. API никогда не сообщает, какой участник отклонил черновик.

6.2.2 Повторные попытки и изменения

  • clientRequestId обозначает один черновик мультиподписи навсегда: он остаётся занятым, пока хранится его черновик, и ещё 365 дней после удаления черновика (410). Изменять черновик может только ключ, который его создал; другой ключ той же мультиподписи получает 409 idempotency_conflict (после смены ключа используйте новые идентификаторы). Делайте свои идентификаторы уникальными навсегда, например дата плюс порядковый номер.
  • Любой вызов безопасно повторять. После тайм-аута или сетевой ошибки отправьте тот же запрос снова: переданные строки заменят сами себя тем же содержимым, а удалённые строки уже удалены, поэтому ответом будет черновик в текущем виде — никогда не второй черновик и не вторая копия строки.
  • Изменение возможно, только пока черновик в статусе submitted. Как только подписант его запустит, вызов отвечает 409 not_editable: попросите подписантов отклонить строки, которые не должны быть оплачены, и отправьте новые под новым clientRequestId.
  • Подписанты видят черновик таким, каким он был в момент открытия. Если он изменится, пока подписант держит его открытым, консоль откажется его запускать и попросит открыть его заново.
  • Два одновременных вызова с одним идентификатором применяются один за другим.

6.2.3 Хеш содержимого

contentHash — это SHA-256 в нижнем регистре hex от байтов UTF-8 компактного массива JSON из строк черновика в их порядке, каждая из которых записана как {"lineId","to","amount","symbol","memo"} именно в этом порядке, с канонической суммой, причём символ всегда указывается явно, а значение "" пишется для отсутствующего memo. Он меняется при каждом изменении черновика. Для первого запроса выше:

[{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001"},{"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT","memo":""}]

→ cc43baacd7df98efac68139dd9be5dba47d4fa0343c034e3fd54098409cf59a4. Собирайте строку сами (порядок ключей и экранирование какой-либо библиотеки JSON не нужны: ни одно из этих полей не может содержать символ, требующий экранирования). Отпечаток, который видят подписанты, — это первые 16 hex-символов contentHash (здесь cc43baacd7df98ef). Что с ними делать, сказано в разделе 8.

6.3 GET /drafts?since=<cursor>&limit=<n>

Черновики этого ключа, упорядоченные по updatedAt, затем по draftId, после курсора (без since — начиная с самого старого из хранящихся). limit — от 1 до 100, по умолчанию 50.

{"drafts":[<draft without lines>],"nextCursor":"<opaque>","hasMore":false}

updatedAt черновика меняется всякий раз, когда меняется его статус или его строки, поэтому опрос с последним nextCursor видит каждое изменение. Пустая страница возвращает отправленный вами курсор; продолжайте его использовать. Курсор, который не удаётся прочитать, — это 400 invalid_request.

6.4 GET /drafts/{draftId}

200 {"draft":<draft>}. Черновик другого ключа (даже той же мультиподписи) или черновик, который больше не хранится: 404 not_found.

6.5 DELETE /drafts/{draftId}

Отзывает черновик, который ещё никто не запустил. Только пока его статус submitted: каждая строка становится withdrawn, 200 {"draft":<draft>}. Если уже withdrawn: снова 200. Иначе 409 not_withdrawable с details.status. Если подписант уже запустил черновик, попросите подписантов отклонить оставшееся.

7. Статусы

7.1 status черновика

СтатусЗначение
submittedЕго ещё никто не запустил. Только сейчас ваш бот может его изменить (раздел 6.2) или отозвать (раздел 6.5)
startedПодписант запустил его на своём телефоне (когда это произошло впервые, показывает startedAt). Подписант может открыть его и запустить снова, например если телефон остановился на полпути; статус остаётся started
rejectedПодписант отклонил его — в веб-консоли или на своём телефоне (до или после запуска), — или его ключ был отозван до того, как его кто-либо запустил. Причину указывает rejection
withdrawnВаш бот отозвал его
expiredНикто не запустил его в течение 7 дней

Ownbit сообщает только то, что знает наверняка: что подписант запустил черновик на своём телефоне. Какие платежи за этим последовали, Ownbit не узнаёт, поэтому черновик в статусе started может быть оплачен полностью, частично или не оплачен вовсе. Платежи — это транзакции мультиподписи: проверяйте их так, как сказано в разделе 8, и не отправляйте строки запущенного черновика повторно, если подписанты не сообщили вам, что они не были оплачены.

7.2 state строки

state строки всегда совпадает со статусом её черновика: на этапе 1 Ownbit не отслеживает транзакцию каждой строки.

СостояниеЗначение
pendingЧерновик в статусе submitted
startedЧерновик в статусе started
rejected, withdrawn, expiredСтатус черновика

7.3 Срок жизни

Черновик, который никто не запустил, истекает через 7 дней. Запущенный черновик остаётся в статусе started, пока подписант его не отклонит. Отклонённые, отозванные и истёкшие черновики хранятся 30 дней после завершения, а запущенный черновик — 30 дней после последнего изменения; затем они удаляются (GET после этого отвечает 404; тот же clientRequestId отвечает 410 ещё 365 дней).

8. Проверка того, что будет оплачено

Ownbit доставляет ваш список от вашего бота на экраны подписантов. Чтобы убедиться, что по пути ничего не изменилось:

  1. Показывайте clientRequestId и отпечаток (первые 16 hex-символов contentHash) в своём канале согласования, рядом с одобренным списком выплат. У изменённого черновика новый отпечаток: показывайте последний. Подписанты видят оба значения в веб-консоли — их браузер заново вычисляет их по строкам, которые они собираются запустить, — и их просят сверить эти значения с вашей записью. Такая сверка возможна, только если ваша запись о согласовании их показывает.
  2. Заново вычисляйте contentHash (раздел 6.2.3) по строкам каждого прочитанного черновика и сравнивайте его со значением, которое вы вычислили для последней ревизии черновика.
  3. Сами проверяйте платежи мультиподписи в блокчейне. На этапе 1 Ownbit не сообщает транзакцию каждой строки. Как только черновик перешёл в started, сравните его строки с исходящими транзакциями адреса мультиподписи (в ответе whoami — поле multisig.address): получатель, сумма и токен каждого платежа должны совпадать с одной из ваших строк, и каждая строка должна быть оплачена не более одного раза.
  4. Следите за repeated: строка, повторяющая строку другого недавнего черновика, помечается для подписантов; её стоит пометить и в вашей системе.
  5. В корпоративной мультиподписи попросите её участников включить белый список и дневной лимит: тогда даже ошибочный черновик не сможет заплатить на неизвестный адрес или больше лимита. У других мультиподписей белого списка нет, поэтому проверка подписантов — единственная.

9. Ошибки

У каждой ошибки такое тело:

{"error":{"code":"<code>","message":"<English sentence>","details":{}},"requestId":"req_0123456789abcdef"}

message — фиксированное предложение на английском для людей; в программе опирайтесь на code и details. Сообщения никогда не повторяют ваши входные данные.

HTTPcodeКогда
400invalid_requestНе JSON, неверный тип, неизвестное поле, неверный clientRequestId, ни одной строки или больше 500, неверный курсор или лимит, тело запроса, не пришедшее за 10 секунд
401unauthorizedЛюбая проблема с ключом (раздел 5)
403forbiddenДействительный ключ без разрешения на этот вызов
403https_requiredЗапрос пришёл не по HTTPS (отзовите ключ, переданный в нём)
404not_foundНеизвестный путь; черновик, не принадлежащий этому ключу или больше не хранящийся
405method_not_allowedМетод, который путь не принимает (включая OPTIONS)
409idempotency_conflictРаздел 6.2
409not_editableРаздел 6.2 (details.status)
409not_withdrawableРаздел 6.5 (details.status)
410goneclientRequestId, черновик которого удалён
413too_largeТело больше 256 КиБ
415unsupported_media_typePOST, который не является JSON
422invalid_linesРаздел 6.2 (details.errors)
429rate_limited, daily_limitЛимит (раздел 10), с Retry-After, details.scope, details.limit, details.retryAfter
500internalОшибка на стороне Ownbit; повторите позже
503unavailableAPI отключён или сейчас не может ответить; при перегрузке — с details.scope api_busy и Retry-After

Ответ 429 с областью edge или 413, пришедший от защитного слоя перед API, имеет ту же форму с "requestId":null.

10. Ограничение частоты запросов и дневные лимиты

10.1 Лимиты

ЛимитЗначениеdetails.scopecode
Запросы с одного адреса, всплеск20 в секунду (всплески до 40), 20 открытых соединенийedgerate_limited
Вызовы на ключ10 в секундуkey_secondrate_limited
Вызовы на ключ300 в минутуkey_minuterate_limited
POST /drafts на ключ60 в часkey_submit_hourrate_limited
Одновременно выполняемые вызовы на ключ2key_concurrentrate_limited
Одновременно выполняемые вызовы на мультиподпись (все её ключи)4multisig_concurrentrate_limited
Вызовы с адреса (действительные ключи)600 в минуту; никогда не отклоняет ключ, чей список разрешённых адресов не пуст и содержит этот адресip_minuterate_limited
Вызовы на ключ10 000 в деньkey_dayrate_limited
Вызовы на мультиподпись (все её ключи вместе)20 000 в деньmultisig_dayrate_limited
Вызовы с адреса (действительные ключи)50 000 в день; никогда не отклоняет ключ, чей список разрешённых адресов не пуст и содержит этот адресip_dayrate_limited
Вызовы с адреса (действительные ключи), жёсткий предел200 000 в день, для всех ключейip_day (details.limit 200000)rate_limited
Неудачные вызовы с адреса20 в минуту; при превышении адрес приостанавливается на 10 минутip_failuresrate_limited
Неудачные вызовы с адреса200 в день; при превышении адрес блокируется на 24 часаip_blockedrate_limited
Неудачные вызовы из сети (/24)1 000 в день; при превышении сеть блокируется на 24 часаnet_blockedrate_limited
Строки платежей на ключсобственный лимит ключа (от 1 до 10 000, по умолчанию 1 000) за любые 24 часаkey_lines_24hdaily_limit
Строки платежей на мультиподпись10 000 за любые 24 часаmultisig_lines_24hdaily_limit
Весь API перегружен(защищает сервис)api_busy (HTTP 503)unavailable
  • День — это календарные сутки по UTC: лимиты вызовов и лимиты неудач обнуляются в 00:00 UTC (08:00 по пекинскому времени). Оба лимита строк скользящие: любые 24 часа.
  • Что засчитывается. Каждый вызов с действительным ключом засчитывается в лимиты ключа, мультиподписи и адреса: в том числе чтение, вызовы, отклонённые после того, как ключ был принят (403, 404, 409, 422 или 429 лимита строк), и повторный POST /drafts. Вызов, отклонённый ограничением частоты или лимитом, не засчитывается ни в один из них, поэтому переждать Retry-After всегда помогает. Вызов, ключ которого отклонён (401), засчитывается только в неудачные вызовы его адреса и сети.
  • Приостановленный или заблокированный адрес или сеть (приостановка на 10 минут или блокировка на 24 часа) по-прежнему обслуживает каждый ключ, который действителен и чей список разрешённых адресов допускает этот адрес (пустой список допускает все). Там отклоняются только вызовы с плохими ключами и с ключами, чей список разрешённых адресов не допускает этот адрес. Поэтому действительный ключ никогда не блокируется из-за чужих неудач с того же адреса.
  • Лимиты на адрес общие для всех, кто с него обращается. Ключ, чей список разрешённых адресов не пуст и содержит этот адрес, не отклоняется лимитами 600 в минуту и 50 000 в день, но лимит всплесков (20 в секунду) и жёсткий предел (200 000 в день) учитывают всех на этом адресе, поэтому за общим NAT, на CI-раннере или за общим облачным исходящим адресом другие всё равно могут замедлять ваши вызовы; а 429 с областью ip_minute или ip_day говорит о том, что другие на вашем адресе активно им пользуются. Используйте выделенный исходящий адрес.

10.2 Ответы

Лимит отвечает 429 (или 503 для api_busy) с телом:

{"error":{"code":"rate_limited","message":"Daily call limit of this key reached",
  "details":{"scope":"key_day","limit":10000,"retryAfter":31260}},"requestId":"req_0123456789abcdef"}

и заголовком Retry-After: 31260: сколько целых секунд ждать (не меньше 1). Ожидание длится до конца окна, приостановки или блокировки; до 00:00 UTC — для дневных лимитов вызовов; для лимитов строк — пока достаточно ваших самых старых строк не выйдет за пределы 24 часов (не меньше 60 секунд); 1 — для edge и двух областей _concurrent; для api_busy — от 1 до примерно 90 секунд, со случайной составляющей, чтобы отклонённые клиенты не возвращались все одновременно. Если отказывают сразу несколько лимитов, ответ называет тот, у которого ожидание дольше. details.limit — значение этого лимита (не указывается для api_busy). Единственный 429 без Retry-After — черновик, который никогда не уложится в свой лимит строк: details.neverFits равно true, а details.retryAfter равно null (раздел 6.2).

Сообщения: Too many requests from this address (edge, ip_minute), Too many failed requests from this address (ip_failures), This address is blocked after too many failed requests (ip_blocked), This network is blocked after too many failed requests (net_blocked), Too many requests for this key (key_second, key_minute), Too many concurrent requests for this key (key_concurrent), Too many concurrent requests for this multisig (multisig_concurrent), Too many drafts submitted with this key in the last hour (key_submit_hour), Daily call limit of this key reached (key_day), Daily call limit of this multisig reached (multisig_day), Daily call limit of this address reached (ip_day), Line limit of this key for 24 hours reached (key_lines_24h), Line limit of this multisig for 24 hours reached (multisig_lines_24h), The API is busy, retry later (api_busy).

10.3 Заголовки

Каждый ответ на вызов, ключ которого был принят (успешные ответы, последующие ошибки и его 429), содержит:

ЗаголовокЗначение
X-RateLimit-LimitДневной лимит вызовов ключа (10000)
X-RateLimit-RemainingСколько осталось на сегодня после этого вызова: меньшее из остатков ключа и его мультиподписи
X-RateLimit-ResetБлижайшие 00:00 UTC в секундах Unix (на 2026-11-17: 1794960000)

Ответы 401, 429 для edge, ip_failures, ip_blocked или net_blocked, а также 503 не содержат ни одного из них. GET /whoami возвращает те же счётчики в теле (callsToday, multisigCallsToday, callsResetAt).

10.4 Как правильно написанный бот опрашивает API и отступает

  • Опрашивайте GET /drafts?since=<last nextCursor> каждые 30 секунд, одним опрашивающим процессом на ключ. Это 2 880 вызовов в день. Если ключ используют несколько копий вашего бота, пусть опрашивает одна из них и делится прочитанным. Сохраняйте последний nextCursor между перезапусками; пустая страница возвращает его без изменений. Когда hasMore равно true, сразу читайте следующую страницу.
  • Никогда не опрашивайте чаще, чем позволяет бюджет: не чаще одного раза в 86 400 × 2 / X-RateLimit-Limit секунд (17,3 секунды при значении по умолчанию 10 000), чтобы опрос расходовал не больше половины дневных вызовов. Один только опрос каждые 10 секунд занимает 8 640 вызовов и оставляет около 1 300 на всё остальное; две копии бота, делающие так на одном ключе, получат отказ ещё до конца дня.
  • Читайте отдельный черновик, только когда вам нужны его строки, то есть когда его updatedAt изменился в списке, и не чаще раза в минуту на черновик. Не опрашивайте каждый черновик по отдельности.
  • Следите за X-RateLimit-Remaining. Когда он опускается ниже десятой части X-RateLimit-Limit, опрашивайте реже. Помните, что он общий с другими ключами мультиподписи.
  • При 429: подождите Retry-After секунд плюс небольшую случайную задержку, затем повторите. Не повторяйте раньше: ответ будет тем же. При key_day или multisig_day сохраните курсор и продолжите после X-RateLimit-Reset.
  • При 503: если есть Retry-After, подождите это время плюс случайные 0–30 секунд; если нет — отступайте экспоненциально от 30 секунд до 10 минут.
  • При сетевой ошибке или 500 во время POST /drafts: отправьте тот же запрос снова с тем же clientRequestId (раздел 6.2.2), выдержав паузу, как описано выше.
  • При 401: перестаньте использовать ключ и оповестите человека. Повторные попытки с отклонённым ключом никогда не помогают, а более 200 неудач за день блокируют ваш адрес на 24 часа для всех плохих ключей (ваши действительные ключи продолжают работать с него, раздел 10.1).
  • Учитывайте полночь по UTC: ключ или мультиподпись, израсходовавшие дневные вызовы, получают отказ до 00:00 UTC. Возобновляйте работу после этого со случайной задержкой 0–30 секунд, а не ровно в эту секунду.

11. Рекомендации по безопасности

  • Только HTTPS. Никогда не отправляйте ключ по обычному HTTP; если это случилось, отзовите ключ. Проверяйте сертификат сервера как обычно.
  • Храните ключ на своём сервере, в хранилище секретов. Никогда — в браузере, мобильном приложении, репозитории, строке журнала, URL, тикете или сообщении в чате. Ownbit никогда не просит вас сообщить его.
  • Задайте каждому ключу список разрешённых адресов IPv4 — фиксированных исходящих адресов ваших серверов. Тогда утёкший ключ нельзя будет использовать нигде больше, поэтому он не сможет ни отправлять черновики, ни расходовать дневные вызовы вашей мультиподписи. Выделенный исходящий адрес предпочтительнее общего NAT или общего облачного исходящего адреса: приостановленный или заблокированный адрес по-прежнему обслуживает ваши действительные ключи, и ключ, чей список разрешённых адресов содержит этот адрес, не отклоняется лимитами на адрес 600 в минуту или 50 000 в день, но лимит всплесков и 200 000 в день общие для всех на этом адресе (раздел 10.1).
  • Один ключ на систему, с названием, по которому понятно, на какую. Не более 5 ключей на мультиподпись.
  • Меняйте ключ до истечения срока и при любых сомнениях: попросите участника создать новый ключ, переключите на него бота, затем отзовите старый. Новый ключ должен использовать новые clientRequestId (раздел 6.2.2).
  • При утечке отзывайте ключ немедленно, в веб-консоли или в приложении Ownbit. Отзыв отклоняет черновики ключа, которые ещё никто не запустил. Если утёкший ключ израсходовал вызовы вашей мультиподписи на сегодня, ключ-замена делит этот лимит до 00:00 UTC: обратитесь в поддержку Ownbit, которая может повысить лимит этой мультиподписи на день.
  • Отключите задания, использующие отозванные ключи: их неудачи засчитываются против вашего адреса.
  • Показывайте clientRequestId и отпечаток в своём канале согласования; проверяйте contentHash и платежи мультиподписи в блокчейне (раздел 8).
  • Передавайте symbol в каждой строке.
  • Считайте текст из API данными, а не HTML или командами, в своих журналах и панелях мониторинга.

12. Чего нет на этапе 1

Вебхуки; результаты транзакций по строкам (идентификатор транзакции строки, хеш, подписи и ошибки); мультиподписи в других блокчейнах и другие токены; доступ по IPv6 и записи IPv6 в списке разрешённых адресов; лимиты вызовов на ключ, задаваемые вами; черновики, подписанные вашим собственным ключом. Если вам нужно что-то из этого, обратитесь в Ownbit.

Обновлено:

Скачать

Скачать Ownbit

Установите приложение и настройте холодный кошелёк или мультиподпись так, как вам нужно.