Ownbit MultiSig API v1 (phase 1)
Let your own system hand payout lists to an Ownbit MultiSig. An API key created in the Web Console submits drafts; signers review every line and start them on their phones. The API never moves funds.
Version of 2026-11-18 (drafts change by lineId; five draft statuses). This document describes phase 1 of the API. All keys, hashes, addresses and IP addresses in it are made-up examples (the IP addresses come from the ranges reserved for documentation); the USDT-TRC20 contract address is the real, public one.
1. What the API does
Your system (below, "your bot") hands Ownbit a list of payouts for one Ownbit multisig, a draft, and later reads what became of it: started by a signer, rejected, withdrawn or expired.
The API never moves funds. A draft becomes payments only when a signer of the multisig opens it in the Ownbit web console, starts it on their own phone, and enough members of the multisig sign each transaction (m of n). Signers see every line before they start it, every check Ownbit makes on a payment still runs, and a signer can reject a draft. A key cannot sign, start a payment, approve, reject, or change the multisig's policy, whitelist or members.
What a key can do:
| Call | Permission | What it does |
|---|---|---|
GET /whoami | drafts:read | Describes the key and its multisig, with today's call counts |
POST /drafts | drafts:submit | Submits a draft (1 to 500 lines), or changes one nobody has started: adds, replaces and removes lines by your lineId |
GET /drafts | drafts:read | Lists this key's drafts, oldest change first, with a cursor |
GET /drafts/{draftId} | drafts:read | Reads one draft with its lines |
DELETE /drafts/{draftId} | drafts:submit | Withdraws a draft that nobody has started |
2. Phase 1 scope
- Multisigs on TRON only. Lines pay in
TRXorUSDT(USDT-TRC20, contractTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t); both have 6 decimals. - IPv4 only. The API is reached over IPv4 only (
api.bittool.comhas no IPv6 address in phase 1), and a key's allowlist holds IPv4 ranges. - No webhooks. Your bot polls (section 10 says how often).
- At most 500 lines a draft. A signer may start a large draft as two requests on their phone; that does not change anything for you.
3. Base URL and transport
https://api.bittool.com/ownbit/api/v1- IPv4 only in phase 1: the name has no IPv6 address, so a server with both IPv4 and IPv6 calls over IPv4 and is matched against its IPv4 allowlist.
- HTTPS only. A request that does not arrive over HTTPS is refused with
403 https_requiredand is never redirected. A key that has been sent over plain HTTP must be treated as leaked: revoke it and create another. HTTPS answers carryStrict-Transport-Security: max-age=31536000. - JSON in UTF-8.
POSTrequests sendContent-Type: application/json(a; charset=utf-8suffix is fine). A request body is at most 256 KiB. - Times are ISO 8601 strings in UTC with milliseconds, for example
2026-11-17T06:00:00.000Z. - Every answer carries
Cache-Control: no-store,Pragma: no-cacheandX-Request-Id(req_followed by 16 characters of[0-9a-z]). Error bodies repeat it asrequestId. Quote it when you contact support. - No CORS. No browser page can call the API: call it from your server.
- Strict requests, open answers. A request with a field the API does not know is refused (
400 invalid_request). Answers may gain new fields over time: ignore fields you do not know.
4. Keys
- Where they come from. A member of the multisig creates a key in the Ownbit web console, on the multisig's API tab (any member with the signer role can), and authorizes it on their phone with the Ownbit app. The key is shown once, in that browser tab, right after the phone authorizes it. Ownbit keeps only a hash of it and cannot show it again: if it is lost, revoke it and create another.
- Format.
obk_followed by 43 characters of[0-9A-Za-z](47 characters in all, about 256 bits of randomness). Everywhere Ownbit shows a key, it shows only its last 4 characters, asobk_…defg. - Options chosen at creation. A name (at most 30 characters, unique among the multisig's keys); validity of 30, 90 (default), 180 or 365 days, 2 years or 5 years, counted from the phone's authorization; an IPv4 allowlist of up to 20 ranges, each from
/8to/32(an empty list means any address); and the most payment lines the key may submit in any 24 hours (1 to 10,000, default 1,000). - Permissions. Every phase 1 key has
drafts:submitanddrafts:read. - One multisig. A key covers one multisig address: its TRX and, where it exists, its USDT at that address. Ownbit may list one address as several multisigs, one per token; they share the same keys. A key never sees another multisig's data.
- At most 5 keys per multisig (pending ones included).
- Revocation. Any member can revoke a key at any time, in the web console or in the Ownbit app. A revoked or expired key fails at once. Revoking a key also rejects its drafts that nobody has started (reason
key_revoked); drafts already started go on. - Notifications. Every member's phone is told when a key is authorized or revoked. If your team sees such a notice it did not expect, revoke the key.
5. Authentication
Send the key on every call, and only in this header:
Authorization: Bearer obk_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefgNever put a key in a URL, a query string or a body.
curl -sS https://api.bittool.com/ownbit/api/v1/whoami \
-H "Authorization: Bearer $OWNBIT_API_KEY"- Every key problem gets the same answer:
401 {"error":{"code":"unauthorized","message":"Invalid or unusable API key"},"requestId":"req_…"}. That covers a missing or malformed header, an unknown key, a key not yet authorized, a revoked or expired key, a caller address outside the key's allowlist, a creator who is no longer a member or no longer has the signer role, and a multisig that is no longer active. The members of the multisig see each key's last refusal and its reason in the web console, so ask them when you cannot tell why. - A valid key without the permission a call needs gets
403 forbidden. - A
401does not go away by retrying. Stop, and have a person look (section 10.4: repeated failures block your address).
6. Calls
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: the key's line limit and the lines it submitted in the last 24 hours.callsToday,dailyCalls: this key's calls counted since 00:00 UTC (this call included) and its daily call cap.multisigCallsToday,multisigDailyCalls: the same for all keys of the multisig together.callsResetAt: when the daily counts restart (section 10).multisig.symbols: the symbols you can pay in.multisig.defaultSymbol: the symbol a line withoutsymbolpays in. On a TRON multisig that isTRX, notUSDT: sendsymbolon every line (section 6.2).requiredNumofownerNum: the signatures each payment needs.
6.2 POST /drafts
One call makes a draft, and later calls with the same clientRequestId change it: they add lines, replace lines and remove lines, each line named by your own lineId. A draft can change only while nobody has started it (status submitted).
Request (exactly these keys; anything else is 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"}]}A later call that adds a line, changes po-1 and removes 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"]}| Field | Rule |
|---|---|
clientRequestId | 1 to 64 of [A-Za-z0-9._:-], your own id for this payout list. It names one draft of the multisig, for good (section 6.2.2) |
lines | 0 to 500 objects, each with only the keys below. The first call must send at least one |
remove | Optional. The lineIds of lines to take out of the draft. A lineId the draft does not have is ignored, so a retry is safe. A lineId may not be both in lines and in remove |
lineId | Required. 1 to 64 of [A-Za-z0-9._:/-], your own id for the line, unique within the draft (another clientRequestId starts afresh). A lineId the draft already has replaces that line in place; a new one is added at the end. Returned to you; never put on chain, never shown to signers |
to | A TRON address (34 characters, base58check). Not the multisig's own address, not the TRON zero address T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb, not the USDT contract (tokens sent there are lost) |
amount | A string matching ^(0|[1-9][0-9]*)(\.[0-9]+)?$, above zero, at most 6 decimals counted as sent ("1.0000000" is refused with amount_decimals; "80.500000" is accepted and stored "80.5"), at most 9223372036854775807 in the smallest unit. Send a string, never a JSON number. Ownbit stores it canonical: trailing zeros of the fraction dropped, then a bare point ("80.50" becomes "80.5", "2.0" becomes "2") |
symbol | TRX or USDT. Send it on every line. If you leave it out, the line pays in the multisig's defaultSymbol, which on a TRON multisig is TRX: a USDT payout without symbol would become a TRX payout of the same number. The multisig must hold that symbol (whoami's symbols) |
memo | Optional. At most 80 characters; none of , ' " \; no control, line-break or invisible characters; no space at the start or end; not a reserved memo (starting with admin:, containing -no-broadcast, or ending in ***br***, in any case). Missing and "" are the same |
Ownbit first removes the lines of remove, then replaces or adds each line of lines, then checks the draft as a whole: at most 500 lines, at least one, and no two lines with the same to, canonical amount and symbol (the chain would refuse the second as a duplicate while the first waits for signatures). Every line you send is checked as on the first call; if anything is refused, nothing changes.
Answers:
| Status | Body | When |
|---|---|---|
201 | {"draft":<draft>} | A new draft, status submitted, revision 1, every line pending |
200 | {"draft":<draft>} | The draft changed (its revision went up by one), or the call changed nothing (a retry): the draft as it now stands |
409 not_editable | details.draftId, details.status | The draft is no longer submitted (a signer started it, or it was withdrawn, rejected or expired): nothing changed |
409 idempotency_conflict | The clientRequestId was used by another key of the same multisig | |
410 gone | The draft of this clientRequestId has been deleted (retention, section 7.3) | |
422 invalid_lines | details.errors | One or more lines are invalid, or the draft would be empty; nothing changed |
429 daily_limit | details.scope | The key's or the multisig's line limit for 24 hours would be passed (section 10). With details.neverFits: true and no Retry-After, this call alone has more lines than the limit, so waiting never helps: send fewer lines per call |
details.errors lists the first 50 problems as {"line":<index in lines>,"lineId":"po-1","field":"amount","reason":"amount_decimals"}. Reasons: 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 and lineId are null: removing would leave no line; withdraw the draft instead, section 6.5).
6.2.1 The draft
The full form (the list's form has no 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_followed by 24 characters of[0-9a-z].revision: 1 for a new draft, one more after each call that changed it.startedAt: when a signer first started the draft on their phone, elsenull. It does not change when a signer starts it again.lines[].lineId: your id of the line.lines[].index: its position now, from 0 (it moves when a line before it is removed: match lines bylineId).memois""when absent.lines[].state: always follows the draft's status (section 7.2). In phase 1 a line carries no transaction id, hash, signature count or error: check the payments as section 8 says.totals: the sum per symbol;counts: the number of lines in each state (only states with lines).repeated:truewhen another draft of this multisig from the last 7 days has a line with the same address, amount and symbol. Signers see the mark and must confirm it before they start the draft; check your own system when you see it.rejection:{"reason","note","at"}when the draft was rejected, elsenull. Reasons:whitelist,address,amount,duplicate,other(chosen by a signer in the web console, who may add a one-linenote),phone(a signer rejected it on their phone; nonote), andkey_revoked. The API never says which member rejected.
6.2.2 Retries and changes
clientRequestIdnames one draft of the multisig for good: it stays used while its draft is kept, and for 365 days after the draft is deleted (410). Only the key that made the draft can change it; another key of the same multisig gets409 idempotency_conflict(after a key rotation, use new ids). Make your ids unique forever, for example a date plus a sequence number.- Every call is safe to retry. After a timeout or a network error, send the same request again: lines you sent replace themselves with the same content and removed lines are already gone, so the answer is the draft as it stands, never a second draft or a second copy of a line.
- A change is possible only while the draft is
submitted. Once a signer starts it, a call answers409 not_editable: ask the signers to reject lines that must not be paid, and send new ones under a newclientRequestId. - Signers see the draft as it is when they open it. If it changes while a signer has it open, their console refuses to start it and asks them to open it again.
- Two concurrent calls with the same id are applied one after the other.
6.2.3 The content hash
contentHash is the lower-case hex SHA-256 of the UTF-8 bytes of the compact JSON array of the draft's lines in their order, each written as {"lineId","to","amount","symbol","memo"} in that order, with the canonical amount, the symbol always written out and "" for a missing memo. It changes with every change of the draft. For the first request above:
[{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001"},{"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT","memo":""}]→ cc43baacd7df98efac68139dd9be5dba47d4fa0343c034e3fd54098409cf59a4. Build the string yourself (no JSON library's key order or escaping is needed: none of these fields may hold a character that needs escaping). The fingerprint signers see is the first 16 hex characters of contentHash (cc43baacd7df98ef here). Section 8 says what to do with them.
6.3 GET /drafts?since=<cursor>&limit=<n>
This key's drafts, ordered by updatedAt, then draftId, after the cursor (without since: from the oldest kept). limit is 1 to 100, default 50.
{"drafts":[<draft without lines>],"nextCursor":"<opaque>","hasMore":false}A draft's updatedAt moves whenever its status or its lines change, so polling with the last nextCursor sees every change. An empty page returns the cursor you sent; keep using it. A cursor that cannot be read is 400 invalid_request.
6.4 GET /drafts/{draftId}
200 {"draft":<draft>}. A draft of another key (even of the same multisig), or one no longer kept: 404 not_found.
6.5 DELETE /drafts/{draftId}
Withdraws a draft that nobody has started. Only while its status is submitted: every line becomes withdrawn, 200 {"draft":<draft>}. Already withdrawn: 200 again. Otherwise 409 not_withdrawable with details.status. Once a signer has started a draft, ask the signers to reject what is left instead.
7. Statuses
7.1 Draft status
| Status | Meaning |
|---|---|
submitted | Nobody has started it yet. Only now can your bot change it (section 6.2) or withdraw it (section 6.5) |
started | A signer started it on their phone (startedAt says when that first happened). A signer may open it and start it again, for example after their phone stopped part-way; it stays started |
rejected | A signer rejected it, in the web console or on their phone (before or after it was started), or its key was revoked before anyone started it. rejection says why |
withdrawn | Your bot withdrew it |
expired | Nobody started it within 7 days |
Ownbit reports only what it knows for certain: that a signer started the draft on their phone. It does not learn which payments followed, so a started draft may be paid in full, in part, or not at all. The payments are transactions of the multisig: check them as section 8 says, and do not submit a started draft's lines again unless the signers tell you they were not paid.
7.2 Line state
A line's state is always its draft's: in phase 1 Ownbit does not follow each line's transaction.
| State | Meaning |
|---|---|
pending | The draft is submitted |
started | The draft is started |
rejected, withdrawn, expired | The draft's status |
7.3 Lifetime
A draft nobody starts expires after 7 days. A started draft stays started until a signer rejects it. Rejected, withdrawn and expired drafts are kept 30 days after they end, and a started draft 30 days after its last change; then they are deleted (GET then answers 404; the same clientRequestId answers 410 for 365 days more).
8. Checking what gets paid
Ownbit carries your list from your bot to the signers' screens. To make sure nothing changed on the way:
- Show the
clientRequestIdand the fingerprint (the first 16 hex characters ofcontentHash) in your own approval channel, next to the approved payout list. A draft you change has a new fingerprint: show the latest one. The signers see both in the web console, recomputed by their browser from the lines they are about to start, and are asked to compare them with your record. That comparison is only possible if your approval record shows them. - Recompute
contentHash(section 6.2.3) from the lines of every draft you read, and compare it with the value you computed for the draft's latest revision. - Check the multisig's payments on chain yourself. In phase 1 Ownbit does not report each line's transaction. Once a draft is
started, compare its lines with the outgoing transactions of the multisig's address (whoami'smultisig.address): every payment's recipient, amount and token must be one of your lines', and each line should be paid at most once. - Watch
repeated: a line repeating one of another recent draft is marked for the signers; it should be marked in your system too. - On an Enterprise multisig, ask its members to turn on the whitelist and a daily limit: then even a wrong draft cannot pay an unknown address or more than the limit. Other multisigs have no whitelist, so the signers' check is the only one.
9. Errors
Every error has this body:
{"error":{"code":"<code>","message":"<English sentence>","details":{}},"requestId":"req_0123456789abcdef"}message is a fixed English sentence for people; program against code and details. Messages never echo your input.
| HTTP | code | When |
|---|---|---|
| 400 | invalid_request | Not JSON, a wrong type, an unknown field, a bad clientRequestId, no line or more than 500, a bad cursor or limit, a request body that did not arrive within 10 seconds |
| 401 | unauthorized | Any key problem (section 5) |
| 403 | forbidden | A valid key without the call's permission |
| 403 | https_required | The request did not come over HTTPS (revoke the key it carried) |
| 404 | not_found | An unknown path; a draft that is not this key's, or no longer kept |
| 405 | method_not_allowed | A method the path does not take (OPTIONS included) |
| 409 | idempotency_conflict | Section 6.2 |
| 409 | not_editable | Section 6.2 (details.status) |
| 409 | not_withdrawable | Section 6.5 (details.status) |
| 410 | gone | A clientRequestId whose draft was deleted |
| 413 | too_large | A body over 256 KiB |
| 415 | unsupported_media_type | A POST that is not JSON |
| 422 | invalid_lines | Section 6.2 (details.errors) |
| 429 | rate_limited, daily_limit | A limit (section 10), with Retry-After, details.scope, details.limit, details.retryAfter |
| 500 | internal | An error on Ownbit's side; retry later |
| 503 | unavailable | The API is switched off or cannot answer right now; with details.scope api_busy and Retry-After when it is busy |
A 429 with scope edge, or a 413, that comes from the protective layer in front of the API has the same shape with "requestId":null.
10. Rate limits and daily caps
10.1 The limits
| Limit | Value | details.scope | code |
|---|---|---|---|
| Requests from one address, burst | 20 a second (bursts up to 40), 20 open connections | edge | rate_limited |
| Calls per key | 10 a second | key_second | rate_limited |
| Calls per key | 300 a minute | key_minute | rate_limited |
POST /drafts per key | 60 an hour | key_submit_hour | rate_limited |
| Calls in progress at once, per key | 2 | key_concurrent | rate_limited |
| Calls in progress at once, per multisig (all its keys) | 4 | multisig_concurrent | rate_limited |
| Calls per address (valid keys) | 600 a minute; never refuses a key whose allowlist is not empty and holds the address | ip_minute | rate_limited |
| Calls per key | 10,000 a day | key_day | rate_limited |
| Calls per multisig (all its keys together) | 20,000 a day | multisig_day | rate_limited |
| Calls per address (valid keys) | 50,000 a day; never refuses a key whose allowlist is not empty and holds the address | ip_day | rate_limited |
| Calls per address (valid keys), hard cap | 200,000 a day, for every key | ip_day (details.limit 200000) | rate_limited |
| Failed calls per address | 20 a minute; past it, the address is held for 10 minutes | ip_failures | rate_limited |
| Failed calls per address | 200 a day; past it, the address is blocked for 24 hours | ip_blocked | rate_limited |
| Failed calls per network (a /24) | 1,000 a day; past it, the network is blocked for 24 hours | net_blocked | rate_limited |
| Payment lines per key | the key's own limit (1 to 10,000, default 1,000) in any 24 hours | key_lines_24h | daily_limit |
| Payment lines per multisig | 10,000 in any 24 hours | multisig_lines_24h | daily_limit |
| Whole API busy | (protects the service) | api_busy (HTTP 503) | unavailable |
- A day is the UTC calendar day: the call caps and the failure caps restart at 00:00 UTC (08:00 in Beijing). The two line limits are rolling: any 24 hours.
- What counts. Every call made with a valid key counts toward the key, multisig and address limits: reads too, and calls refused after the key was accepted (a
403,404,409,422, or a line limit's429), and a repeatedPOST /drafts. A call refused by a rate limit or a cap counts toward none of them, so waiting outRetry-Afteralways works. A call whose key is refused (401) counts only toward the failed calls of its address and network. - A held or blocked address or network (held for 10 minutes, or blocked for 24 hours) still serves every key that is valid and whose allowlist admits the address (an empty allowlist admits all). Only calls with bad keys, and keys whose allowlist does not admit the address, are refused there. A valid key is therefore never locked out by other people's failures from the same address.
- Limits per address are shared with everyone calling from it. A key whose allowlist is not empty and holds the address is not refused by the 600 a minute or the 50,000 a day, but the burst limit (20 a second) and the hard cap (200,000 a day) count everyone on the address, so on a shared NAT, CI runner or cloud egress others can still slow your calls; and a
429with scopeip_minuteorip_daytells you that others on your address are busy. Use a dedicated outgoing address.
10.2 The answers
A limit answers 429 (or 503 for api_busy) with:
{"error":{"code":"rate_limited","message":"Daily call limit of this key reached",
"details":{"scope":"key_day","limit":10000,"retryAfter":31260}},"requestId":"req_0123456789abcdef"}and the header Retry-After: 31260: the whole seconds to wait (at least 1). It runs to the end of the window, the hold or the block; to 00:00 UTC for the daily call caps; for the line limits, until enough of your oldest lines leave the 24 hours (at least 60 seconds); 1 for edge and the two _concurrent scopes; for api_busy, from 1 to about 90 seconds, with a random part so that refused clients do not all return together. When several limits refuse at once, the answer names the one with the longest wait. details.limit is that limit's value (not given for api_busy). The one 429 without Retry-After is a draft that can never fit its line limit: details.neverFits is true and details.retryAfter is null (section 6.2).
The messages: 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 The headers
Every answer to a call whose key was accepted (successes, the errors after it, and its 429s) carries:
| Header | Value |
|---|---|
X-RateLimit-Limit | The key's daily call cap (10000) |
X-RateLimit-Remaining | What is left today after this call: the smaller of what the key and its multisig have left |
X-RateLimit-Reset | The next 00:00 UTC, in Unix seconds (on 2026-11-17: 1794960000) |
A 401, a 429 of edge, ip_failures, ip_blocked or net_blocked, and a 503 carry none of them. GET /whoami gives the same counts in its body (callsToday, multisigCallsToday, callsResetAt).
10.4 How a well-behaved bot polls and backs off
- Poll
GET /drafts?since=<last nextCursor>every 30 seconds, with one poller per key. That is 2,880 calls a day. If several copies of your bot share a key, let one of them poll and share what it reads. Keep the lastnextCursoracross restarts; an empty page returns it unchanged. WhenhasMoreistrue, read the next page at once. - Never poll faster than the budget allows: at most once every 86,400 × 2 /
X-RateLimit-Limitseconds (17.3 seconds with the default 10,000), so that polling uses at most half of the day's calls. Polling every 10 seconds alone takes 8,640 calls and leaves about 1,300 for everything else; two copies of a bot doing that on one key are refused before the day ends. - Read a single draft only when you need its lines, that is when its
updatedAtmoved in the list, and at most once a minute per draft. Do not poll every draft separately. - Watch
X-RateLimit-Remaining. When it falls below a tenth ofX-RateLimit-Limit, poll less often. Remember that it is shared with the other keys of the multisig. - On
429: waitRetry-Afterseconds, plus a small random delay, then retry. Do not retry earlier: the answer will be the same. Onkey_dayormultisig_day, keep your cursor and resume afterX-RateLimit-Reset. - On
503: withRetry-After, wait it plus a random 0 to 30 seconds; without, back off exponentially from 30 seconds up to 10 minutes. - On a network error or
500duringPOST /drafts: resend the same request with the sameclientRequestId(section 6.2.2), after a backoff as above. - On
401: stop using the key and alert a person. Retrying a refused key never helps, and more than 200 failures in a day block your address for 24 hours for every bad key (your valid keys keep working from it, section 10.1). - Plan for midnight UTC: a key or multisig that used its day's calls is refused until 00:00 UTC. Resume then after a random 0 to 30 seconds, not on the second.
11. Security advice
- HTTPS only. Never send a key over plain HTTP; if it happened, revoke the key. Verify the server's certificate as usual.
- Keep the key on your server, in a secret store. Never in a browser, a mobile app, a repository, a log line, a URL, a ticket or a chat message. Ownbit never asks you for it.
- Give every key an IPv4 allowlist of your servers' fixed outgoing addresses. Then a leaked key cannot be used anywhere else, so it can neither submit drafts nor spend your multisig's daily calls. Prefer a dedicated outgoing address to a shared NAT or cloud egress: a held or blocked address still serves your valid keys, and a key whose allowlist holds the address is not refused by the per-address 600 a minute or 50,000 a day, but the burst limit and the 200,000 a day are shared with everyone on the address (section 10.1).
- One key per system, with a name that says which. At most 5 keys per multisig.
- Rotate before expiry and on any doubt: have a member create a new key, switch your bot to it, then revoke the old one. A new key must use new
clientRequestIds (section 6.2.2). - On a leak, revoke at once, in the web console or the Ownbit app. Revoking rejects the key's drafts that nobody has started. If a leaked key used up your multisig's calls for today, the replacement key shares that cap until 00:00 UTC: ask Ownbit support, who can raise that multisig's cap for the day.
- Turn off jobs that use revoked keys: their failures count against your address.
- Show the
clientRequestIdand fingerprint in your approval channel; checkcontentHashand the multisig's payments on chain (section 8). - Send
symbolon every line. - Treat text from the API as data, never as HTML or commands, in your logs and dashboards.
12. Not in phase 1
Webhooks; per-line transaction results (a line's transaction id, hash, signatures and errors); multisigs on other chains and other tokens; access over IPv6 and IPv6 allowlist entries; per-key call limits set by you; drafts signed with your own key. Ask Ownbit if you need one of them.
Last updated:
Download Ownbit
Install the app, then set up a cold wallet or MultiSig for the setup you need.