Ownbit MultiSig API v1(フェーズ 1)
自社のシステムから Ownbit マルチシグへ支払いリストを渡せます。Web コンソールで作成した API キーで下書きを送信し、署名者が各行を確認してスマートフォンで開始します。API が資金を動かすことはありません。
2026-11-18 版(下書きは lineId で変更します。下書きのステータスは 5 種類です)。本書は API のフェーズ 1 について説明します。本書に含まれるキー、ハッシュ、アドレス、IP アドレスはすべて架空の例です(IP アドレスはドキュメント用に予約された範囲のものです)。ただし、USDT-TRC20 のコントラクトアドレスは実在する公開のものです。
1. API でできること
あなたのシステム(以下「ボット」)は、1 つの Ownbit マルチシグに対する支払いのリスト、つまり下書きを Ownbit に渡し、後でその下書きがどうなったか(署名者による開始、拒否、取り下げ、期限切れ)を読み取ります。
API が資金を動かすことはありません。下書きが支払いになるのは、マルチシグの署名者が Ownbit Web コンソールで下書きを開き、自分のスマートフォンで開始し、マルチシグの十分な数のメンバーが各トランザクションに署名した(n 人中 m 人)ときだけです。署名者は開始する前にすべての行を確認でき、Ownbit が支払いに対して行うチェックはすべてそのまま実行され、署名者は下書きを拒否できます。キーでは、署名、支払いの開始、承認、拒否、マルチシグのポリシー・ホワイトリスト・メンバーの変更はできません。
キーでできること:
| 呼び出し | 権限 | 内容 |
|---|---|---|
GET /whoami | drafts:read | キーとそのマルチシグの情報を、本日の呼び出し回数とともに返します |
POST /drafts | drafts:submit | 下書き(1〜500 行)を提出するか、まだ誰も開始していない下書きを変更します:あなたの lineId で行を追加、置換、削除します |
GET /drafts | drafts:read | このキーの下書きを、変更の古い順にカーソル付きで一覧します |
GET /drafts/{draftId} | drafts:read | 1 件の下書きを行とともに読み取ります |
DELETE /drafts/{draftId} | drafts:submit | 誰も開始していない下書きを取り下げます |
2. フェーズ 1 の範囲
- TRON のマルチシグのみ。 各行は
TRXまたはUSDT(USDT-TRC20、コントラクトTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t)で支払います。どちらも小数点以下 6 桁です。 - IPv4 のみ。 API には IPv4 でのみ接続できます(フェーズ 1 では
api.bittool.comに IPv6 アドレスはありません)。キーの許可リストには IPv4 の範囲を入れます。 - Webhook はありません。 ボットはポーリングします(頻度は第 10 節で説明します)。
- 1 件の下書きは最大 500 行。 署名者は大きな下書きをスマートフォン上で 2 回のリクエストに分けて開始することがありますが、あなたの側には何の影響もありません。
3. ベース URL と通信
https://api.bittool.com/ownbit/api/v1- フェーズ 1 では IPv4 のみ:このホスト名には IPv6 アドレスがないため、IPv4 と IPv6 の両方を持つサーバーも IPv4 で呼び出し、IPv4 の許可リストと照合されます。
- 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_に続く[0-9a-z]の 16 文字)が付きます。エラーのボディでは同じ値がrequestIdとして繰り返されます。サポートに問い合わせる際はこの値を伝えてください。 - CORS なし。 ブラウザーのページから API を呼び出すことはできません。サーバーから呼び出してください。
- リクエストは厳格、応答は拡張可能。 API が知らないフィールドを含むリクエストは拒否されます(
400 invalid_request)。応答には今後フィールドが追加されることがあります。知らないフィールドは無視してください。
4. キー
- 入手方法。 マルチシグのメンバーが Ownbit Web コンソールのマルチシグの API タブでキーを作成し(署名者ロールを持つメンバーなら誰でも作成できます)、自分のスマートフォンの Ownbit アプリで承認します。キーは、スマートフォンが承認した直後にそのブラウザーのタブで 1 回だけ 表示されます。Ownbit はキーのハッシュしか保持しておらず、再表示できません。紛失した場合は取り消して、新しいキーを作成してください。
- 形式。
obk_に続く[0-9A-Za-z]の 43 文字です(全体で 47 文字、約 256 ビットのランダム性)。Ownbit がキーを表示する箇所では、obk_…defgのように末尾 4 文字だけを表示します。 - 作成時に選ぶオプション。 名前(30 文字以内、マルチシグのキーの中で一意)、有効期間(30 日、90 日(既定)、180 日、365 日、2 年、5 年。スマートフォンが承認した時点から数えます)、最大 20 件の範囲からなる IPv4 許可リスト(各範囲は
/8から/32。空のリストはすべてのアドレスを意味します)、そしてキーが任意の 24 時間に提出できる支払い行の上限(1〜10,000、既定 1,000)です。 - 権限。 フェーズ 1 のキーはすべて
drafts:submitとdrafts:readを持ちます。 - 1 つのマルチシグ。 キーの対象は 1 つのマルチシグアドレスで、そのアドレスの TRX と、存在する場合はそのアドレスの USDT です。Ownbit は 1 つのアドレスをトークンごとに複数のマルチシグとして表示することがありますが、それらは同じキーを共有します。キーが別のマルチシグのデータを見ることはありません。
- マルチシグごとにキーは最大 5 つ(承認待ちのものを含む)。
- 取り消し。 どのメンバーもいつでも、Web コンソールまたは 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_…"}。対象は、ヘッダーがない、または形式が不正、未知のキー、まだ承認されていないキー、取り消し済みまたは期限切れのキー、キーの許可リスト外の呼び出し元アドレス、メンバーでなくなった、または署名者ロールを失った作成者、有効でなくなったマルチシグです。マルチシグのメンバーは Web コンソールで各キーの最後の拒否とその理由を確認できるので、原因がわからない場合はメンバーに尋ねてください。 - 有効なキーでも、呼び出しに必要な権限がなければ
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 以降に行った呼び出しの回数(この呼び出しを含む)と、1 日の呼び出し上限。multisigCallsToday、multisigDailyCalls:同じものを、マルチシグのすべてのキーの合計で示した値。callsResetAt:1 日のカウントがリセットされる時刻(第 10 節)。multisig.symbols:支払いに使えるシンボル。multisig.defaultSymbol:symbolのない行で使われるシンボル。TRON のマルチシグでは、これはTRXであり、USDTではありません:すべての行でsymbolを送ってください(第 6.2 節)。requiredNum(ownerNum人中):各支払いに必要な署名の数。
6.2 POST /drafts
1 回の呼び出しで下書きを作成し、同じ 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"}]}行を 1 つ追加し、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 | [A-Za-z0-9._:-] の 1〜64 文字で、この支払いリストに対するあなた自身の ID。マルチシグの 1 つの下書きを永久に指し示します(第 6.2.2 節) |
lines | 0〜500 個のオブジェクト。各オブジェクトには以下のキーだけを含めます。最初の呼び出しでは少なくとも 1 つ送る必要があります |
remove | 任意。下書きから取り除く行の lineId。下書きにない lineId は無視されるため、再試行しても安全です。同じ lineId を lines と remove の両方に入れることはできません |
lineId | 必須。[A-Za-z0-9._:/-] の 1〜64 文字で、行に対するあなた自身の 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 がすべて同じ行が 2 つないこと(1 つ目が署名を待っている間に、チェーンが 2 つ目を重複として拒否するためです)。送ったすべての行は最初の呼び出しと同じようにチェックされます。何か 1 つでも拒否されると、何も変更されません。
応答:
| ステータス | ボディ | 条件 |
|---|---|---|
201 | {"draft":<draft>} | 新しい下書き。ステータスは submitted、リビジョンは 1、すべての行が pending |
200 | {"draft":<draft>} | 下書きが変更された(revision が 1 増えた)場合、または呼び出しで何も変わらなかった場合(再試行):現時点の下書きを返します |
409 not_editable | details.draftId, details.status | 下書きがもう submitted ではない場合(署名者が開始した、または取り下げ・拒否・期限切れになった):何も変更されません |
409 idempotency_conflict | その clientRequestId が同じマルチシグの別のキーで使用済みの場合 | |
410 gone | この clientRequestId の下書きが削除済みの場合(保存期間、第 7.3 節) | |
422 invalid_lines | details.errors | 1 つ以上の行が無効な場合、または下書きが空になる場合。何も変更されません |
429 daily_limit | details.scope | キーまたはマルチシグの 24 時間の行数上限を超える場合(第 10 節)。details.neverFits: true で Retry-After がない場合は、この呼び出しだけで上限を超える行数があるため、待っても解決しません。1 回の呼び出しで送る行数を減らしてください |
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。削除すると行が 1 つも残らなくなる場合です。代わりに下書きを取り下げてください。第 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_に続く[0-9a-z]の 24 文字。revision:新しい下書きでは 1。下書きを変更した呼び出しのたびに 1 ずつ増えます。startedAt:署名者がスマートフォンで最初に下書きを開始した日時。それ以外はnull。署名者がもう一度開始しても変わりません。lines[].lineId:その行に対するあなたの ID。lines[].index:行の現在の位置(0 から。前にある行が削除されると変わるので、行はlineIdで照合してください)。memoは、指定がない場合""です。lines[].state:常に下書きのステータスに従います(第 7.2 節)。フェーズ 1 では、行にトランザクション ID、ハッシュ、署名数、エラーは含まれません。支払いは第 8 節のとおりに確認してください。totals:シンボルごとの合計。counts:状態ごとの行数(行がある状態のみ)。repeated:このマルチシグの過去 7 日以内の別の下書きに、アドレス・金額・シンボルが同じ行がある場合にtrue。署名者にはこの印が表示され、署名者は下書きを開始する前にそれを確認する必要があります。この値を見たら、あなたのシステム側も確認してください。rejection:下書きが拒否された場合は{"reason","note","at"}、それ以外はnull。理由:whitelist、address、amount、duplicate、other(Web コンソールで署名者が選択し、1 行のnoteを添えることができます)、phone(署名者がスマートフォンで拒否した場合。noteはありません)、およびkey_revoked。どのメンバーが拒否したかを API が示すことはありません。
6.2.2 再試行と変更
clientRequestIdはマルチシグの 1 つの下書きを 永久に 指し示します。その下書きが保存されている間は使用済みのままで、下書きが削除された後も 365 日間は使用済みとして扱われます(410)。下書きを変更できるのは、それを作成したキーだけです。同じマルチシグの別のキーは409 idempotency_conflictを受け取ります(キーのローテーション後は新しい ID を使ってください)。ID は永久に一意になるようにしてください。たとえば日付と連番を組み合わせます。- どの呼び出しも安全に再試行できます。タイムアウトやネットワークエラーの後は、同じ リクエストをもう一度送ってください。送った行は同じ内容で自分自身を置き換え、削除した行はすでに消えているため、応答は現時点の下書きになり、2 つ目の下書きや同じ行の 2 つ目のコピーができることはありません。
- 変更できるのは下書きが
submittedの間だけです。署名者が開始した後の呼び出しには409 not_editableが返ります。支払ってはいけない行は署名者に拒否してもらい、新しい行は新しいclientRequestIdで送ってください。 - 署名者には、開いた時点の下書きが表示されます。署名者が開いている間に下書きが変更されると、コンソールは開始を拒否し、もう一度開くよう署名者に求めます。
- 同じ ID の呼び出しが同時に 2 つ届いた場合は、1 つずつ順に適用されます。
6.2.3 コンテンツハッシュ
contentHash は、下書きの行を現在の順序で並べたコンパクトな JSON 配列の UTF-8 バイト列に対する SHA-256 を、小文字の 16 進数で表したものです。各行は {"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 文字の 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 | 署名者が Web コンソールまたはスマートフォンで拒否した(開始の前でも後でも)か、誰かが開始する前にキーが取り消されました。理由は 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 はさらに 365 日間 410 を返します)。
8. 支払い内容の確認
Ownbit は、あなたのリストをボットから署名者の画面まで運びます。途中で何も変わっていないことを確かめるには:
clientRequestIdとフィンガープリントを表示してください(contentHashの先頭 16 文字の 16 進数)。表示する場所は、あなた自身の承認チャネルの、承認済み支払いリストの横です。変更した下書きには新しいフィンガープリントが付くので、最新のものを表示してください。署名者は Web コンソールでこの 2 つを確認できます。これらは、署名者のブラウザーがこれから開始する行から再計算したもので、署名者はそれをあなたの記録と照合するよう求められます。この照合は、あなたの承認記録にこれらが表示されている場合にのみ可能です。contentHashを再計算してください(第 6.2.3 節)。読み取ったすべての下書きの行から計算し、その下書きの最新リビジョンについて計算した値と比較します。- マルチシグの支払いをチェーン上で自分で確認してください。 フェーズ 1 の Ownbit は、各行のトランザクションを報告しません。下書きが
startedになったら、その行をマルチシグのアドレス(whoamiのmultisig.address)からの送金トランザクションと照合してください:すべての支払いの受取人、金額、トークンがあなたの行のいずれかと一致し、各行への支払いは 1 回以下でなければなりません。 repeatedに注意してください:最近の別の下書きの行と重複する行には、署名者向けの印が付きます。あなたのシステムでも印を付けるべきです。- エンタープライズ・マルチシグでは、メンバーに ホワイトリスト と 1 日の上限 をオンにしてもらってください。そうすれば、誤った下書きであっても、未知のアドレスに支払ったり上限を超えて支払ったりすることはできません。その他のマルチシグにはホワイトリストがないため、署名者による確認が唯一のチェックになります。
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 が付きます |
429 のうちスコープが edge のものや 413 で、API の前段にある保護レイヤーから返されるものも同じ形式ですが、"requestId":null になります。
10. レート制限と 1 日の上限
10.1 制限
| 制限 | 値 | details.scope | code |
|---|---|---|---|
| 1 つのアドレスからのリクエスト(バースト) | 毎秒 20 件(バーストは 40 件まで)、同時接続 20 | edge | rate_limited |
| キーごとの呼び出し | 毎秒 10 回 | key_second | rate_limited |
| キーごとの呼び出し | 毎分 300 回 | key_minute | rate_limited |
キーごとの POST /drafts | 1 時間に 60 回 | key_submit_hour | rate_limited |
| キーごとの同時実行中の呼び出し | 2 | key_concurrent | rate_limited |
| マルチシグごとの同時実行中の呼び出し(すべてのキーの合計) | 4 | multisig_concurrent | rate_limited |
| アドレスごとの呼び出し(有効なキー) | 毎分 600 回。許可リストが空でなく、そのアドレスを含むキーは拒否されません | ip_minute | rate_limited |
| キーごとの呼び出し | 1 日 10,000 回 | key_day | rate_limited |
| マルチシグごとの呼び出し(すべてのキーの合計) | 1 日 20,000 回 | multisig_day | rate_limited |
| アドレスごとの呼び出し(有効なキー) | 1 日 50,000 回。許可リストが空でなく、そのアドレスを含むキーは拒否されません | ip_day | rate_limited |
| アドレスごとの呼び出し(有効なキー)、ハード上限 | 1 日 200,000 回。すべてのキーが対象です | ip_day(details.limit 200000) | rate_limited |
| アドレスごとの失敗した呼び出し | 毎分 20 回。超えるとアドレスが 10 分間保留されます | ip_failures | rate_limited |
| アドレスごとの失敗した呼び出し | 1 日 200 回。超えるとアドレスが 24 時間ブロックされます | ip_blocked | rate_limited |
| ネットワーク(/24)ごとの失敗した呼び出し | 1 日 1,000 回。超えるとネットワークが 24 時間ブロックされます | net_blocked | rate_limited |
| キーごとの支払い行 | 任意の 24 時間でキー自身の上限(1〜10,000、既定 1,000) | key_lines_24h | daily_limit |
| マルチシグごとの支払い行 | 任意の 24 時間で 10,000 | multisig_lines_24h | daily_limit |
| API 全体の混雑 | (サービスの保護) | api_busy(HTTP 503) | unavailable |
- 1 日は UTC の暦日です:呼び出し上限と失敗回数の上限は 00:00 UTC(北京時間 08:00)にリセットされます。2 つの行数上限はローリング方式で、任意の 24 時間が対象です。
- カウントされるもの。 有効なキーで行われたすべての呼び出しは、キー、マルチシグ、アドレスの制限にカウントされます。読み取りも、キーが受け付けられた後に拒否された呼び出し(
403、404、409、422、または行数上限による429)も、繰り返されたPOST /draftsも含まれます。レート制限や上限によって拒否された呼び出しはどの制限にもカウントされないため、Retry-Afterの時間だけ待てば必ず解消します。キーが拒否された呼び出し(401)は、そのアドレスとネットワークの失敗した呼び出しにのみカウントされます。 - 保留またはブロックされたアドレスやネットワーク(10 分間の保留、または 24 時間のブロック)でも、有効で、かつ許可リストがそのアドレスを認めているキー(空の許可リストはすべてのアドレスを認めます)は引き続き使えます。そこで拒否されるのは、不正なキーによる呼び出しと、許可リストがそのアドレスを認めていないキーだけです。したがって、同じアドレスからの他人の失敗によって有効なキーが締め出されることはありません。
- アドレスごとの制限は、そのアドレスから呼び出すすべての人で共有されます。 許可リストが空でなく、そのアドレスを含むキーは、毎分 600 回や 1 日 50,000 回の制限では拒否されません。しかし、バースト制限(毎秒 20 件)とハード上限(1 日 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)です。その値はウィンドウ、保留、ブロックの終わりまでの時間で、1 日の呼び出し上限では 00:00 UTC まで、行数上限では最も古い行が十分な数だけ 24 時間の範囲から外れるまで(最小 60 秒)、edge と 2 つの _concurrent スコープでは 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 | キーの 1 日の呼び出し上限(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 行儀のよいボットのポーリングとバックオフ
GET /drafts?since=<last nextCursor>を 30 秒ごとに、キーごとに 1 つのポーラーでポーリングしてください。 これは 1 日 2,880 回の呼び出しになります。ボットの複数のインスタンスが 1 つのキーを共有する場合は、1 つのインスタンスだけにポーリングさせ、読み取った内容を共有してください。最後のnextCursorは再起動後も保持してください。空のページはそれを変更せずに返します。hasMoreがtrueの場合は、すぐに次のページを読んでください。- 予算が許す以上の頻度でポーリングしないでください: 最短でも 86,400 × 2 /
X-RateLimit-Limit秒に 1 回(既定の 10,000 なら 17.3 秒)とし、ポーリングに使うのが 1 日の呼び出しの半分以下になるようにします。10 秒ごとのポーリングだけで 8,640 回を使い、その他に残るのは約 1,300 回です。1 つのキーで 2 つのボットがそれを行うと、1 日が終わる前に拒否されます。 - 個々の下書きを読むのは、その行が必要なときだけにしてください。つまり一覧でその
updatedAtが変わったときで、下書きごとに 1 分に 1 回までとします。すべての下書きを個別にポーリングしないでください。 X-RateLimit-Remainingを監視してください。X-RateLimit-Limitの 10 分の 1 を下回ったら、ポーリングの頻度を下げてください。この値はマルチシグの他のキーと共有されていることに注意してください。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の場合: そのキーの使用をやめ、人に知らせてください。拒否されたキーで再試行しても解決せず、1 日に 200 回を超える失敗があると、すべての不正なキーについてそのアドレスが 24 時間ブロックされます(有効なキーはそのアドレスからも引き続き使えます。第 10.1 節)。- UTC の午前 0 時に備えてください: 1 日分の呼び出しを使い切ったキーやマルチシグは、00:00 UTC まで拒否されます。その時刻ちょうどではなく、ランダムに 0〜30 秒後に再開してください。
11. セキュリティに関する推奨事項
- HTTPS のみ。 キーを平文の HTTP で送らないでください。送ってしまった場合は、そのキーを取り消してください。サーバーの証明書は通常どおり検証してください。
- キーはサーバーに保管してください。シークレットストアに入れ、ブラウザー、モバイルアプリ、リポジトリ、ログ、URL、チケット、チャットメッセージには決して入れないでください。Ownbit がキーを尋ねることはありません。
- すべてのキーに IPv4 許可リストを設定してください。サーバーの固定の送信元アドレスを入れます。そうすれば漏洩したキーは他の場所で使えず、下書きの提出もマルチシグの 1 日の呼び出し数の消費もできません。共有 NAT やクラウドの送信元アドレスよりも、専用の送信元アドレスを使ってください。保留またはブロックされたアドレスでも有効なキーは使え、許可リストにそのアドレスを含むキーはアドレスごとの毎分 600 回や 1 日 50,000 回の制限では拒否されませんが、バースト制限と 1 日 200,000 回の上限はそのアドレスのすべての利用者で共有されます(第 10.1 節)。
- システムごとに 1 つのキーを使い、どのシステムのものかわかる名前を付けてください。マルチシグごとにキーは最大 5 つです。
- 期限切れの前や、少しでも疑いがあるときはローテーションしてください: メンバーに新しいキーを作成してもらい、ボットをそのキーに切り替えてから、古いキーを取り消します。新しいキーでは新しい
clientRequestIdを使う必要があります(第 6.2.2 節)。 - 漏洩したらすぐに取り消してください。Web コンソールまたは Ownbit アプリで取り消せます。取り消すと、そのキーの下書きのうち誰も開始していないものは拒否されます。漏洩したキーがマルチシグの本日の呼び出し数を使い切った場合、代わりのキーも 00:00 UTC までその上限を共有します。Ownbit サポートに依頼すれば、そのマルチシグのその日の上限を引き上げてもらえます。
- 取り消したキーを使うジョブは停止してください:その失敗はあなたのアドレスにカウントされます。
- 承認チャネルに
clientRequestIdとフィンガープリントを表示し、contentHashとマルチシグのチェーン上の支払いを確認してください(第 8 節)。 - すべての行で
symbolを送ってください。 - API からのテキストはデータとして扱ってください。ログやダッシュボードで HTML やコマンドとして扱ってはいけません。
12. フェーズ 1 で提供しないもの
Webhook、行ごとのトランザクション結果(行のトランザクション ID、ハッシュ、署名、エラー)、他のチェーンや他のトークンのマルチシグ、IPv6 でのアクセスと IPv6 の許可リスト項目、あなたが設定するキーごとの呼び出し上限、あなた自身の鍵で署名した下書き。いずれかが必要な場合は Ownbit にお問い合わせください。
最終更新:
Ownbit をダウンロード
アプリをインストールし、必要に応じてコールドウォレットやマルチシグを設定しましょう。