Ownbit MultiSig API v1 (giai đoạn 1)
Để hệ thống của bạn tự chuyển danh sách chi trả cho một ví Ownbit MultiSig. Khóa API tạo trong Web Console gửi các bản nháp; người ký xem từng dòng rồi bắt đầu trên điện thoại của mình. API không bao giờ tự chuyển tiền.
Phiên bản ngày 2026-11-18 (bản nháp thay đổi theo lineId; năm trạng thái bản nháp). Tài liệu này mô tả giai đoạn 1 của API. Mọi khóa, hash, địa chỉ và địa chỉ IP trong tài liệu đều là ví dụ dựng sẵn (các địa chỉ IP lấy từ những dải dành riêng cho tài liệu); địa chỉ hợp đồng USDT-TRC20 là địa chỉ thật, công khai.
1. API làm gì
Hệ thống của bạn (dưới đây gọi là "bot của bạn") giao cho Ownbit một danh sách khoản chi trả cho một ví MultiSig của Ownbit, gọi là bản nháp, và sau đó đọc lại kết quả của nó: được một người ký khởi chạy, bị từ chối, bị rút lại hay đã hết hạn.
API không bao giờ di chuyển tiền. Một bản nháp chỉ trở thành các khoản thanh toán khi một người ký của ví MultiSig mở nó trong Web Console của Ownbit, khởi chạy nó trên điện thoại của chính mình, và đủ số thành viên của ví MultiSig ký từng giao dịch (m trên n). Người ký thấy từng dòng trước khi khởi chạy, mọi kiểm tra mà Ownbit thực hiện với một khoản thanh toán vẫn được áp dụng, và người ký có thể từ chối bản nháp. Một khóa không thể ký, khởi chạy thanh toán, phê duyệt, từ chối, hay thay đổi chính sách, danh sách trắng hoặc thành viên của ví MultiSig.
Những gì một khóa có thể làm:
| Lệnh gọi | Quyền | Chức năng |
|---|---|---|
GET /whoami | drafts:read | Mô tả khóa và ví MultiSig của nó, kèm số lệnh gọi trong ngày hôm nay |
POST /drafts | drafts:submit | Gửi một bản nháp (1 đến 500 dòng), hoặc thay đổi một bản nháp chưa ai khởi chạy: thêm, thay thế và xóa dòng theo lineId của bạn |
GET /drafts | drafts:read | Liệt kê các bản nháp của khóa này, thay đổi cũ nhất trước, kèm con trỏ |
GET /drafts/{draftId} | drafts:read | Đọc một bản nháp cùng các dòng của nó |
DELETE /drafts/{draftId} | drafts:submit | Rút lại một bản nháp chưa ai khởi chạy |
2. Phạm vi giai đoạn 1
- Chỉ ví MultiSig trên TRON. Các dòng thanh toán bằng
TRXhoặcUSDT(USDT-TRC20, hợp đồngTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t); cả hai đều có 6 chữ số thập phân. - Chỉ IPv4. API chỉ truy cập được qua IPv4 (
api.bittool.comkhông có địa chỉ IPv6 trong giai đoạn 1), và danh sách IP cho phép của một khóa chứa các dải IPv4. - Không có webhook. Bot của bạn thăm dò định kỳ (mục 10 cho biết tần suất).
- Tối đa 500 dòng mỗi bản nháp. Người ký có thể khởi chạy một bản nháp lớn thành hai yêu cầu trên điện thoại của mình; điều đó không thay đổi gì đối với bạn.
3. URL gốc và giao thức truyền tải
https://api.bittool.com/ownbit/api/v1- Chỉ IPv4 trong giai đoạn 1: tên miền không có địa chỉ IPv6, nên một máy chủ có cả IPv4 lẫn IPv6 sẽ gọi qua IPv4 và được đối chiếu với danh sách IPv4 được phép của nó.
- Chỉ HTTPS. Yêu cầu không đến qua HTTPS bị từ chối với
403 https_requiredvà không bao giờ được chuyển hướng. Một khóa đã bị gửi qua HTTP thường phải được coi là đã bị lộ: hãy thu hồi nó và tạo khóa khác. Phản hồi HTTPS có kèmStrict-Transport-Security: max-age=31536000. - JSON dạng UTF-8. Các yêu cầu
POSTgửiContent-Type: application/json(hậu tố; charset=utf-8vẫn được chấp nhận). Phần thân yêu cầu tối đa 256 KiB. - Thời gian là chuỗi ISO 8601 theo UTC có phần mili giây, ví dụ
2026-11-17T06:00:00.000Z. - Mọi phản hồi đều kèm
Cache-Control: no-store,Pragma: no-cachevàX-Request-Id(req_theo sau là 16 ký tự[0-9a-z]). Phần thân lỗi lặp lại giá trị này trongrequestId. Hãy nêu nó khi bạn liên hệ bộ phận hỗ trợ. - Không có CORS. Không trang trình duyệt nào có thể gọi API: hãy gọi từ máy chủ của bạn.
- Yêu cầu nghiêm ngặt, phản hồi mở. Yêu cầu có trường mà API không biết sẽ bị từ chối (
400 invalid_request). Phản hồi có thể có thêm trường mới theo thời gian: hãy bỏ qua các trường bạn không biết.
4. Khóa
- Nguồn gốc. Một thành viên của ví MultiSig tạo khóa trong Web Console của Ownbit, tại thẻ API của ví MultiSig (bất kỳ thành viên nào có vai trò người ký đều làm được), và cấp quyền cho khóa trên điện thoại bằng ứng dụng Ownbit. Khóa được hiển thị một lần, trong thẻ trình duyệt đó, ngay sau khi điện thoại cấp quyền. Ownbit chỉ giữ hash của khóa và không thể hiển thị lại: nếu bị mất, hãy thu hồi nó và tạo khóa khác.
- Định dạng.
obk_theo sau là 43 ký tự[0-9A-Za-z](tổng cộng 47 ký tự, khoảng 256 bit ngẫu nhiên). Ở mọi nơi Ownbit hiển thị khóa, nó chỉ hiển thị 4 ký tự cuối, dưới dạngobk_…defg. - Tùy chọn khi tạo. Một tên (tối đa 30 ký tự, không trùng giữa các khóa của ví MultiSig); thời hạn hiệu lực 30, 90 (mặc định), 180 hoặc 365 ngày, 2 năm hoặc 5 năm, tính từ lúc điện thoại cấp quyền; một danh sách IPv4 được phép gồm tối đa 20 dải, mỗi dải từ
/8đến/32(danh sách rỗng nghĩa là mọi địa chỉ); và số dòng thanh toán tối đa mà khóa được gửi trong bất kỳ 24 giờ nào (1 đến 10,000, mặc định 1,000). - Quyền. Mọi khóa giai đoạn 1 đều có
drafts:submitvàdrafts:read. - Một ví MultiSig. Một khóa áp dụng cho một địa chỉ ví MultiSig: TRX của địa chỉ đó và, nếu có, USDT tại địa chỉ đó. Ownbit có thể liệt kê một địa chỉ thành nhiều ví MultiSig, mỗi token một ví; chúng dùng chung các khóa. Một khóa không bao giờ thấy dữ liệu của ví MultiSig khác.
- Tối đa 5 khóa cho mỗi ví MultiSig (tính cả khóa đang chờ cấp quyền).
- Thu hồi. Bất kỳ thành viên nào cũng có thể thu hồi khóa vào bất kỳ lúc nào, trong Web Console hoặc trong ứng dụng Ownbit. Khóa đã bị thu hồi hoặc hết hạn sẽ thất bại ngay lập tức. Thu hồi khóa cũng đồng thời từ chối các bản nháp chưa ai khởi chạy của khóa đó (lý do
key_revoked); các bản nháp đã được khởi chạy vẫn tiếp tục. - Thông báo. Điện thoại của mọi thành viên đều được thông báo khi một khóa được cấp quyền hoặc bị thu hồi. Nếu nhóm của bạn thấy một thông báo như vậy mà không lường trước, hãy thu hồi khóa.
5. Xác thực
Gửi khóa trong mọi lệnh gọi, và chỉ trong header này:
Authorization: Bearer obk_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefgKhông bao giờ đặt khóa trong URL, chuỗi truy vấn hay phần thân yêu cầu.
curl -sS https://api.bittool.com/ownbit/api/v1/whoami \
-H "Authorization: Bearer $OWNBIT_API_KEY"- Mọi vấn đề về khóa đều nhận cùng một phản hồi:
401 {"error":{"code":"unauthorized","message":"Invalid or unusable API key"},"requestId":"req_…"}. Điều đó bao gồm header bị thiếu hoặc sai định dạng, khóa không xác định, khóa chưa được cấp quyền, khóa đã bị thu hồi hoặc hết hạn, địa chỉ gọi nằm ngoài danh sách cho phép của khóa, người tạo khóa không còn là thành viên hoặc không còn vai trò người ký, và ví MultiSig không còn hoạt động. Các thành viên của ví MultiSig thấy lần từ chối gần nhất của mỗi khóa cùng lý do trong Web Console, vì vậy hãy hỏi họ khi bạn không biết tại sao. - Một khóa hợp lệ nhưng không có quyền mà lệnh gọi yêu cầu sẽ nhận
403 forbidden. - Lỗi
401không tự hết khi thử lại. Hãy dừng lại và nhờ một người kiểm tra (mục 10.4: thất bại lặp lại sẽ chặn địa chỉ của bạn).
6. Các lệnh gọi
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: giới hạn dòng của khóa và số dòng khóa đã gửi trong 24 giờ qua.callsToday,dailyCalls: số lệnh gọi của khóa này tính từ 00:00 UTC (kể cả lệnh gọi này) và hạn mức lệnh gọi hằng ngày của nó.multisigCallsToday,multisigDailyCalls: tương tự, cho tất cả các khóa của ví MultiSig cộng lại.callsResetAt: thời điểm các bộ đếm hằng ngày bắt đầu lại (mục 10).multisig.symbols: các ký hiệu bạn có thể dùng để thanh toán.multisig.defaultSymbol: ký hiệu mà một dòng không cósymbolsẽ dùng để thanh toán. Trên ví MultiSig TRON, đó làTRX, không phảiUSDT: hãy gửisymboltrên mọi dòng (mục 6.2).requiredNumtrênownerNum: số chữ ký mà mỗi khoản thanh toán cần.
6.2 POST /drafts
Một lệnh gọi tạo ra một bản nháp, và các lệnh gọi sau với cùng clientRequestId sẽ thay đổi nó: thêm dòng, thay thế dòng và xóa dòng, mỗi dòng được xác định bằng lineId của riêng bạn. Một bản nháp chỉ có thể thay đổi khi chưa ai khởi chạy nó (trạng thái submitted).
Yêu cầu (đúng các khóa JSON này; bất kỳ khóa nào khác đều là 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"}]}Một lệnh gọi sau đó thêm một dòng, thay đổi po-1 và xóa 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"]}| Trường | Quy tắc |
|---|---|
clientRequestId | 1 đến 64 ký tự [A-Za-z0-9._:-], mã định danh riêng của bạn cho danh sách chi trả này. Nó xác định một bản nháp của ví MultiSig, vĩnh viễn (mục 6.2.2) |
lines | 0 đến 500 đối tượng, mỗi đối tượng chỉ có các khóa JSON bên dưới. Lệnh gọi đầu tiên phải gửi ít nhất một đối tượng |
remove | Tùy chọn. Các lineId của những dòng cần lấy ra khỏi bản nháp. Một lineId mà bản nháp không có sẽ bị bỏ qua, nên thử lại là an toàn. Một lineId không được có mặt đồng thời trong lines và trong remove |
lineId | Bắt buộc. 1 đến 64 ký tự [A-Za-z0-9._:/-], mã định danh riêng của bạn cho dòng, duy nhất trong bản nháp (một clientRequestId khác bắt đầu lại từ đầu). Một lineId mà bản nháp đã có sẽ thay thế dòng đó tại chỗ; một mã mới được thêm vào cuối. Được trả lại cho bạn; không bao giờ được ghi lên blockchain, không bao giờ hiển thị cho người ký |
to | Một địa chỉ TRON (34 ký tự, base58check). Không phải địa chỉ của chính ví MultiSig, không phải địa chỉ zero của TRON T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb, không phải hợp đồng USDT (token gửi đến đó sẽ bị mất) |
amount | Một chuỗi khớp ^(0|[1-9][0-9]*)(\.[0-9]+)?$, lớn hơn không, tối đa 6 chữ số thập phân tính theo đúng chuỗi đã gửi ("1.0000000" bị từ chối với amount_decimals; "80.500000" được chấp nhận và lưu thành "80.5"), tối đa 9223372036854775807 theo đơn vị nhỏ nhất. Hãy gửi chuỗi, không bao giờ gửi số JSON. Ownbit lưu nó ở dạng chuẩn: bỏ các số không ở cuối phần thập phân, rồi bỏ dấu chấm đứng trơ trọi ("80.50" thành "80.5", "2.0" thành "2") |
symbol | TRX hoặc USDT. Hãy gửi nó trên mọi dòng. Nếu bạn bỏ qua, dòng sẽ thanh toán bằng defaultSymbol của ví MultiSig, mà trên ví MultiSig TRON là TRX: một khoản chi USDT không có symbol sẽ trở thành khoản chi TRX với cùng con số. Ví MultiSig phải có ký hiệu đó (xem whoami, trường symbols) |
memo | Tùy chọn. Tối đa 80 ký tự; không chứa ký tự nào trong số , ' " \; không có ký tự điều khiển, ký tự ngắt dòng hay ký tự vô hình; không có khoảng trắng ở đầu hoặc cuối; không phải memo dành riêng (bắt đầu bằng admin:, chứa -no-broadcast, hoặc kết thúc bằng ***br***, không phân biệt hoa thường). Thiếu và "" là như nhau |
Ownbit trước tiên xóa các dòng trong remove, sau đó thay thế hoặc thêm từng dòng của lines, rồi kiểm tra toàn bộ bản nháp: tối đa 500 dòng, ít nhất một dòng, và không có hai dòng nào trùng cả to, amount dạng chuẩn và symbol (blockchain sẽ từ chối dòng thứ hai vì trùng lặp trong khi dòng thứ nhất đang chờ chữ ký). Mỗi dòng bạn gửi đều được kiểm tra như ở lệnh gọi đầu tiên; nếu có bất cứ điều gì bị từ chối, sẽ không có gì thay đổi.
Phản hồi:
| Trạng thái | Phần thân | Khi nào |
|---|---|---|
201 | {"draft":<draft>} | Một bản nháp mới, trạng thái submitted, bản sửa đổi 1, mọi dòng ở pending |
200 | {"draft":<draft>} | Bản nháp đã thay đổi (revision của nó tăng thêm một), hoặc lệnh gọi không thay đổi gì (một lần thử lại): bản nháp ở trạng thái hiện tại |
409 not_editable | details.draftId, details.status | Bản nháp không còn ở submitted (một người ký đã khởi chạy nó, hoặc nó đã bị rút lại, bị từ chối hoặc hết hạn): không có gì thay đổi |
409 idempotency_conflict | clientRequestId đã được một khóa khác của cùng ví MultiSig sử dụng | |
410 gone | Bản nháp của clientRequestId này đã bị xóa (hết thời hạn lưu giữ, mục 7.3) | |
422 invalid_lines | details.errors | Một hoặc nhiều dòng không hợp lệ, hoặc bản nháp sẽ bị trống; không có gì thay đổi |
429 daily_limit | details.scope | Giới hạn dòng trong 24 giờ của khóa hoặc của ví MultiSig sẽ bị vượt quá (mục 10). Khi có details.neverFits: true và không có Retry-After, riêng lệnh gọi này đã có nhiều dòng hơn giới hạn, nên chờ đợi không bao giờ có ích: hãy gửi ít dòng hơn trong mỗi lệnh gọi |
details.errors liệt kê 50 vấn đề đầu tiên dưới dạng {"line":<index in lines>,"lineId":"po-1","field":"amount","reason":"amount_decimals"}. Các lý do: 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 và lineId là null: việc xóa sẽ khiến bản nháp không còn dòng nào; thay vào đó hãy rút lại bản nháp, mục 6.5).
6.2.1 Bản nháp
Dạng đầy đủ (dạng trong danh sách không có 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_theo sau là 24 ký tự[0-9a-z].revision: 1 đối với bản nháp mới, tăng thêm một sau mỗi lệnh gọi làm nó thay đổi.startedAt: thời điểm một người ký khởi chạy bản nháp lần đầu trên điện thoại, nếu không thì lànull. Giá trị này không đổi khi một người ký khởi chạy lại bản nháp.lines[].lineId: mã định danh của bạn cho dòng.lines[].index: vị trí hiện tại của dòng, tính từ 0 (vị trí này thay đổi khi một dòng đứng trước bị xóa: hãy đối chiếu các dòng theolineId).memolà""khi không có.lines[].state: luôn theo trạng thái của bản nháp (mục 7.2). Trong giai đoạn 1, một dòng không mang mã giao dịch, hash, số chữ ký hay lỗi: hãy kiểm tra các khoản thanh toán như mục 8 hướng dẫn.totals: tổng theo từng ký hiệu;counts: số dòng ở mỗi trạng thái (chỉ các trạng thái có dòng).repeated:truekhi một bản nháp khác của ví MultiSig này trong 7 ngày qua có một dòng với cùng địa chỉ, số tiền và ký hiệu. Người ký thấy dấu đánh dấu này và phải xác nhận nó trước khi khởi chạy bản nháp; hãy kiểm tra hệ thống của chính bạn khi thấy nó.rejection:{"reason","note","at"}khi bản nháp bị từ chối, nếu không thì lànull. Các lý do:whitelist,address,amount,duplicate,other(do một người ký chọn trong Web Console, người này có thể thêm mộtnotedài một dòng),phone(một người ký đã từ chối trên điện thoại; không cónote), vàkey_revoked. API không bao giờ cho biết thành viên nào đã từ chối.
6.2.2 Thử lại và thay đổi
clientRequestIdxác định một bản nháp của ví MultiSig vĩnh viễn: nó vẫn bị coi là đã dùng trong khi bản nháp còn được lưu giữ, và trong 365 ngày sau khi bản nháp bị xóa (410). Chỉ khóa đã tạo bản nháp mới có thể thay đổi nó; một khóa khác của cùng ví MultiSig nhận409 idempotency_conflict(sau khi xoay vòng khóa, hãy dùng mã định danh mới). Hãy làm cho mã định danh của bạn là duy nhất mãi mãi, ví dụ ngày tháng cộng với số thứ tự.- Mọi lệnh gọi đều an toàn để thử lại. Sau khi hết thời gian chờ hoặc gặp lỗi mạng, hãy gửi lại cùng yêu cầu đó: các dòng bạn đã gửi tự thay thế bằng chính nội dung như cũ và các dòng đã xóa thì đã không còn, nên phản hồi là bản nháp ở trạng thái hiện tại, không bao giờ là bản nháp thứ hai hay bản sao thứ hai của một dòng.
- Chỉ có thể thay đổi khi bản nháp ở
submitted. Khi một người ký đã khởi chạy nó, lệnh gọi sẽ trả về409 not_editable: hãy yêu cầu người ký từ chối các dòng không được thanh toán, và gửi các dòng mới dưới mộtclientRequestIdmới. - Người ký thấy bản nháp đúng như lúc họ mở nó. Nếu bản nháp thay đổi trong khi người ký đang mở, Web Console của họ sẽ từ chối khởi chạy và yêu cầu họ mở lại.
- Hai lệnh gọi đồng thời với cùng mã định danh được áp dụng lần lượt, cái này sau cái kia.
6.2.3 Hash nội dung
contentHash là SHA-256 dạng hex chữ thường của các byte UTF-8 của mảng JSON rút gọn chứa các dòng của bản nháp theo đúng thứ tự, mỗi dòng được viết dưới dạng {"lineId","to","amount","symbol","memo"} theo đúng thứ tự đó, với số tiền ở dạng chuẩn, ký hiệu luôn được ghi ra và "" cho memo bị thiếu. Nó thay đổi theo mọi thay đổi của bản nháp. Với yêu cầu đầu tiên ở trên:
[{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001"},{"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT","memo":""}]→ cc43baacd7df98efac68139dd9be5dba47d4fa0343c034e3fd54098409cf59a4. Hãy tự dựng chuỗi này (không cần thứ tự khóa hay cách escape của bất kỳ thư viện JSON nào: không trường nào trong số này được phép chứa ký tự cần escape). Dấu vân tay mà người ký thấy là 16 ký tự hex đầu tiên của contentHash (ở đây là cc43baacd7df98ef). Mục 8 cho biết phải làm gì với chúng.
6.3 GET /drafts?since=<cursor>&limit=<n>
Các bản nháp của khóa này, sắp xếp theo updatedAt, rồi theo draftId, nằm sau con trỏ (không có since: từ bản nháp cũ nhất còn được lưu giữ). limit từ 1 đến 100, mặc định 50.
{"drafts":[<draft without lines>],"nextCursor":"<opaque>","hasMore":false}updatedAt của một bản nháp thay đổi mỗi khi trạng thái hoặc các dòng của nó thay đổi, nên thăm dò với nextCursor gần nhất sẽ thấy mọi thay đổi. Một trang rỗng trả về con trỏ bạn đã gửi; hãy tiếp tục dùng nó. Một con trỏ không đọc được là 400 invalid_request.
6.4 GET /drafts/{draftId}
200 {"draft":<draft>}. Bản nháp của một khóa khác (kể cả của cùng ví MultiSig), hoặc bản nháp không còn được lưu giữ: 404 not_found.
6.5 DELETE /drafts/{draftId}
Rút lại một bản nháp chưa ai khởi chạy. Chỉ khi trạng thái của nó là submitted: mọi dòng chuyển thành withdrawn, 200 {"draft":<draft>}. Đã ở withdrawn: lại là 200. Nếu không thì 409 not_withdrawable kèm details.status. Khi một người ký đã khởi chạy bản nháp, thay vào đó hãy yêu cầu người ký từ chối phần còn lại.
7. Trạng thái
7.1 status của bản nháp
| Trạng thái | Ý nghĩa |
|---|---|
submitted | Chưa ai khởi chạy nó. Chỉ lúc này bot của bạn mới có thể thay đổi nó (mục 6.2) hoặc rút lại nó (mục 6.5) |
started | Một người ký đã khởi chạy nó trên điện thoại (startedAt cho biết lần đầu điều đó xảy ra khi nào). Người ký có thể mở và khởi chạy lại nó, ví dụ sau khi điện thoại của họ dừng giữa chừng; nó vẫn ở started |
rejected | Một người ký đã từ chối nó, trong Web Console hoặc trên điện thoại (trước hoặc sau khi nó được khởi chạy), hoặc khóa của nó đã bị thu hồi trước khi có ai khởi chạy. rejection cho biết lý do |
withdrawn | Bot của bạn đã rút lại nó |
expired | Không ai khởi chạy nó trong vòng 7 ngày |
Ownbit chỉ báo cáo những gì nó biết chắc chắn: rằng một người ký đã khởi chạy bản nháp trên điện thoại. Ownbit không biết những khoản thanh toán nào diễn ra sau đó, nên một bản nháp started có thể đã được thanh toán toàn bộ, một phần hoặc hoàn toàn chưa. Các khoản thanh toán là giao dịch của ví MultiSig: hãy kiểm tra chúng như mục 8 hướng dẫn, và đừng gửi lại các dòng của một bản nháp đã khởi chạy trừ khi người ký cho bạn biết chúng chưa được thanh toán.
7.2 state của dòng
state của một dòng luôn là trạng thái của bản nháp chứa nó: trong giai đoạn 1, Ownbit không theo dõi giao dịch của từng dòng.
| Trạng thái | Ý nghĩa |
|---|---|
pending | Bản nháp ở submitted |
started | Bản nháp ở started |
rejected, withdrawn, expired | Trạng thái của bản nháp |
7.3 Vòng đời
Bản nháp không ai khởi chạy sẽ hết hạn sau 7 ngày. Bản nháp đã khởi chạy vẫn ở started cho đến khi một người ký từ chối nó. Các bản nháp bị từ chối, bị rút lại và hết hạn được lưu giữ 30 ngày sau khi kết thúc, còn bản nháp đã khởi chạy được lưu giữ 30 ngày sau lần thay đổi cuối cùng; sau đó chúng bị xóa (khi đó GET trả về 404; cùng clientRequestId đó trả về 410 thêm 365 ngày nữa).
8. Kiểm tra những gì được thanh toán
Ownbit chuyển danh sách của bạn từ bot của bạn đến màn hình của người ký. Để chắc chắn không có gì bị thay đổi trên đường đi:
- Hiển thị
clientRequestIdvà dấu vân tay (16 ký tự hex đầu tiên củacontentHash) trong kênh phê duyệt của riêng bạn, bên cạnh danh sách chi trả đã được phê duyệt. Một bản nháp bạn thay đổi sẽ có dấu vân tay mới: hãy hiển thị dấu vân tay mới nhất. Người ký thấy cả hai trong Web Console, được trình duyệt của họ tính lại từ các dòng họ sắp khởi chạy, và được yêu cầu so sánh chúng với bản ghi của bạn. Việc so sánh đó chỉ có thể thực hiện nếu bản ghi phê duyệt của bạn hiển thị chúng. - Tính lại
contentHash(mục 6.2.3) từ các dòng của mọi bản nháp bạn đọc, và so sánh với giá trị bạn đã tính cho bản sửa đổi mới nhất của bản nháp. - Tự kiểm tra các khoản thanh toán của ví MultiSig trên blockchain. Trong giai đoạn 1, Ownbit không báo cáo giao dịch của từng dòng. Khi một bản nháp đã ở
started, hãy so sánh các dòng của nó với các giao dịch đi ra từ địa chỉ của ví MultiSig (lấy từwhoami, trườngmultisig.address): người nhận, số tiền và token của mọi khoản thanh toán phải khớp với một trong các dòng của bạn, và mỗi dòng chỉ nên được thanh toán tối đa một lần. - Theo dõi
repeated: một dòng lặp lại một dòng của bản nháp gần đây khác sẽ được đánh dấu cho người ký; nó cũng nên được đánh dấu trong hệ thống của bạn. - Trên ví MultiSig Enterprise, hãy yêu cầu các thành viên bật danh sách trắng và giới hạn hằng ngày: khi đó ngay cả một bản nháp sai cũng không thể thanh toán cho địa chỉ lạ hoặc vượt quá giới hạn. Các ví MultiSig khác không có danh sách trắng, nên việc kiểm tra của người ký là lớp kiểm tra duy nhất.
9. Lỗi
Mọi lỗi đều có phần thân như sau:
{"error":{"code":"<code>","message":"<English sentence>","details":{}},"requestId":"req_0123456789abcdef"}message là một câu tiếng Anh cố định dành cho con người đọc; hãy lập trình dựa trên code và details. Thông báo không bao giờ lặp lại dữ liệu đầu vào của bạn.
| HTTP | code | Khi nào |
|---|---|---|
| 400 | invalid_request | Không phải JSON, sai kiểu dữ liệu, trường không xác định, clientRequestId không hợp lệ, không có dòng nào hoặc hơn 500 dòng, con trỏ hoặc limit không hợp lệ, phần thân yêu cầu không đến trong vòng 10 giây |
| 401 | unauthorized | Mọi vấn đề về khóa (mục 5) |
| 403 | forbidden | Khóa hợp lệ nhưng không có quyền mà lệnh gọi cần |
| 403 | https_required | Yêu cầu không đến qua HTTPS (hãy thu hồi khóa đi kèm yêu cầu đó) |
| 404 | not_found | Đường dẫn không xác định; bản nháp không thuộc khóa này, hoặc không còn được lưu giữ |
| 405 | method_not_allowed | Phương thức mà đường dẫn không chấp nhận (kể cả OPTIONS) |
| 409 | idempotency_conflict | Mục 6.2 |
| 409 | not_editable | Mục 6.2 (details.status) |
| 409 | not_withdrawable | Mục 6.5 (details.status) |
| 410 | gone | Một clientRequestId có bản nháp đã bị xóa |
| 413 | too_large | Phần thân vượt quá 256 KiB |
| 415 | unsupported_media_type | Một POST không phải JSON |
| 422 | invalid_lines | Mục 6.2 (details.errors) |
| 429 | rate_limited, daily_limit | Một giới hạn (mục 10), kèm Retry-After, details.scope, details.limit, details.retryAfter |
| 500 | internal | Lỗi phía Ownbit; hãy thử lại sau |
| 503 | unavailable | API đang bị tắt hoặc hiện không thể phản hồi; kèm details.scope api_busy và Retry-After khi API đang quá tải |
Một 429 với phạm vi edge, hoặc một 413, đến từ lớp bảo vệ phía trước API có cùng cấu trúc, với "requestId":null.
10. Giới hạn tần suất và hạn mức hằng ngày
10.1 Các giới hạn
| Giới hạn | Giá trị | details.scope | code |
|---|---|---|---|
| Yêu cầu từ một địa chỉ, burst | 20 mỗi giây (burst tối đa 40), 20 kết nối đang mở | edge | rate_limited |
| Lệnh gọi mỗi khóa | 10 mỗi giây | key_second | rate_limited |
| Lệnh gọi mỗi khóa | 300 mỗi phút | key_minute | rate_limited |
POST /drafts mỗi khóa | 60 mỗi giờ | key_submit_hour | rate_limited |
| Lệnh gọi đang xử lý đồng thời, mỗi khóa | 2 | key_concurrent | rate_limited |
| Lệnh gọi đang xử lý đồng thời, mỗi ví MultiSig (tất cả các khóa của nó) | 4 | multisig_concurrent | rate_limited |
| Lệnh gọi mỗi địa chỉ (khóa hợp lệ) | 600 mỗi phút; không bao giờ từ chối khóa có danh sách cho phép không rỗng và chứa địa chỉ đó | ip_minute | rate_limited |
| Lệnh gọi mỗi khóa | 10,000 mỗi ngày | key_day | rate_limited |
| Lệnh gọi mỗi ví MultiSig (tất cả các khóa của nó cộng lại) | 20,000 mỗi ngày | multisig_day | rate_limited |
| Lệnh gọi mỗi địa chỉ (khóa hợp lệ) | 50,000 mỗi ngày; không bao giờ từ chối khóa có danh sách cho phép không rỗng và chứa địa chỉ đó | ip_day | rate_limited |
| Lệnh gọi mỗi địa chỉ (khóa hợp lệ), hạn mức cứng | 200,000 mỗi ngày, áp dụng cho mọi khóa | ip_day (details.limit 200000) | rate_limited |
| Lệnh gọi thất bại mỗi địa chỉ | 20 mỗi phút; vượt quá mức này, địa chỉ bị tạm giữ 10 phút | ip_failures | rate_limited |
| Lệnh gọi thất bại mỗi địa chỉ | 200 mỗi ngày; vượt quá mức này, địa chỉ bị chặn 24 giờ | ip_blocked | rate_limited |
| Lệnh gọi thất bại mỗi mạng (một /24) | 1,000 mỗi ngày; vượt quá mức này, mạng bị chặn 24 giờ | net_blocked | rate_limited |
| Dòng thanh toán mỗi khóa | giới hạn riêng của khóa (1 đến 10,000, mặc định 1,000) trong bất kỳ 24 giờ nào | key_lines_24h | daily_limit |
| Dòng thanh toán mỗi ví MultiSig | 10,000 trong bất kỳ 24 giờ nào | multisig_lines_24h | daily_limit |
| Toàn bộ API quá tải | (bảo vệ dịch vụ) | api_busy (HTTP 503) | unavailable |
- Một ngày là ngày theo lịch UTC: các hạn mức lệnh gọi và hạn mức thất bại bắt đầu lại lúc 00:00 UTC (08:00 giờ Bắc Kinh). Hai giới hạn dòng là cửa sổ trượt: bất kỳ 24 giờ nào.
- Những gì được tính. Mọi lệnh gọi thực hiện bằng khóa hợp lệ đều được tính vào giới hạn của khóa, ví MultiSig và địa chỉ: kể cả lệnh đọc, các lệnh gọi bị từ chối sau khi khóa đã được chấp nhận (
403,404,409,422, hoặc429của giới hạn dòng), và mộtPOST /draftslặp lại. Lệnh gọi bị từ chối bởi giới hạn tần suất hoặc hạn mức không được tính vào bất kỳ giới hạn nào, nên chờ hếtRetry-Afterluôn có tác dụng. Lệnh gọi có khóa bị từ chối (401) chỉ được tính vào số lệnh gọi thất bại của địa chỉ và mạng của nó. - Địa chỉ hoặc mạng bị tạm giữ hay bị chặn (tạm giữ 10 phút, hoặc chặn 24 giờ) vẫn phục vụ mọi khóa hợp lệ có danh sách cho phép chấp nhận địa chỉ đó (danh sách cho phép rỗng chấp nhận tất cả). Chỉ các lệnh gọi với khóa sai, và các khóa có danh sách cho phép không chấp nhận địa chỉ đó, mới bị từ chối ở đó. Vì vậy một khóa hợp lệ không bao giờ bị chặn vì thất bại của người khác từ cùng địa chỉ.
- Giới hạn theo địa chỉ được chia sẻ với mọi người gọi từ địa chỉ đó. Một khóa có danh sách cho phép không rỗng và chứa địa chỉ đó không bị từ chối bởi giới hạn 600 mỗi phút hay 50,000 mỗi ngày, nhưng giới hạn burst (20 mỗi giây) và hạn mức cứng (200,000 mỗi ngày) tính tất cả mọi người trên địa chỉ đó, nên trên NAT dùng chung, CI runner hoặc egress đám mây, người khác vẫn có thể làm chậm lệnh gọi của bạn; và một
429với phạm viip_minutehoặcip_daycho bạn biết người khác trên địa chỉ của bạn đang gọi nhiều. Hãy dùng một địa chỉ đi ra riêng.
10.2 Các phản hồi
Một giới hạn trả về 429 (hoặc 503 đối với api_busy) với:
{"error":{"code":"rate_limited","message":"Daily call limit of this key reached",
"details":{"scope":"key_day","limit":10000,"retryAfter":31260}},"requestId":"req_0123456789abcdef"}và header Retry-After: 31260: số giây nguyên cần chờ (ít nhất 1). Thời gian này kéo dài đến hết cửa sổ, thời gian tạm giữ hoặc thời gian chặn; đến 00:00 UTC đối với các hạn mức lệnh gọi hằng ngày; đối với giới hạn dòng, đến khi đủ số dòng cũ nhất của bạn ra khỏi khung 24 giờ (ít nhất 60 giây); 1 đối với edge và hai phạm vi _concurrent; đối với api_busy, từ 1 đến khoảng 90 giây, có một phần ngẫu nhiên để các client bị từ chối không quay lại cùng lúc. Khi nhiều giới hạn cùng từ chối, phản hồi nêu giới hạn có thời gian chờ lâu nhất. details.limit là giá trị của giới hạn đó (không có đối với api_busy). 429 duy nhất không có Retry-After là trường hợp bản nháp không bao giờ vừa với giới hạn dòng của nó: details.neverFits là true và details.retryAfter là null (mục 6.2).
Các thông báo: 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 Các header
Mọi phản hồi cho lệnh gọi có khóa đã được chấp nhận (thành công, các lỗi phát sinh sau đó, và các 429 của nó) đều kèm:
| Header | Giá trị |
|---|---|
X-RateLimit-Limit | Hạn mức lệnh gọi hằng ngày của khóa (10000) |
X-RateLimit-Remaining | Số còn lại hôm nay sau lệnh gọi này: giá trị nhỏ hơn giữa phần còn lại của khóa và của ví MultiSig của nó |
X-RateLimit-Reset | Thời điểm 00:00 UTC kế tiếp, tính bằng giây Unix (vào ngày 2026-11-17: 1794960000) |
Một 401, một 429 của edge, ip_failures, ip_blocked hoặc net_blocked, và một 503 không kèm header nào trong số này. GET /whoami cung cấp các số đếm tương tự trong phần thân (callsToday, multisigCallsToday, callsResetAt).
10.4 Cách một bot hoạt động đúng mực thăm dò và lùi lại
- Thăm dò
GET /drafts?since=<last nextCursor>mỗi 30 giây, với một tiến trình thăm dò cho mỗi khóa. Như vậy là 2,880 lệnh gọi mỗi ngày. Nếu nhiều bản sao bot của bạn dùng chung một khóa, hãy để một bản thăm dò và chia sẻ những gì nó đọc được. GiữnextCursorgần nhất qua các lần khởi động lại; trang rỗng trả về nó không đổi. KhihasMorelàtrue, hãy đọc trang tiếp theo ngay lập tức. - Không bao giờ thăm dò nhanh hơn ngân sách cho phép: tối đa một lần mỗi 86,400 × 2 /
X-RateLimit-Limitgiây (17.3 giây với mặc định 10,000), để việc thăm dò dùng tối đa một nửa số lệnh gọi trong ngày. Riêng việc thăm dò mỗi 10 giây đã tốn 8,640 lệnh gọi và chỉ để lại khoảng 1,300 cho mọi việc khác; hai bản sao bot làm như vậy trên cùng một khóa sẽ bị từ chối trước khi hết ngày. - Chỉ đọc một bản nháp riêng lẻ khi bạn cần các dòng của nó, tức là khi
updatedAtcủa nó thay đổi trong danh sách, và tối đa một lần mỗi phút cho mỗi bản nháp. Không thăm dò riêng từng bản nháp. - Theo dõi
X-RateLimit-Remaining. Khi giá trị này giảm xuống dưới một phần mười củaX-RateLimit-Limit, hãy thăm dò thưa hơn. Hãy nhớ rằng nó được chia sẻ với các khóa khác của ví MultiSig. - Khi gặp
429: chờRetry-Aftergiây, cộng thêm một khoảng trễ ngẫu nhiên nhỏ, rồi thử lại. Đừng thử lại sớm hơn: phản hồi sẽ vẫn như cũ. Vớikey_dayhoặcmultisig_day, hãy giữ con trỏ và tiếp tục sauX-RateLimit-Reset. - Khi gặp
503: nếu cóRetry-After, chờ khoảng đó cộng thêm ngẫu nhiên 0 đến 30 giây; nếu không có, lùi lại theo hàm mũ từ 30 giây đến tối đa 10 phút. - Khi gặp lỗi mạng hoặc
500trong lúcPOST /drafts: gửi lại cùng yêu cầu với cùngclientRequestId(mục 6.2.2), sau một khoảng lùi như trên. - Khi gặp
401: ngừng dùng khóa và báo cho một người. Thử lại một khóa bị từ chối không bao giờ có ích, và hơn 200 lần thất bại trong một ngày sẽ chặn địa chỉ của bạn trong 24 giờ đối với mọi khóa sai (các khóa hợp lệ của bạn vẫn hoạt động từ địa chỉ đó, mục 10.1). - Lên kế hoạch cho nửa đêm UTC: một khóa hoặc ví MultiSig đã dùng hết lệnh gọi trong ngày sẽ bị từ chối cho đến 00:00 UTC. Khi đó hãy tiếp tục sau một khoảng ngẫu nhiên 0 đến 30 giây, không phải đúng vào giây đó.
11. Khuyến nghị bảo mật
- Chỉ HTTPS. Không bao giờ gửi khóa qua HTTP thường; nếu điều đó đã xảy ra, hãy thu hồi khóa. Xác minh chứng chỉ của máy chủ như thường lệ.
- Giữ khóa trên máy chủ của bạn, trong kho lưu trữ bí mật. Không bao giờ đặt trong trình duyệt, ứng dụng di động, kho mã nguồn, dòng log, URL, ticket hay tin nhắn chat. Ownbit không bao giờ yêu cầu bạn cung cấp khóa.
- Cấp cho mọi khóa một danh sách IPv4 được phép gồm các địa chỉ đi ra cố định của máy chủ của bạn. Khi đó một khóa bị lộ không thể được dùng ở bất kỳ nơi nào khác, nên nó không thể gửi bản nháp cũng không thể tiêu tốn số lệnh gọi hằng ngày của ví MultiSig của bạn. Ưu tiên một địa chỉ đi ra riêng thay vì NAT dùng chung hoặc egress đám mây: một địa chỉ bị tạm giữ hoặc bị chặn vẫn phục vụ các khóa hợp lệ của bạn, và một khóa có danh sách cho phép chứa địa chỉ đó không bị từ chối bởi giới hạn theo địa chỉ 600 mỗi phút hay 50,000 mỗi ngày, nhưng giới hạn burst và mức 200,000 mỗi ngày được chia sẻ với mọi người trên địa chỉ đó (mục 10.1).
- Mỗi hệ thống một khóa, với tên cho biết đó là hệ thống nào. Tối đa 5 khóa cho mỗi ví MultiSig.
- Xoay vòng trước khi hết hạn và khi có bất kỳ nghi ngờ nào: nhờ một thành viên tạo khóa mới, chuyển bot của bạn sang khóa đó, rồi thu hồi khóa cũ. Khóa mới phải dùng các
clientRequestIdmới (mục 6.2.2). - Khi bị lộ, hãy thu hồi ngay, trong Web Console hoặc ứng dụng Ownbit. Việc thu hồi sẽ từ chối các bản nháp chưa ai khởi chạy của khóa đó. Nếu một khóa bị lộ đã dùng hết số lệnh gọi hôm nay của ví MultiSig, khóa thay thế sẽ dùng chung hạn mức đó cho đến 00:00 UTC: hãy liên hệ bộ phận hỗ trợ của Ownbit, họ có thể nâng hạn mức của ví MultiSig đó trong ngày.
- Tắt các tác vụ dùng khóa đã bị thu hồi: các lần thất bại của chúng bị tính vào địa chỉ của bạn.
- Hiển thị
clientRequestIdvà dấu vân tay trong kênh phê duyệt của bạn; kiểm tracontentHashvà các khoản thanh toán của ví MultiSig trên blockchain (mục 8). - Gửi
symboltrên mọi dòng. - Coi văn bản từ API là dữ liệu, không bao giờ là HTML hay lệnh, trong log và dashboard của bạn.
12. Không có trong giai đoạn 1
Webhook; kết quả giao dịch theo từng dòng (mã giao dịch, hash, chữ ký và lỗi của một dòng); ví MultiSig trên các blockchain khác và các token khác; truy cập qua IPv6 và các mục IPv6 trong danh sách cho phép; giới hạn lệnh gọi theo khóa do bạn tự đặt; bản nháp được ký bằng khóa của riêng bạn. Hãy liên hệ Ownbit nếu bạn cần một trong số đó.
Cập nhật lần cuối:
Tải Ownbit
Cài ứng dụng rồi thiết lập ví lạnh hoặc đa chữ ký theo nhu cầu của bạn.