Reference

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:

CallPermissionWhat it does
GET /whoamidrafts:readDescribes the key and its multisig, with today's call counts
POST /draftsdrafts:submitSubmits a draft (1 to 500 lines), or changes one nobody has started: adds, replaces and removes lines by your lineId
GET /draftsdrafts:readLists this key's drafts, oldest change first, with a cursor
GET /drafts/{draftId}drafts:readReads one draft with its lines
DELETE /drafts/{draftId}drafts:submitWithdraws a draft that nobody has started

2. Phase 1 scope

  • Multisigs on TRON only. Lines pay in TRX or USDT (USDT-TRC20, contract TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t); both have 6 decimals.
  • IPv4 only. The API is reached over IPv4 only (api.bittool.com has 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_required and is never redirected. A key that has been sent over plain HTTP must be treated as leaked: revoke it and create another. HTTPS answers carry Strict-Transport-Security: max-age=31536000.
  • JSON in UTF-8. POST requests send Content-Type: application/json (a ; charset=utf-8 suffix 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-cache and X-Request-Id (req_ followed by 16 characters of [0-9a-z]). Error bodies repeat it as requestId. 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, as obk_…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 /8 to /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:submit and drafts: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_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefg

Never 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 401 does 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 without symbol pays in. On a TRON multisig that is TRX, not USDT: send symbol on every line (section 6.2).
  • requiredNum of ownerNum: 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"]}
FieldRule
clientRequestId1 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)
lines0 to 500 objects, each with only the keys below. The first call must send at least one
removeOptional. 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
lineIdRequired. 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
toA 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)
amountA 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")
symbolTRX 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)
memoOptional. 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:

StatusBodyWhen
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_editabledetails.draftId, details.statusThe draft is no longer submitted (a signer started it, or it was withdrawn, rejected or expired): nothing changed
409 idempotency_conflictThe clientRequestId was used by another key of the same multisig
410 goneThe draft of this clientRequestId has been deleted (retention, section 7.3)
422 invalid_linesdetails.errorsOne or more lines are invalid, or the draft would be empty; nothing changed
429 daily_limitdetails.scopeThe 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, else null. 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 by lineId). memo is "" 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: true when 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, else null. Reasons: whitelist, address, amount, duplicate, other (chosen by a signer in the web console, who may add a one-line note), phone (a signer rejected it on their phone; no note), and key_revoked. The API never says which member rejected.

6.2.2 Retries and changes

  • clientRequestId names 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 gets 409 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 answers 409 not_editable: ask the signers to reject lines that must not be paid, and send new ones under a new clientRequestId.
  • 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

StatusMeaning
submittedNobody has started it yet. Only now can your bot change it (section 6.2) or withdraw it (section 6.5)
startedA 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
rejectedA 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
withdrawnYour bot withdrew it
expiredNobody 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.

StateMeaning
pendingThe draft is submitted
startedThe draft is started
rejected, withdrawn, expiredThe 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:

  1. Show the clientRequestId and the fingerprint (the first 16 hex characters of contentHash) 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.
  2. 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.
  3. 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's multisig.address): every payment's recipient, amount and token must be one of your lines', and each line should be paid at most once.
  4. Watch repeated: a line repeating one of another recent draft is marked for the signers; it should be marked in your system too.
  5. 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.

HTTPcodeWhen
400invalid_requestNot 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
401unauthorizedAny key problem (section 5)
403forbiddenA valid key without the call's permission
403https_requiredThe request did not come over HTTPS (revoke the key it carried)
404not_foundAn unknown path; a draft that is not this key's, or no longer kept
405method_not_allowedA method the path does not take (OPTIONS included)
409idempotency_conflictSection 6.2
409not_editableSection 6.2 (details.status)
409not_withdrawableSection 6.5 (details.status)
410goneA clientRequestId whose draft was deleted
413too_largeA body over 256 KiB
415unsupported_media_typeA POST that is not JSON
422invalid_linesSection 6.2 (details.errors)
429rate_limited, daily_limitA limit (section 10), with Retry-After, details.scope, details.limit, details.retryAfter
500internalAn error on Ownbit's side; retry later
503unavailableThe 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

LimitValuedetails.scopecode
Requests from one address, burst20 a second (bursts up to 40), 20 open connectionsedgerate_limited
Calls per key10 a secondkey_secondrate_limited
Calls per key300 a minutekey_minuterate_limited
POST /drafts per key60 an hourkey_submit_hourrate_limited
Calls in progress at once, per key2key_concurrentrate_limited
Calls in progress at once, per multisig (all its keys)4multisig_concurrentrate_limited
Calls per address (valid keys)600 a minute; never refuses a key whose allowlist is not empty and holds the addressip_minuterate_limited
Calls per key10,000 a daykey_dayrate_limited
Calls per multisig (all its keys together)20,000 a daymultisig_dayrate_limited
Calls per address (valid keys)50,000 a day; never refuses a key whose allowlist is not empty and holds the addressip_dayrate_limited
Calls per address (valid keys), hard cap200,000 a day, for every keyip_day (details.limit 200000)rate_limited
Failed calls per address20 a minute; past it, the address is held for 10 minutesip_failuresrate_limited
Failed calls per address200 a day; past it, the address is blocked for 24 hoursip_blockedrate_limited
Failed calls per network (a /24)1,000 a day; past it, the network is blocked for 24 hoursnet_blockedrate_limited
Payment lines per keythe key's own limit (1 to 10,000, default 1,000) in any 24 hourskey_lines_24hdaily_limit
Payment lines per multisig10,000 in any 24 hoursmultisig_lines_24hdaily_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's 429), and a repeated POST /drafts. A call refused by a rate limit or a cap counts toward none of them, so waiting out Retry-After always 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 429 with scope ip_minute or ip_day tells 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:

HeaderValue
X-RateLimit-LimitThe key's daily call cap (10000)
X-RateLimit-RemainingWhat is left today after this call: the smaller of what the key and its multisig have left
X-RateLimit-ResetThe 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 last nextCursor across restarts; an empty page returns it unchanged. When hasMore is true, read the next page at once.
  • Never poll faster than the budget allows: at most once every 86,400 × 2 / X-RateLimit-Limit seconds (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 updatedAt moved 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 of X-RateLimit-Limit, poll less often. Remember that it is shared with the other keys of the multisig.
  • On 429: wait Retry-After seconds, plus a small random delay, then retry. Do not retry earlier: the answer will be the same. On key_day or multisig_day, keep your cursor and resume after X-RateLimit-Reset.
  • On 503: with Retry-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 500 during POST /drafts: resend the same request with the same clientRequestId (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 clientRequestId and fingerprint in your approval channel; check contentHash and the multisig's payments on chain (section 8).
  • Send symbol on 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

Download Ownbit

Install the app, then set up a cold wallet or MultiSig for the setup you need.