Ownbit 多簽 API v1(第一階段)
讓您自己的系統把付款清單交給 Ownbit 多簽。在網頁控制台中建立的 API 金鑰可以提交草稿;簽名人逐行審核後在手機上發起。API 從不動用資金。
2026-11-18 版(草稿依 lineId 修改;草稿有五種狀態)。本文件說明 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. 第一階段範圍
- 僅限 TRON 上的多簽。 付款行以
TRX或USDT(USDT-TRC20,合約TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t)付款;兩者都是 6 位小數。 - 僅限 IPv4。 API 只能透過 IPv4 存取(第一階段
api.bittool.com沒有 IPv6 位址),金鑰的 IP 白名單也只能填 IPv4 網段。 - 沒有 webhook。 由您的機器人輪詢(輪詢頻率見第 10 節)。
- 每份草稿最多 500 筆付款行。 簽名人可能會在手機上把一份大草稿分成兩個請求發起;這對您沒有任何影響。
3. 基礎網址與傳輸
https://api.bittool.com/ownbit/api/v1- 第一階段僅限 IPv4:此網域名稱沒有 IPv6 位址,所以同時具備 IPv4 和 IPv6 的伺服器會透過 IPv4 呼叫,並以其 IPv4 位址比對 IP 白名單。
- 僅限 HTTPS。 不是經由 HTTPS 送達的請求會以
403 https_required拒絕,且絕不會被重新導向。曾經透過明文 HTTP 傳送的金鑰必須視為已外洩:請撤銷它並建立新的金鑰。HTTPS 回應會帶有Strict-Transport-Security: max-age=31536000。 - UTF-8 編碼的 JSON。
POST請求須傳送Content-Type: application/json(加上; charset=utf-8後綴也可以)。請求本文最多 256 KiB。 - 時間一律是 UTC 的 ISO 8601 字串,含毫秒,例如
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 App 授權。金鑰在手機授權後,只會在該瀏覽器分頁中顯示一次。Ownbit 只保存金鑰的雜湊值,無法再次顯示:如果遺失,請撤銷它並建立新的金鑰。
- 格式。
obk_後接 43 個[0-9A-Za-z]字元(共 47 個字元,約 256 位元的隨機性)。Ownbit 在任何地方顯示金鑰時,都只顯示最後 4 個字元,形如obk_…defg。 - 建立時選擇的選項。 名稱(最多 30 個字元,在該多簽的金鑰中不可重複);有效期 30、90(預設)、180 或 365 天、2 年或 5 年,從手機授權時開始計算;最多 20 個網段的 IPv4 白名單,每個網段從
/8到/32(空白清單表示任何位址);以及此金鑰在任意 24 小時內最多可提交的付款筆數(1 到 10,000,預設 1,000)。 - 權限。 第一階段的每個金鑰都具有
drafts:submit和drafts:read。 - 一個多簽。 一個金鑰對應一個多簽地址:該地址上的 TRX,以及(若有)該地址上的 USDT。Ownbit 可能把同一個地址列為多個多簽,每種代幣一個;它們共用相同的金鑰。金鑰絕不會看到其他多簽的資料。
- 每個多簽最多 5 個金鑰(含等待授權中的金鑰)。
- 撤銷。 任何成員都可以隨時在網頁控制台或 Ownbit App 中撤銷金鑰。已撤銷或已過期的金鑰會立即失效。撤銷金鑰也會拒絕它提交且還沒有人發起的草稿(原因為
key_revoked);已發起的草稿會繼續進行。 - 通知。 金鑰被授權或撤銷時,每位成員的手機都會收到通知。如果您的團隊看到意料之外的通知,請撤銷該金鑰。
5. 驗證
每次呼叫都要傳送金鑰,而且只能放在這個標頭中:
Authorization: Bearer obk_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefg絕不要把金鑰放進網址、查詢字串或請求本文。
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_…"}。這涵蓋了標頭缺漏或格式錯誤、未知的金鑰、尚未授權的金鑰、已撤銷或已過期的金鑰、呼叫端位址不在金鑰的 IP 白名單內、建立者已不是成員或已不具簽名人角色,以及多簽已不再生效。多簽的成員可以在網頁控制台中看到每個金鑰最近一次被拒的時間和原因,所以您無法判斷原因時,請詢問他們。 - 有效的金鑰若不具備該呼叫所需的權限,會得到
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._:-] 字元,是您為這份付款清單自訂的 ID。它永久指定該多簽的一份草稿(第 6.2.2 節) |
lines | 0 到 500 個物件,每個物件只能含有下列鍵。第一次呼叫至少要傳送一個 |
remove | 選填。要從草稿中移除的付款行的 lineId。草稿中沒有的 lineId 會被忽略,所以重試是安全的。同一個 lineId 不能同時出現在 lines 和 remove 中 |
lineId | 必填。1 到 64 個 [A-Za-z0-9._:/-] 字元,是您為該付款行自訂的 ID,在草稿內不可重複(換一個 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:一筆沒有 symbol 的 USDT 付款會變成相同數字的 TRX 付款。多簽必須持有該幣種(whoami 的 symbols) |
memo | 選填。最多 80 個字元;不能含有 , ' " \;不能含有控制字元、換行字元或隱藏字元;開頭和結尾不能有空格;不能是保留備註(以 admin: 開頭、含有 -no-broadcast,或以 ***br*** 結尾,不分大小寫)。缺少與 "" 視為相同 |
Ownbit 先移除 remove 中的付款行,再逐一取代或新增 lines 中的每筆付款行,然後檢查整份草稿:最多 500 筆、至少 1 筆,且任兩筆付款行的 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:您為該付款行自訂的 ID。lines[].index:它目前的位置,從 0 開始(前面的付款行被移除時它會改變:請以lineId對應付款行)。memo未提供時為""。lines[].state:一律跟隨草稿的狀態(第 7.2 節)。第一階段的付款行不帶交易 ID、雜湊值、簽名數或錯誤:請依第 8 節的說明核對付款。totals:每個幣種的合計;counts:每種狀態的付款行數(只列出有付款行的狀態)。repeated:若此多簽最近 7 天內的另一份草稿有一筆地址、金額和幣種都相同的付款行,則為true。簽名人會看到此標記,且必須先確認才能發起草稿;看到它時,請檢查您自己的系統。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(更換金鑰之後,請使用新的 ID)。請讓您的 ID 永遠不重複,例如使用日期加上序號。- 每次呼叫都可以安全地重試。逾時或發生網路錯誤後,請再次傳送相同的請求:您傳送的付款行會以相同內容取代自己,已移除的付款行早已不在,所以回應就是草稿目前的樣子,絕不會產生第二份草稿或重複的付款行。
- 只有在草稿為
submitted時才能修改。一旦有簽名人發起它,呼叫會回應409 not_editable:請簽名人拒絕不應付款的付款行,並以新的clientRequestId傳送新的付款行。 - 簽名人看到的是開啟時的草稿。如果草稿在簽名人開啟期間被修改,其控制台會拒絕發起,並請簽名人重新開啟。
- 以相同 ID 同時送出的兩次呼叫會依序套用。
6.2.3 內容雜湊
contentHash 是草稿付款行依目前順序組成的緊湊 JSON 陣列,其 UTF-8 位元組的 SHA-256 值,以小寫十六進位表示;每筆付款行依序寫成 {"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 程式庫的鍵順序或跳脫處理:這些欄位都不可能含有需要跳脫的字元)。簽名人看到的指紋是 contentHash 的前 16 個十六進位字元(此例為 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 只回報它確定知道的事:簽名人已在手機上發起草稿。它不知道之後產生了哪些付款,所以 started 的草稿可能已全額付款、部分付款,或完全沒有付款。這些付款是多簽的交易:請依第 8 節的說明核對,除非簽名人告訴您這些付款行沒有付款,否則不要再次提交已發起草稿的付款行。
7.2 付款行 state
付款行的 state 一律與其草稿相同:第一階段 Ownbit 不追蹤每筆付款行的交易。
| 狀態 | 意義 |
|---|---|
pending | 草稿為 submitted |
started | 草稿為 started |
rejected、withdrawn、expired | 與草稿的狀態相同 |
7.3 保留期限
沒有人發起的草稿會在 7 天後過期。已發起的草稿會維持 started,直到簽名人拒絕它。已拒絕、已撤回和已過期的草稿在結束後保留 30 天,已發起的草稿則在最後一次變更後保留 30 天;之後刪除(此後 GET 會回應 404;相同的 clientRequestId 在之後 365 天內會回應 410)。
8. 核對實際付款內容
Ownbit 把您的清單從您的機器人傳到簽名人的螢幕上。為了確保途中沒有任何改變:
- 在您自己的核准管道中顯示
clientRequestId和指紋(contentHash的前 16 個十六進位字元),放在已核准的付款清單旁邊。修改過的草稿會有新的指紋:請顯示最新的指紋。簽名人會在網頁控制台看到這兩者,它們由簽名人的瀏覽器根據即將發起的付款行重新計算,系統也會請簽名人將其與您的紀錄比對。只有當您的核准紀錄顯示了它們,這樣的比對才有可能。 - 根據您讀取的每份草稿的付款行重新計算
contentHash(第 6.2.3 節),並與您為該草稿最新版次計算出的值比對。 - 自行在鏈上核對多簽的付款。 第一階段 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 筆、無效的游標或 limit、請求本文未在 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 KiB |
| 415 | unsupported_media_type | 不是 JSON 的 POST |
| 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 |
由 API 前端防護層發出的 429(scope 為 edge)或 413,格式相同,但為 "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 白名單不為空且包含該位址,絕不拒絕該金鑰 | ip_minute | rate_limited |
| 每個金鑰的呼叫 | 每天 10,000 次 | key_day | rate_limited |
| 每個多簽的呼叫(所有金鑰合計) | 每天 20,000 次 | multisig_day | rate_limited |
| 每個位址的呼叫(有效金鑰) | 每天 50,000 次;若金鑰的 IP 白名單不為空且包含該位址,絕不拒絕該金鑰 | 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 |
| 每個多簽的付款筆數 | 任意 24 小時內 10,000 筆 | 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 小時)仍會為每個有效且其 IP 白名單允許該位址的金鑰提供服務(空白的 IP 白名單允許所有位址)。在那裡只有使用錯誤金鑰的呼叫,以及其 IP 白名單不允許該位址的金鑰會被拒絕。因此有效的金鑰絕不會因為同一位址上其他人的失敗而被鎖住。
- 每個位址的限制由所有從該位址呼叫的人共用。 IP 白名單不為空且包含該位址的金鑰,不會被每分鐘 600 次或每天 50,000 次的限制拒絕,但突發限制(每秒 20 次)和硬性上限(每天 200,000 次)會計入該位址上的所有人,所以在共用的 NAT、CI 執行器或雲端出口上,其他人仍可能拖慢您的呼叫;而
429若 scope 為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 秒);對 edge 和兩個 _concurrent scope 為 1;對 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 良好的機器人如何輪詢與退避
- 每 30 秒輪詢一次
GET /drafts?since=<last nextCursor>,每個金鑰只用一個輪詢程式。 這樣每天是 2,880 次呼叫。如果您的機器人有多個執行個體共用一個金鑰,請讓其中一個負責輪詢,並分享它讀到的內容。重新啟動時請保留最新的nextCursor;空白的頁面會原樣回傳它。當hasMore為true時,請立即讀取下一頁。 - 輪詢頻率絕不要超過額度允許的範圍: 最多每 86,400 × 2 /
X-RateLimit-Limit秒一次(預設 10,000 時為 17.3 秒),讓輪詢最多只用掉當天一半的呼叫次數。光是每 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 傳送金鑰;如果發生了,請撤銷該金鑰。請照常驗證伺服器的憑證。
- 把金鑰保存在您的伺服器上,放在機密儲存區中。絕不要放在瀏覽器、行動 App、程式碼儲存庫、日誌、網址、工單或聊天訊息中。Ownbit 絕不會向您索取金鑰。
- 為每個金鑰設定 IPv4 白名單,填入您伺服器固定的對外位址。這樣外洩的金鑰就無法在其他地方使用,既不能提交草稿,也不能消耗您多簽的每日呼叫次數。比起共用的 NAT 或雲端出口,請優先使用專用的對外位址:被暫停或封鎖的位址仍會為您的有效金鑰提供服務,而 IP 白名單包含該位址的金鑰也不會被每個位址每分鐘 600 次或每天 50,000 次的限制拒絕,但突發限制和每天 200,000 次的上限由該位址上的所有人共用(第 10.1 節)。
- 每個系統使用一個金鑰,並取一個能看出是哪個系統的名稱。每個多簽最多 5 個金鑰。
- 在到期前以及有任何疑慮時更換金鑰: 請成員建立新的金鑰,把您的機器人切換到新金鑰,再撤銷舊的金鑰。新金鑰必須使用新的
clientRequestId(第 6.2.2 節)。 - 一旦外洩,請立即撤銷,在網頁控制台或 Ownbit App 中都可以。撤銷會拒絕該金鑰提交且還沒有人發起的草稿。如果外洩的金鑰用完了您多簽今天的呼叫次數,替代的金鑰在 00:00 UTC 之前會共用該上限:請聯絡 Ownbit 客服,他們可以提高該多簽當天的上限。
- 停用仍在使用已撤銷金鑰的工作:它們的失敗會計入您的位址。
- 在您的核准管道中顯示
clientRequestId和指紋;在鏈上核對contentHash和多簽的付款(第 8 節)。 - 每一筆付款行都要傳送
symbol。 - 把來自 API 的文字視為資料,在您的日誌和儀表板中絕不要把它當成 HTML 或指令。
12. 第一階段不包含的功能
Webhook;逐筆付款行的交易結果(付款行的交易 ID、雜湊值、簽名數和錯誤);其他鏈上的多簽和其他代幣;透過 IPv6 存取以及 IPv6 白名單項目;由您自訂的每個金鑰呼叫上限;以您自己的金鑰簽名的草稿。如果需要其中任何一項,請洽詢 Ownbit。