参考

Ownbit 多签 API v1(第一阶段)

让您自己的系统把付款清单交给 Ownbit 多签。在网页控制台中创建的 API 密钥可以提交草稿;签名人逐行审核后在手机上发起。API 从不动用资金。

版本日期 2026-11-18(草稿按 lineId 修改;草稿共五种状态)。本文档描述 API 的第一阶段。文中所有密钥、哈希、地址和 IP 地址都是虚构的示例(IP 地址取自专供文档使用的保留网段);USDT-TRC20 合约地址是真实的公开地址。

1. API 的用途

您的系统(下称“您的机器人”)把某个 Ownbit 多签的一份付款清单——即一份草稿——交给 Ownbit,之后再查询它的结果:已由签名人发起、已被拒绝、已撤回或已过期。

API 从不转移资金。只有当多签的一位签名人在 Ownbit 网页控制台中打开草稿、在自己的手机上发起它,并且有足够多的多签成员对每笔交易签名(m-of-n)后,草稿才会变成付款。签名人在发起前能看到每一行,Ownbit 对付款所做的各项检查照常进行,签名人也可以拒绝草稿。密钥不能签名、发起付款、同意或拒绝,也不能修改多签的安全策略、白名单或成员。

密钥可以做的事:

调用权限作用
GET /whoamidrafts:read描述密钥及其多签,并给出当天的调用次数
POST /draftsdrafts:submit提交一份草稿(1 到 500 行),或修改一份尚无人发起的草稿:按您的 lineId 添加、替换和删除行
GET /draftsdrafts:read列出此密钥的草稿,按变更时间从早到晚排序,带游标
GET /drafts/{draftId}drafts:read读取一份草稿及其各行
DELETE /drafts/{draftId}drafts:submit撤回一份尚无人发起的草稿

2. 第一阶段的范围

  • 仅支持 TRON 上的多签。 各行以 TRX 或 USDT(USDT-TRC20,合约 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t)付款;两者都是 6 位小数。
  • 仅支持 IPv4。 只能通过 IPv4 访问 API(第一阶段 api.bittool.com 没有 IPv6 地址),密钥的 IP 白名单只包含 IPv4 网段。
  • 没有 Webhook。 您的机器人需要轮询(轮询频率见第 10 节)。
  • 每份草稿最多 500 行。 签名人可能会在手机上把一份较大的草稿分成两次请求发起;这对您没有任何影响。

3. 基础 URL 与传输

https://api.bittool.com/ownbit/api/v1
  • 第一阶段仅支持 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_ 后跟 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

切勿把密钥放在 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_…"}。这包括:请求头缺失或格式错误、未知的密钥、尚未授权的密钥、已撤销或已过期的密钥、调用方地址不在密钥的 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"]}
字段规则
clientRequestId1 到 64 个 [A-Za-z0-9._:-] 字符,是您为这份付款清单设定的 ID。它永久对应多签的一份草稿(第 6.2.2 节)
lines0 到 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")
symbolTRX 或 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 加 1),或本次调用没有改变任何内容(重试):返回草稿的当前状态
409 not_editabledetails.draftId、details.status草稿已不再是 submitted(已有签名人发起,或已被撤回、拒绝或已过期):没有做任何修改
409 idempotency_conflict该 clientRequestId 已被同一多签的另一个密钥使用
410 gone该 clientRequestId 对应的草稿已被删除(保留期限,第 7.3 节)
422 invalid_linesdetails.errors有一行或多行无效,或草稿将变为空;没有做任何修改
429 daily_limitdetails.scope会超出密钥或多签 24 小时内的付款行数上限(第 10 节)。如果带有 details.neverFits: true 且没有 Retry-After,说明仅本次调用的行数就超过了上限,等待永远无济于事:请每次调用发送较少的行

