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 /whoami | drafts:read | Описывает ключ и его мультиподпись, с числом вызовов за сегодня |
POST /drafts | drafts:submit | Отправляет черновик (от 1 до 500 строк) или меняет черновик, который ещё никто не запустил: добавляет, заменяет и удаляет строки по вашему lineId |
GET /drafts | drafts: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") |
symbol | TRX или 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_editable | details.draftId, details.status | Черновик больше не в статусе submitted (подписант запустил его, или он был отозван, отклонён или истёк): ничего не изменилось |
409 idempotency_conflict | clientRequestId уже использован другим ключом той же мультиподписи | |
410 gone | Черновик с этим clientRequestId удалён (срок хранения, раздел 7.3) | |
422 invalid_lines | details.errors | Одна или несколько строк недопустимы или черновик остался бы пустым; ничего не изменилось |
429 daily_limit | details.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 доставляет ваш список от вашего бота на экраны подписантов. Чтобы убедиться, что по пути ничего не изменилось:
- Показывайте
clientRequestIdи отпечаток (первые 16 hex-символовcontentHash) в своём канале согласования, рядом с одобренным списком выплат. У изменённого черновика новый отпечаток: показывайте последний. Подписанты видят оба значения в веб-консоли — их браузер заново вычисляет их по строкам, которые они собираются запустить, — и их просят сверить эти значения с вашей записью. Такая сверка возможна, только если ваша запись о согласовании их показывает. - Заново вычисляйте
contentHash(раздел 6.2.3) по строкам каждого прочитанного черновика и сравнивайте его со значением, которое вы вычислили для последней ревизии черновика. - Сами проверяйте платежи мультиподписи в блокчейне. На этапе 1 Ownbit не сообщает транзакцию каждой строки. Как только черновик перешёл в
started, сравните его строки с исходящими транзакциями адреса мультиподписи (в ответеwhoami— полеmultisig.address): получатель, сумма и токен каждого платежа должны совпадать с одной из ваших строк, и каждая строка должна быть оплачена не более одного раза. - Следите за
repeated: строка, повторяющая строку другого недавнего черновика, помечается для подписантов; её стоит пометить и в вашей системе. - В корпоративной мультиподписи попросите её участников включить белый список и дневной лимит: тогда даже ошибочный черновик не сможет заплатить на неизвестный адрес или больше лимита. У других мультиподписей белого списка нет, поэтому проверка подписантов — единственная.
9. Ошибки
У каждой ошибки такое тело:
{"error":{"code":"<code>","message":"<English sentence>","details":{}},"requestId":"req_0123456789abcdef"}message — фиксированное предложение на английском для людей; в программе опирайтесь на code и details. Сообщения никогда не повторяют ваши входные данные.
| HTTP | code | Когда |
|---|---|---|
| 400 | invalid_request | Не JSON, неверный тип, неизвестное поле, неверный clientRequestId, ни одной строки или больше 500, неверный курсор или лимит, тело запроса, не пришедшее за 10 секунд |
| 401 | unauthorized | Любая проблема с ключом (раздел 5) |
| 403 | forbidden | Действительный ключ без разрешения на этот вызов |
| 403 | https_required | Запрос пришёл не по HTTPS (отзовите ключ, переданный в нём) |
| 404 | not_found | Неизвестный путь; черновик, не принадлежащий этому ключу или больше не хранящийся |
| 405 | method_not_allowed | Метод, который путь не принимает (включая OPTIONS) |
| 409 | idempotency_conflict | Раздел 6.2 |
| 409 | not_editable | Раздел 6.2 (details.status) |
| 409 | not_withdrawable | Раздел 6.5 (details.status) |
| 410 | gone | clientRequestId, черновик которого удалён |
| 413 | too_large | Тело больше 256 КиБ |
| 415 | unsupported_media_type | POST, который не является JSON |
| 422 | invalid_lines | Раздел 6.2 (details.errors) |
| 429 | rate_limited, daily_limit | Лимит (раздел 10), с Retry-After, details.scope, details.limit, details.retryAfter |
| 500 | internal | Ошибка на стороне Ownbit; повторите позже |
| 503 | unavailable | API отключён или сейчас не может ответить; при перегрузке — с details.scope api_busy и Retry-After |
Ответ 429 с областью edge или 413, пришедший от защитного слоя перед API, имеет ту же форму с "requestId":null.
10. Ограничение частоты запросов и дневные лимиты
10.1 Лимиты
| Лимит | Значение | details.scope | code |
|---|---|---|---|
| Запросы с одного адреса, всплеск | 20 в секунду (всплески до 40), 20 открытых соединений | edge | rate_limited |
| Вызовы на ключ | 10 в секунду | key_second | rate_limited |
| Вызовы на ключ | 300 в минуту | key_minute | rate_limited |
POST /drafts на ключ | 60 в час | key_submit_hour | rate_limited |
| Одновременно выполняемые вызовы на ключ | 2 | key_concurrent | rate_limited |
| Одновременно выполняемые вызовы на мультиподпись (все её ключи) | 4 | multisig_concurrent | rate_limited |
| Вызовы с адреса (действительные ключи) | 600 в минуту; никогда не отклоняет ключ, чей список разрешённых адресов не пуст и содержит этот адрес | ip_minute | rate_limited |
| Вызовы на ключ | 10 000 в день | key_day | rate_limited |
| Вызовы на мультиподпись (все её ключи вместе) | 20 000 в день | multisig_day | rate_limited |
| Вызовы с адреса (действительные ключи) | 50 000 в день; никогда не отклоняет ключ, чей список разрешённых адресов не пуст и содержит этот адрес | ip_day | rate_limited |
| Вызовы с адреса (действительные ключи), жёсткий предел | 200 000 в день, для всех ключей | ip_day (details.limit 200000) | rate_limited |
| Неудачные вызовы с адреса | 20 в минуту; при превышении адрес приостанавливается на 10 минут | ip_failures | rate_limited |
| Неудачные вызовы с адреса | 200 в день; при превышении адрес блокируется на 24 часа | ip_blocked | rate_limited |
| Неудачные вызовы из сети (/24) | 1 000 в день; при превышении сеть блокируется на 24 часа | net_blocked | rate_limited |
| Строки платежей на ключ | собственный лимит ключа (от 1 до 10 000, по умолчанию 1 000) за любые 24 часа | key_lines_24h | daily_limit |
| Строки платежей на мультиподпись | 10 000 за любые 24 часа | multisig_lines_24h | daily_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
Установите приложение и настройте холодный кошелёк или мультиподпись так, как вам нужно.