リファレンス

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 /whoamidrafts:readキーとそのマルチシグの情報を、本日の呼び出し回数とともに返します
POST /draftsdrafts:submit下書き(1〜500 行)を提出するか、まだ誰も開始していない下書きを変更します:あなたの lineId で行を追加、置換、削除します
GET /draftsdrafts:readこのキーの下書きを、変更の古い順にカーソル付きで一覧します
GET /drafts/{draftId}drafts:read1 件の下書きを行とともに読み取ります
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 節)
lines0〜500 個のオブジェクト。各オブジェクトには以下のキーだけを含めます。最初の呼び出しでは少なくとも 1 つ送る必要があります
remove任意。下書きから取り除く行の lineId。下書きにない lineId は無視されるため、再試行しても安全です。同じ lineId を lines と remove の両方に入れることはできません
lineId必須。[A-Za-z0-9._:/-] の 1〜64 文字で、行に対するあなた自身の ID。下書き内で一意です(別の clientRequestId では一から別に扱われます)。下書きにすでにある lineId を送ると、その行をその位置のまま 置き換えます。新しいものは末尾に追加されます。あなたに返されますが、チェーンに載ることも、署名者に表示されることもありません
toTRON アドレス(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" になります)
symbolTRX または 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_editabledetails.draftId, details.status下書きがもう submitted ではない場合(署名者が開始した、または取り下げ・拒否・期限切れになった):何も変更されません
409 idempotency_conflictその clientRequestId が同じマルチシグの別のキーで使用済みの場合
410 goneこの clientRequestId の下書きが削除済みの場合(保存期間、第 7.3 節)
422 invalid_linesdetails.errors1 つ以上の行が無効な場合、または下書きが空になる場合。何も変更されません
429 daily_limitdetails.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ボットが取り下げました
expired7 日以内に誰も開始しませんでした

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 は、あなたのリストをボットから署名者の画面まで運びます。途中で何も変わっていないことを確かめるには:

  1. clientRequestId とフィンガープリントを表示してください(contentHash の先頭 16 文字の 16 進数)。表示する場所は、あなた自身の承認チャネルの、承認済み支払いリストの横です。変更した下書きには新しいフィンガープリントが付くので、最新のものを表示してください。署名者は Web コンソールでこの 2 つを確認できます。これらは、署名者のブラウザーがこれから開始する行から再計算したもので、署名者はそれをあなたの記録と照合するよう求められます。この照合は、あなたの承認記録にこれらが表示されている場合にのみ可能です。
  2. contentHash を再計算してください(第 6.2.3 節)。読み取ったすべての下書きの行から計算し、その下書きの最新リビジョンについて計算した値と比較します。
  3. マルチシグの支払いをチェーン上で自分で確認してください。 フェーズ 1 の Ownbit は、各行のトランザクションを報告しません。下書きが started になったら、その行をマルチシグのアドレス(whoami の multisig.address)からの送金トランザクションと照合してください:すべての支払いの受取人、金額、トークンがあなたの行のいずれかと一致し、各行への支払いは 1 回以下でなければなりません。
  4. repeated に注意してください:最近の別の下書きの行と重複する行には、署名者向けの印が付きます。あなたのシステムでも印を付けるべきです。
  5. エンタープライズ・マルチシグでは、メンバーに ホワイトリスト と 1 日の上限 をオンにしてもらってください。そうすれば、誤った下書きであっても、未知のアドレスに支払ったり上限を超えて支払ったりすることはできません。その他のマルチシグにはホワイトリストがないため、署名者による確認が唯一のチェックになります。

9. エラー

すべてのエラーのボディは次の形式です:

{"error":{"code":"<code>","message":"<English sentence>","details":{}},"requestId":"req_0123456789abcdef"}

message は人が読むための固定の英文です。プログラムでは code と details を使ってください。メッセージに入力内容が含まれることはありません。

HTTPcode条件
400invalid_requestJSON でない、型が違う、未知のフィールドがある、clientRequestId が不正、行がないか 500 行を超える、カーソルまたは limit が不正、リクエストボディが 10 秒以内に届かなかった
401unauthorizedキーに関するあらゆる問題(第 5 節)
403forbidden有効なキーだが、その呼び出しの権限がない
403https_requiredリクエストが HTTPS で届かなかった(送られたキーを取り消してください)
404not_found未知のパス。このキーのものではない下書き、またはすでに保存されていない下書き
405method_not_allowedそのパスが受け付けないメソッド(OPTIONS を含む)
409idempotency_conflict第 6.2 節
409not_editable第 6.2 節(details.status)
409not_withdrawable第 6.5 節(details.status)
410gone下書きが削除された clientRequestId
413too_large256 KiB を超えるボディ
415unsupported_media_typeJSON でない POST
422invalid_lines第 6.2 節(details.errors)
429rate_limited, daily_limit制限(第 10 節)。Retry-After、details.scope、details.limit、details.retryAfter が付きます
500internalOwnbit 側のエラー。後で再試行してください
503unavailableAPI がオフになっているか、現在応答できない。混雑時は details.scope が api_busy で、Retry-After が付きます

429 のうちスコープが edge のものや 413 で、API の前段にある保護レイヤーから返されるものも同じ形式ですが、"requestId":null になります。

10. レート制限と 1 日の上限

10.1 制限

制限値details.scopecode
1 つのアドレスからのリクエスト(バースト)毎秒 20 件(バーストは 40 件まで)、同時接続 20edgerate_limited
キーごとの呼び出し毎秒 10 回key_secondrate_limited
キーごとの呼び出し毎分 300 回key_minuterate_limited
キーごとの POST /drafts1 時間に 60 回key_submit_hourrate_limited
キーごとの同時実行中の呼び出し2key_concurrentrate_limited
マルチシグごとの同時実行中の呼び出し(すべてのキーの合計)4multisig_concurrentrate_limited
アドレスごとの呼び出し(有効なキー)毎分 600 回。許可リストが空でなく、そのアドレスを含むキーは拒否されませんip_minuterate_limited
キーごとの呼び出し1 日 10,000 回key_dayrate_limited
マルチシグごとの呼び出し(すべてのキーの合計)1 日 20,000 回multisig_dayrate_limited
アドレスごとの呼び出し(有効なキー)1 日 50,000 回。許可リストが空でなく、そのアドレスを含むキーは拒否されませんip_dayrate_limited
アドレスごとの呼び出し(有効なキー)、ハード上限1 日 200,000 回。すべてのキーが対象ですip_day(details.limit 200000)rate_limited
アドレスごとの失敗した呼び出し毎分 20 回。超えるとアドレスが 10 分間保留されますip_failuresrate_limited
アドレスごとの失敗した呼び出し1 日 200 回。超えるとアドレスが 24 時間ブロックされますip_blockedrate_limited
ネットワーク(/24)ごとの失敗した呼び出し1 日 1,000 回。超えるとネットワークが 24 時間ブロックされますnet_blockedrate_limited
キーごとの支払い行任意の 24 時間でキー自身の上限(1〜10,000、既定 1,000)key_lines_24hdaily_limit
マルチシグごとの支払い行任意の 24 時間で 10,000multisig_lines_24hdaily_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 をダウンロード

アプリをインストールし、必要に応じてコールドウォレットやマルチシグを設定しましょう。