details.errors 以 {"line":<index in lines>,"lineId":"po-1","field":"amount","reason":"amount_decimals"} 的形式列出前 50 个问题。原因: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,此后每次修改了草稿的调用都会使其加 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您的机器人撤回了它
expired7 天内无人发起

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 把您的清单从您的机器人传送到签名人的屏幕上。为确保途中没有任何改动:

  1. 在您自己的审批渠道中展示 clientRequestId 和指纹(contentHash 的前 16 个十六进制字符),放在已批准的付款清单旁边。修改过的草稿会有新的指纹:请展示最新的指纹。签名人会在网页控制台中看到这两项——由他们的浏览器根据即将发起的行重新计算——并被要求与您的记录进行比对。只有您的审批记录中展示了它们,才能进行这种比对。
  2. 重新计算 contentHash(第 6.2.3 节):根据您读取的每份草稿的行进行计算,并与您为该草稿最新修订计算的值进行比较。
  3. 自行在链上核对多签的付款。 在第一阶段,Ownbit 不报告每一行的交易。草稿一旦变为 started,请将其各行与多签地址(whoami 的 multisig.address)的转出交易进行比对:每笔付款的收款人、金额和代币都必须与您的某一行一致,并且每一行最多只应被付款一次。
  4. 留意 repeated:与其他近期草稿中某一行重复的行会为签名人标记出来;在您的系统中也应标记出来。
  5. 对于企业多签,请其成员开启白名单和每日限额:这样即使草稿有误,也无法付款给未知地址或超过限额。其他多签没有白名单,因此签名人的核对是唯一的检查。

9. 错误

每个错误都使用以下响应体:

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

message 是一句固定的英文句子,供人阅读;程序请依据 code 和 details 处理。消息从不回显您的输入。

HTTPcode情形
400invalid_request不是 JSON、类型错误、未知字段、错误的 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_large超过 256 KiB 的请求体
415unsupported_media_type不是 JSON 的 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

来自 API 前端防护层的 429(scope 为 edge)或 413 格式相同,但为 "requestId":null。

10. 速率限制与每日上限

10.1 各项限制

限制值details.scopecode
同一地址的请求,突发每秒 20 个(突发最多 40 个),20 个打开的连接edgerate_limited
每个密钥的调用每秒 10 次key_secondrate_limited
每个密钥的调用每分钟 300 次key_minuterate_limited
每个密钥的 POST /drafts每小时 60 次key_submit_hourrate_limited
每个密钥同时进行中的调用2key_concurrentrate_limited
每个多签(所有密钥)同时进行中的调用4multisig_concurrentrate_limited
每个地址的调用(有效密钥)每分钟 600 次;对 IP 白名单非空且包含该地址的密钥从不拒绝ip_minuterate_limited
每个密钥的调用每天 10,000 次key_dayrate_limited
每个多签的调用(所有密钥合计)每天 20,000 次multisig_dayrate_limited
每个地址的调用(有效密钥)每天 50,000 次;对 IP 白名单非空且包含该地址的密钥从不拒绝ip_dayrate_limited
每个地址的调用(有效密钥),硬上限每天 200,000 次,对所有密钥生效ip_day(details.limit 200000)rate_limited
每个地址的失败调用每分钟 20 次;超过后该地址被暂停 10 分钟ip_failuresrate_limited
每个地址的失败调用每天 200 次;超过后该地址被封锁 24 小时ip_blockedrate_limited
每个网络(/24)的失败调用每天 1,000 次;超过后该网络被封锁 24 小时net_blockedrate_limited
每个密钥的付款行密钥自己的上限(1 到 10,000,默认 1,000),任意 24 小时内key_lines_24hdaily_limit
每个多签的付款行任意 24 小时内 10,000 行multisig_lines_24hdaily_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 白名单非空且包含该地址的密钥不会被每分钟 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、代码仓库、日志、URL、工单或聊天消息中。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。

最近更新:

下载

下载 Ownbit

安装 App,然后按你的需求设置冷钱包或多签。