Ownbit MultiSig API v1 (เฟส 1)
ให้ระบบของคุณเองส่งรายการจ่ายเงินให้ Ownbit MultiSig ได้ คีย์ API ที่สร้างในเว็บคอนโซลใช้ส่งดราฟต์ ผู้ลงนามตรวจทุกบรรทัดแล้วเริ่มรายการบนโทรศัพท์ของตน API ไม่เคยโอนเงินเอง
เวอร์ชันวันที่ 2026-11-18 (ดราฟต์เปลี่ยนแปลงได้ด้วย lineId; ดราฟต์มีห้าสถานะ) เอกสารนี้อธิบาย API เฟส 1 คีย์ แฮช ที่อยู่ และที่อยู่ IP ทั้งหมดในเอกสารนี้เป็นตัวอย่างสมมติ (ที่อยู่ IP มาจากช่วงที่สงวนไว้สำหรับใช้ในเอกสาร) ยกเว้นที่อยู่สัญญา USDT-TRC20 ซึ่งเป็นที่อยู่จริงที่เปิดเผยต่อสาธารณะ
1. API ทำอะไรได้บ้าง
ระบบของคุณ (ต่อไปนี้เรียกว่า "บอตของคุณ") ส่งลิสต์การจ่ายเงินสำหรับกระเป๋า MultiSig ของ Ownbit หนึ่งใบ ซึ่งเรียกว่า ดราฟต์ ให้ Ownbit และภายหลังจึงอ่านผลว่าดราฟต์นั้นเป็นอย่างไร: ผู้ลงนามเริ่มดำเนินการแล้ว ถูกปฏิเสธ ถูกถอนคืน หรือหมดอายุ
API ไม่เคยเคลื่อนย้ายเงินทุน ดราฟต์จะกลายเป็นการชำระเงินก็ต่อเมื่อผู้ลงนามของ MultiSig เปิดดราฟต์นั้นในเว็บคอนโซลของ Ownbit เริ่มดำเนินการบนโทรศัพท์ของตนเอง และสมาชิกของ MultiSig ลงนามในแต่ละธุรกรรมครบจำนวน (m จาก n) ผู้ลงนามเห็นทุกรายการก่อนเริ่มดำเนินการ การตรวจสอบทุกอย่างที่ Ownbit ทำกับการชำระเงินยังคงทำงานตามปกติ และผู้ลงนามสามารถปฏิเสธดราฟต์ได้ คีย์ไม่สามารถลงนาม เริ่มการชำระเงิน อนุมัติ ปฏิเสธ หรือเปลี่ยนนโยบาย ไวท์ลิสต์ หรือสมาชิกของ MultiSig ได้
สิ่งที่คีย์ทำได้:
| การเรียก | สิทธิ์ | สิ่งที่ทำ |
|---|---|---|
GET /whoami | drafts:read | อธิบายข้อมูลของคีย์และ MultiSig ของคีย์ พร้อมจำนวนการเรียกของวันนี้ |
POST /drafts | drafts:submit | ส่งดราฟต์ (1 ถึง 500 รายการ) หรือแก้ไขดราฟต์ที่ยังไม่มีใครเริ่ม: เพิ่ม แทนที่ และลบรายการตาม lineId ของคุณ |
GET /drafts | drafts:read | แสดงดราฟต์ของคีย์นี้ เรียงจากที่เปลี่ยนแปลงเก่าสุดก่อน พร้อม cursor |
GET /drafts/{draftId} | drafts:read | อ่านดราฟต์หนึ่งฉบับพร้อมรายการของดราฟต์นั้น |
DELETE /drafts/{draftId} | drafts:submit | ถอนคืนดราฟต์ที่ยังไม่มีใครเริ่ม |
2. ขอบเขตของเฟส 1
- MultiSig บน TRON เท่านั้น รายการชำระเป็น
TRXหรือUSDT(USDT-TRC20 สัญญาTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t) ทั้งสองมีทศนิยม 6 ตำแหน่ง - IPv4 เท่านั้น เข้าถึง API ได้ผ่าน IPv4 เท่านั้น (
api.bittool.comไม่มีที่อยู่ IPv6 ในเฟส 1) และ allowlist ของคีย์เก็บช่วงที่อยู่ IPv4 - ไม่มี webhook บอตของคุณต้อง poll เอง (หัวข้อ 10 บอกว่าควรถี่แค่ไหน)
- ดราฟต์ละไม่เกิน 500 รายการ ผู้ลงนามอาจเริ่มดราฟต์ขนาดใหญ่เป็นสองคำขอบนโทรศัพท์ของตน ซึ่งไม่ทำให้อะไรเปลี่ยนแปลงสำหรับคุณ
3. Base URL และการรับส่งข้อมูล
https://api.bittool.com/ownbit/api/v1- IPv4 เท่านั้น ในเฟส 1: ชื่อโดเมนไม่มีที่อยู่ IPv6 ดังนั้นเซิร์ฟเวอร์ที่มีทั้ง IPv4 และ IPv6 จะเรียกผ่าน IPv4 และถูกตรวจสอบกับ allowlist IPv4 ของตน
- HTTPS เท่านั้น คำขอที่ไม่ได้มาทาง HTTPS จะถูกปฏิเสธด้วย
403 https_requiredและจะไม่ถูก redirect คีย์ที่เคยถูกส่งผ่าน HTTP ธรรมดาต้องถือว่ารั่วไหลแล้ว: ให้เพิกถอนและสร้างคีย์ใหม่ การตอบกลับผ่าน HTTPS มีStrict-Transport-Security: max-age=31536000 - JSON ใน UTF-8 คำขอ
POSTส่งContent-Type: application/json(มีส่วนต่อท้าย; charset=utf-8ก็ได้) body ของคำขอมีขนาดไม่เกิน 256 KiB - เวลา เป็นสตริง ISO 8601 ใน UTC พร้อมมิลลิวินาที เช่น
2026-11-17T06:00:00.000Z - ทุกการตอบกลับ มี
Cache-Control: no-store,Pragma: no-cacheและX-Request-Id(req_ตามด้วยอักขระ[0-9a-z]16 ตัว) body ของข้อผิดพลาดจะระบุค่านี้ซ้ำเป็นrequestIdโปรดแจ้งค่านี้เมื่อติดต่อฝ่ายสนับสนุน - ไม่รองรับ CORS ไม่มีหน้าเบราว์เซอร์ใดเรียก API ได้: ให้เรียกจากเซิร์ฟเวอร์ของคุณ
- คำขอเข้มงวด การตอบกลับเปิดกว้าง คำขอที่มีฟิลด์ที่ API ไม่รู้จักจะถูกปฏิเสธ (
400 invalid_request) การตอบกลับอาจมีฟิลด์ใหม่เพิ่มขึ้นในอนาคต: ให้ละเว้นฟิลด์ที่คุณไม่รู้จัก
4. คีย์
- ที่มาของคีย์ สมาชิกของ MultiSig สร้างคีย์ในเว็บคอนโซลของ Ownbit ที่แท็บ API ของ MultiSig (สมาชิกคนใดก็ได้ที่มีบทบาทผู้ลงนาม) และอนุมัติคีย์บนโทรศัพท์ของตนด้วยแอป Ownbit คีย์จะแสดงเพียงครั้งเดียว ในแท็บเบราว์เซอร์นั้น ทันทีหลังจากโทรศัพท์อนุมัติ Ownbit เก็บไว้เพียงแฮชของคีย์และไม่สามารถแสดงคีย์ได้อีก: หากคีย์สูญหาย ให้เพิกถอนและสร้างคีย์ใหม่
- รูปแบบ
obk_ตามด้วยอักขระ[0-9A-Za-z]43 ตัว (รวม 47 ตัวอักษร ความสุ่มประมาณ 256 บิต) ทุกที่ที่ Ownbit แสดงคีย์ จะแสดงเพียง 4 ตัวอักษรสุดท้ายในรูปobk_…defg - ตัวเลือกที่กำหนดตอนสร้าง ชื่อ (ไม่เกิน 30 ตัวอักษร ไม่ซ้ำกับคีย์อื่นของ MultiSig); อายุการใช้งาน 30, 90 (ค่าเริ่มต้น), 180 หรือ 365 วัน, 2 ปี หรือ 5 ปี นับจากการอนุมัติบนโทรศัพท์; allowlist IPv4 ได้สูงสุด 20 ช่วง แต่ละช่วงตั้งแต่
/8ถึง/32(ลิสต์ว่างหมายถึงที่อยู่ใดก็ได้); และจำนวนรายการชำระเงินสูงสุดที่คีย์ส่งได้ในทุกช่วง 24 ชั่วโมง (1 ถึง 10,000 ค่าเริ่มต้น 1,000) - สิทธิ์ คีย์เฟส 1 ทุกคีย์มี
drafts:submitและdrafts:read - หนึ่ง MultiSig คีย์หนึ่งครอบคลุมที่อยู่ MultiSig หนึ่งที่อยู่: TRX ของที่อยู่นั้น และ USDT ที่ที่อยู่นั้นหากมี Ownbit อาจแสดงที่อยู่เดียวเป็นหลาย MultiSig หนึ่งรายการต่อโทเคน; ทั้งหมดใช้คีย์ชุดเดียวกัน คีย์ไม่มีทางเห็นข้อมูลของ MultiSig อื่น
- ไม่เกิน 5 คีย์ ต่อ MultiSig (รวมคีย์ที่รอการอนุมัติ)
- การเพิกถอน สมาชิกคนใดก็ได้เพิกถอนคีย์ได้ทุกเมื่อ ในเว็บคอนโซลหรือในแอป Ownbit คีย์ที่ถูกเพิกถอนหรือหมดอายุจะใช้ไม่ได้ทันที การเพิกถอนคีย์ยังปฏิเสธดราฟต์ของคีย์นั้นที่ยังไม่มีใครเริ่มด้วย (เหตุผล
key_revoked); ดราฟต์ที่เริ่มแล้วจะดำเนินต่อไป - การแจ้งเตือน โทรศัพท์ของสมาชิกทุกคนจะได้รับแจ้งเมื่อคีย์ถูกอนุมัติหรือถูกเพิกถอน หากทีมของคุณเห็นการแจ้งเตือนเช่นนี้โดยไม่คาดคิด ให้เพิกถอนคีย์
5. การยืนยันตัวตน
ส่งคีย์ในทุกการเรียก และส่งใน header นี้เท่านั้น:
Authorization: Bearer obk_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefgห้ามใส่คีย์ใน URL, query string หรือ body
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_…"}ซึ่งครอบคลุม header ที่ขาดหายหรือผิดรูปแบบ คีย์ที่ไม่รู้จัก คีย์ที่ยังไม่ได้รับการอนุมัติ คีย์ที่ถูกเพิกถอนหรือหมดอายุ ที่อยู่ของผู้เรียกที่อยู่นอก allowlist ของคีย์ ผู้สร้างคีย์ที่ไม่ได้เป็นสมาชิกแล้วหรือไม่มีบทบาทผู้ลงนามแล้ว และ MultiSig ที่ไม่ได้ใช้งานอยู่แล้ว สมาชิกของ MultiSig เห็นการปฏิเสธครั้งล่าสุดของแต่ละคีย์พร้อมเหตุผลในเว็บคอนโซล ดังนั้นหากคุณไม่ทราบสาเหตุ ให้สอบถามพวกเขา - คีย์ที่ถูกต้องแต่ไม่มีสิทธิ์ที่การเรียกนั้นต้องใช้ จะได้
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: ค่าเดียวกันสำหรับคีย์ทั้งหมดของ MultiSig รวมกันcallsResetAt: เวลาที่การนับรายวันเริ่มใหม่ (หัวข้อ 10)multisig.symbols: สัญลักษณ์ที่คุณใช้ชำระได้multisig.defaultSymbol: สัญลักษณ์ที่รายการซึ่งไม่มีsymbolจะใช้ชำระ บน MultiSig ของ TRON ค่านี้คือTRXไม่ใช่USDT: ให้ส่งsymbolในทุกรายการ (หัวข้อ 6.2)requiredNumจากownerNum: จำนวนลายเซ็นที่การชำระเงินแต่ละครั้งต้องใช้
6.2 POST /drafts
การเรียกครั้งเดียวสร้างดราฟต์ และการเรียกครั้งต่อ ๆ ไปด้วย clientRequestId เดียวกันจะแก้ไขดราฟต์นั้น: เพิ่มรายการ แทนที่รายการ และลบรายการ โดยแต่ละรายการระบุด้วย lineId ของคุณเอง ดราฟต์จะเปลี่ยนแปลงได้เฉพาะขณะที่ยังไม่มีใครเริ่ม (สถานะ submitted)
คำขอ (มีเฉพาะคีย์เหล่านี้เท่านั้น สิ่งอื่นใดจะได้ 400 invalid_request):
{"clientRequestId":"payout-2026-11-17-001",
"lines":[{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001"},
{"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT"}]}การเรียกครั้งต่อมาที่เพิ่มรายการหนึ่ง แก้ไข po-1 และลบ po-2:
{"clientRequestId":"payout-2026-11-17-001",
"lines":[{"lineId":"po-3","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"0.03","symbol":"USDT"},
{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"130","symbol":"USDT","memo":"INV-1001"}],
"remove":["po-2"]}| ฟิลด์ | กฎ |
|---|---|
clientRequestId | อักขระ [A-Za-z0-9._:-] 1 ถึง 64 ตัว เป็น id ของคุณเองสำหรับลิสต์การจ่ายเงินนี้ ใช้ระบุดราฟต์หนึ่งฉบับของ MultiSig อย่างถาวร (หัวข้อ 6.2.2) |
lines | อ็อบเจกต์ 0 ถึง 500 รายการ แต่ละรายการมีเฉพาะคีย์ด้านล่าง การเรียกครั้งแรกต้องส่งอย่างน้อยหนึ่งรายการ |
remove | ไม่บังคับ lineId ของรายการที่จะนำออกจากดราฟต์ lineId ที่ดราฟต์ไม่มีจะถูกละเว้น ดังนั้นการลองใหม่จึงปลอดภัย lineId หนึ่งจะอยู่ทั้งใน lines และใน remove ไม่ได้ |
lineId | บังคับ อักขระ [A-Za-z0-9._:/-] 1 ถึง 64 ตัว เป็น id ของคุณเองสำหรับรายการ ต้องไม่ซ้ำกันภายในดราฟต์ (clientRequestId อื่นเริ่มต้นใหม่ทั้งหมด) lineId ที่ดราฟต์มีอยู่แล้วจะแทนที่รายการนั้นในตำแหน่งเดิม; ส่วน id ใหม่จะถูกเพิ่มต่อท้าย ค่านี้ส่งกลับมาให้คุณ แต่จะไม่ถูกบันทึกบนเชน และไม่แสดงให้ผู้ลงนามเห็น |
to | ที่อยู่ TRON (34 ตัวอักษร, base58check) ต้องไม่ใช่ที่อยู่ของ MultiSig เอง ไม่ใช่ที่อยู่ศูนย์ของ TRON T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb และไม่ใช่สัญญา USDT (โทเคนที่ส่งไปที่นั่นจะสูญหาย) |
amount | สตริงที่ตรงกับ ^(0|[1-9][0-9]*)(\.[0-9]+)?$ มากกว่าศูนย์ ทศนิยมไม่เกิน 6 ตำแหน่งโดยนับตามที่ส่งมา ("1.0000000" ถูกปฏิเสธด้วย amount_decimals; "80.500000" ได้รับการยอมรับและเก็บเป็น "80.5") ไม่เกิน 9223372036854775807 ในหน่วยที่เล็กที่สุด ให้ส่งเป็นสตริง ห้ามส่งเป็นตัวเลข JSON Ownbit จะเก็บในรูปแบบ canonical: ตัดศูนย์ท้ายของส่วนทศนิยมออก แล้วตัดจุดที่เหลืออยู่ลำพังออก ("80.50" กลายเป็น "80.5", "2.0" กลายเป็น "2") |
symbol | TRX หรือ USDT ส่งในทุกรายการ หากคุณละไว้ รายการนั้นจะชำระด้วย defaultSymbol ของ MultiSig ซึ่งบน MultiSig ของ TRON คือ TRX: การจ่าย USDT ที่ไม่มี symbol จะกลายเป็นการจ่าย TRX ด้วยตัวเลขเดียวกัน MultiSig ต้องมีสัญลักษณ์นั้นอยู่ (symbols ของ whoami) |
memo | ไม่บังคับ ไม่เกิน 80 ตัวอักษร; ห้ามมี , ' " \; ห้ามมีอักขระควบคุม อักขระขึ้นบรรทัดใหม่ หรืออักขระที่มองไม่เห็น; ห้ามมีช่องว่างที่ต้นหรือท้าย; ห้ามเป็นเมโมที่สงวนไว้ (ขึ้นต้นด้วย admin: มี -no-broadcast หรือลงท้ายด้วย ***br*** ไม่ว่าจะเป็นตัวพิมพ์เล็กหรือใหญ่) การไม่ส่งกับ "" มีความหมายเหมือนกัน |
Ownbit จะลบรายการใน remove ก่อน จากนั้นแทนที่หรือเพิ่มแต่ละรายการใน lines แล้วจึงตรวจสอบดราฟต์ทั้งฉบับ: ไม่เกิน 500 รายการ อย่างน้อยหนึ่งรายการ และไม่มีสองรายการที่มี to, amount แบบ canonical และ symbol เหมือนกัน (เชนจะปฏิเสธรายการที่สองเพราะซ้ำ ขณะที่รายการแรกยังรอลายเซ็น) ทุกรายการที่คุณส่งจะถูกตรวจสอบเหมือนในการเรียกครั้งแรก; หากมีสิ่งใดถูกปฏิเสธ จะไม่มีอะไรเปลี่ยนแปลง
การตอบกลับ:
| สถานะ | Body | เมื่อใด |
|---|---|---|
201 | {"draft":<draft>} | ดราฟต์ใหม่ สถานะ submitted revision 1 ทุกรายการเป็น pending |
200 | {"draft":<draft>} | ดราฟต์เปลี่ยนแปลงแล้ว (revision เพิ่มขึ้นหนึ่ง) หรือการเรียกไม่ได้เปลี่ยนแปลงอะไร (เป็นการลองใหม่): คืนดราฟต์ตามที่เป็นอยู่ในขณะนี้ |
409 not_editable | details.draftId, details.status | ดราฟต์ไม่ได้อยู่ในสถานะ submitted แล้ว (ผู้ลงนามเริ่มแล้ว หรือถูกถอนคืน ถูกปฏิเสธ หรือหมดอายุ): ไม่มีอะไรเปลี่ยนแปลง |
409 idempotency_conflict | clientRequestId นี้ถูกใช้โดยคีย์อื่นของ MultiSig เดียวกัน | |
410 gone | ดราฟต์ของ clientRequestId นี้ถูกลบไปแล้ว (ตามระยะเวลาการเก็บรักษา หัวข้อ 7.3) | |
422 invalid_lines | details.errors | มีรายการที่ไม่ถูกต้องตั้งแต่หนึ่งรายการขึ้นไป หรือดราฟต์จะว่างเปล่า; ไม่มีอะไรเปลี่ยนแปลง |
429 daily_limit | details.scope | จะเกินขีดจำกัดจำนวนรายการใน 24 ชั่วโมงของคีย์หรือของ MultiSig (หัวข้อ 10) หากมี details.neverFits: true และไม่มี Retry-After แสดงว่าการเรียกครั้งนี้เพียงครั้งเดียวมีรายการมากกว่าขีดจำกัด การรอจึงไม่ช่วยอะไร: ให้ส่งรายการต่อการเรียกให้น้อยลง |
details.errors แสดงปัญหา 50 รายการแรกในรูป {"line":<index in lines>,"lineId":"po-1","field":"amount","reason":"amount_decimals"} เหตุผล: line_id_invalid, line_id_duplicate, address_invalid, address_self, address_zero, address_contract, amount_invalid, amount_zero, amount_decimals, amount_too_large, symbol_unknown, symbol_unavailable, memo_invalid, memo_reserved, duplicate_line, draft_empty (line และ lineId เป็น null: การลบจะทำให้ไม่เหลือรายการใดเลย; ให้ถอนคืนดราฟต์แทน หัวข้อ 6.5)
6.2.1 ดราฟต์
รูปแบบเต็ม (รูปแบบในลิสต์ไม่มี lines):
{"draftId":"drf_0123456789abcdefghijklmn","clientRequestId":"payout-2026-11-17-001","status":"started","revision":1,
"createdAt":"2026-11-17T06:10:00.000Z","updatedAt":"2026-11-17T06:31:12.000Z","startedAt":"2026-11-17T06:31:12.000Z","lineCount":2,
"contentHash":"cc43baacd7df98efac68139dd9be5dba47d4fa0343c034e3fd54098409cf59a4",
"totals":[{"symbol":"USDT","amount":"205.5"}],"counts":{"started":2},"rejection":null,
"lines":[{"index":0,"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001",
"repeated":false,"state":"started"},
{"index":1,"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT","memo":"",
"repeated":false,"state":"started"}]}draftId:drf_ตามด้วยอักขระ[0-9a-z]24 ตัวrevision: 1 สำหรับดราฟต์ใหม่ และเพิ่มขึ้นหนึ่งหลังการเรียกแต่ละครั้งที่เปลี่ยนแปลงดราฟต์startedAt: เวลาที่ผู้ลงนามเริ่มดราฟต์บนโทรศัพท์ของตนเป็นครั้งแรก มิฉะนั้นเป็นnullค่านี้ไม่เปลี่ยนเมื่อผู้ลงนามเริ่มดราฟต์อีกครั้งlines[].lineId: id ของรายการที่คุณกำหนดlines[].index: ตำแหน่งปัจจุบันของรายการ นับจาก 0 (ตำแหน่งจะเลื่อนเมื่อรายการที่อยู่ก่อนหน้าถูกลบ: ให้จับคู่รายการด้วยlineId)memoเป็น""เมื่อไม่มีlines[].state: เป็นไปตามสถานะของดราฟต์เสมอ (หัวข้อ 7.2) ในเฟส 1 รายการไม่มี transaction id แฮช จำนวนลายเซ็น หรือข้อผิดพลาด: ให้ตรวจสอบการชำระเงินตามที่หัวข้อ 8 อธิบายtotals: ผลรวมแยกตามสัญลักษณ์;counts: จำนวนรายการในแต่ละสถานะ (เฉพาะสถานะที่มีรายการ)repeated:trueเมื่อดราฟต์อื่นของ MultiSig นี้ภายใน 7 วันที่ผ่านมามีรายการที่มีที่อยู่ จำนวนเงิน และสัญลักษณ์เดียวกัน ผู้ลงนามจะเห็นเครื่องหมายนี้และต้องยืนยันก่อนเริ่มดราฟต์; เมื่อคุณเห็นค่านี้ ให้ตรวจสอบระบบของคุณเองrejection:{"reason","note","at"}เมื่อดราฟต์ถูกปฏิเสธ มิฉะนั้นเป็นnullเหตุผล:whitelist,address,amount,duplicate,other(เลือกโดยผู้ลงนามในเว็บคอนโซล ซึ่งอาจเพิ่มnoteหนึ่งบรรทัด),phone(ผู้ลงนามปฏิเสธบนโทรศัพท์ของตน; ไม่มีnote) และkey_revokedAPI จะไม่บอกว่าสมาชิกคนใดเป็นผู้ปฏิเสธ
6.2.2 การลองใหม่และการแก้ไข
clientRequestIdระบุดราฟต์หนึ่งฉบับของ MultiSig อย่างถาวร: ค่านี้ถือว่าถูกใช้แล้วตลอดเวลาที่ดราฟต์ยังถูกเก็บไว้ และอีก 365 วันหลังจากดราฟต์ถูกลบ (410) เฉพาะคีย์ที่สร้างดราฟต์เท่านั้นที่แก้ไขดราฟต์ได้; คีย์อื่นของ MultiSig เดียวกันจะได้409 idempotency_conflict(หลังการหมุนเวียนคีย์ ให้ใช้ id ใหม่) ทำให้ id ของคุณไม่ซ้ำกันตลอดไป เช่น ใช้วันที่ต่อด้วยหมายเลขลำดับ- ทุกการเรียกลองใหม่ได้อย่างปลอดภัย หลังจาก timeout หรือข้อผิดพลาดของเครือข่าย ให้ส่งคำขอเดิมอีกครั้ง: รายการที่คุณส่งจะแทนที่ตัวเองด้วยเนื้อหาเดียวกัน และรายการที่ลบไปแล้วก็หายไปแล้ว ดังนั้นคำตอบคือดราฟต์ตามที่เป็นอยู่ในขณะนี้ จะไม่มีดราฟต์ฉบับที่สองหรือรายการซ้ำเกิดขึ้น
- การแก้ไขทำได้เฉพาะขณะดราฟต์อยู่ในสถานะ
submittedเมื่อผู้ลงนามเริ่มแล้ว การเรียกจะได้409 not_editable: ให้ขอให้ผู้ลงนามปฏิเสธรายการที่ต้องไม่ถูกจ่าย และส่งรายการใหม่ภายใต้clientRequestIdใหม่ - ผู้ลงนามเห็นดราฟต์ตามที่เป็นอยู่ขณะเปิด หากดราฟต์เปลี่ยนแปลงขณะที่ผู้ลงนามเปิดอยู่ คอนโซลของผู้ลงนามจะปฏิเสธการเริ่มและขอให้เปิดใหม่อีกครั้ง
- การเรียกสองครั้งพร้อมกันด้วย id เดียวกันจะถูกดำเนินการทีละครั้งตามลำดับ
6.2.3 แฮชของเนื้อหา
contentHash คือค่า SHA-256 แบบ hex ตัวพิมพ์เล็กของไบต์ UTF-8 ของอาร์เรย์ JSON แบบกระชับที่ประกอบด้วยรายการของดราฟต์ตามลำดับ แต่ละรายการเขียนเป็น {"lineId","to","amount","symbol","memo"} ตามลำดับนั้น โดยใช้จำนวนเงินแบบ canonical เขียนสัญลักษณ์ออกมาเสมอ และใช้ "" เมื่อไม่มี 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 ให้สร้างสตริงนี้ด้วยตัวเอง (ไม่จำเป็นต้องอาศัยลำดับคีย์หรือการ escape ของไลบรารี JSON ใด ๆ: ไม่มีฟิลด์ใดในนี้ที่มีอักขระที่ต้อง escape ได้) fingerprint ที่ผู้ลงนามเห็นคืออักขระ hex 16 ตัวแรกของ contentHash (ในที่นี้คือ cc43baacd7df98ef) หัวข้อ 8 อธิบายว่าควรทำอะไรกับค่าเหล่านี้
6.3 GET /drafts?since=<cursor>&limit=<n>
ดราฟต์ของคีย์นี้ เรียงตาม updatedAt แล้วตาม draftId ต่อจาก cursor (หากไม่มี since: เริ่มจากดราฟต์เก่าสุดที่ยังเก็บไว้) limit มีค่า 1 ถึง 100 ค่าเริ่มต้น 50
{"drafts":[<draft without lines>],"nextCursor":"<opaque>","hasMore":false}updatedAt ของดราฟต์จะขยับทุกครั้งที่สถานะหรือรายการของดราฟต์เปลี่ยน ดังนั้นการ poll ด้วย nextCursor ล่าสุดจะเห็นทุกการเปลี่ยนแปลง หน้าว่างจะคืน cursor ที่คุณส่งมา; ให้ใช้ cursor นั้นต่อไป cursor ที่อ่านไม่ได้จะได้ 400 invalid_request
6.4 GET /drafts/{draftId}
200 {"draft":<draft>} ดราฟต์ของคีย์อื่น (แม้จะเป็นของ MultiSig เดียวกัน) หรือดราฟต์ที่ไม่ได้เก็บไว้แล้ว: 404 not_found
6.5 DELETE /drafts/{draftId}
ถอนคืนดราฟต์ที่ยังไม่มีใครเริ่ม ทำได้เฉพาะขณะที่สถานะเป็น submitted: ทุกรายการจะกลายเป็น withdrawn, 200 {"draft":<draft>} หากเป็น withdrawn อยู่แล้ว: ได้ 200 อีกครั้ง กรณีอื่นจะได้ 409 not_withdrawable พร้อม details.status เมื่อผู้ลงนามเริ่มดราฟต์แล้ว ให้ขอให้ผู้ลงนามปฏิเสธส่วนที่เหลือแทน
7. สถานะ
7.1 status ของดราฟต์
| สถานะ | ความหมาย |
|---|---|
submitted | ยังไม่มีใครเริ่ม เฉพาะในสถานะนี้เท่านั้นที่บอตของคุณแก้ไขได้ (หัวข้อ 6.2) หรือถอนคืนได้ (หัวข้อ 6.5) |
started | ผู้ลงนามเริ่มดราฟต์บนโทรศัพท์ของตนแล้ว (startedAt บอกว่าเกิดขึ้นครั้งแรกเมื่อใด) ผู้ลงนามอาจเปิดและเริ่มอีกครั้งได้ เช่น หลังจากโทรศัพท์หยุดทำงานกลางคัน; สถานะยังคงเป็น started |
rejected | ผู้ลงนามปฏิเสธดราฟต์ ในเว็บคอนโซลหรือบนโทรศัพท์ของตน (ก่อนหรือหลังเริ่มก็ได้) หรือคีย์ของดราฟต์ถูกเพิกถอนก่อนที่จะมีใครเริ่ม rejection บอกเหตุผล |
withdrawn | บอตของคุณถอนคืนดราฟต์ |
expired | ไม่มีใครเริ่มภายใน 7 วัน |
Ownbit รายงานเฉพาะสิ่งที่รู้แน่ชัด: ผู้ลงนามได้เริ่มดราฟต์บนโทรศัพท์ของตนแล้ว Ownbit ไม่ทราบว่ามีการชำระเงินใดตามมาบ้าง ดังนั้นดราฟต์ที่เป็น started อาจถูกจ่ายครบ จ่ายบางส่วน หรือไม่ถูกจ่ายเลย การชำระเงินคือธุรกรรมของ MultiSig: ให้ตรวจสอบตามที่หัวข้อ 8 อธิบาย และอย่าส่งรายการของดราฟต์ที่เริ่มแล้วซ้ำ เว้นแต่ผู้ลงนามจะแจ้งว่ารายการเหล่านั้นไม่ได้ถูกจ่าย
7.2 state ของรายการ
state ของรายการจะเหมือนกับสถานะของดราฟต์เสมอ: ในเฟส 1 Ownbit ไม่ได้ติดตามธุรกรรมของแต่ละรายการ
| สถานะ | ความหมาย |
|---|---|
pending | ดราฟต์อยู่ในสถานะ submitted |
started | ดราฟต์อยู่ในสถานะ started |
rejected, withdrawn, expired | สถานะของดราฟต์ |
7.3 อายุการเก็บรักษา
ดราฟต์ที่ไม่มีใครเริ่มจะหมดอายุหลัง 7 วัน ดราฟต์ที่เริ่มแล้วจะคงสถานะ started จนกว่าผู้ลงนามจะปฏิเสธ ดราฟต์ที่ถูกปฏิเสธ ถูกถอนคืน และหมดอายุจะถูกเก็บไว้ 30 วันหลังสิ้นสุด และดราฟต์ที่เริ่มแล้วจะถูกเก็บไว้ 30 วันหลังการเปลี่ยนแปลงครั้งล่าสุด; จากนั้นจะถูกลบ (GET จะตอบ 404; clientRequestId เดิมจะตอบ 410 ต่อไปอีก 365 วัน)
8. การตรวจสอบสิ่งที่ถูกจ่าย
Ownbit นำลิสต์ของคุณจากบอตของคุณไปยังหน้าจอของผู้ลงนาม เพื่อให้แน่ใจว่าไม่มีอะไรเปลี่ยนไประหว่างทาง:
- แสดง
clientRequestIdและ fingerprint (อักขระ hex 16 ตัวแรกของcontentHash) ในช่องทางอนุมัติของคุณเอง ข้างลิสต์การจ่ายเงินที่อนุมัติแล้ว ดราฟต์ที่คุณแก้ไขจะมี fingerprint ใหม่: ให้แสดงค่าล่าสุด ผู้ลงนามเห็นทั้งสองค่าในเว็บคอนโซล ซึ่งเบราว์เซอร์ของพวกเขาคำนวณใหม่จากรายการที่กำลังจะเริ่ม และจะถูกขอให้เปรียบเทียบกับบันทึกของคุณ การเปรียบเทียบนี้ทำได้ก็ต่อเมื่อบันทึกการอนุมัติของคุณแสดงค่าทั้งสอง - คำนวณ
contentHashใหม่ (หัวข้อ 6.2.3) จากรายการของทุกดราฟต์ที่คุณอ่าน และเปรียบเทียบกับค่าที่คุณคำนวณไว้สำหรับ revision ล่าสุดของดราฟต์ - ตรวจสอบการชำระเงินของ MultiSig บนเชนด้วยตนเอง ในเฟส 1 Ownbit ไม่รายงานธุรกรรมของแต่ละรายการ เมื่อดราฟต์เป็น
startedแล้ว ให้เปรียบเทียบรายการของดราฟต์กับธุรกรรมขาออกของที่อยู่ MultiSig (multisig.addressของwhoami): ผู้รับ จำนวนเงิน และโทเคนของการชำระเงินทุกครั้งต้องตรงกับรายการใดรายการหนึ่งของคุณ และแต่ละรายการควรถูกจ่ายไม่เกินหนึ่งครั้ง - เฝ้าดู
repeated: รายการที่ซ้ำกับรายการในดราฟต์อื่นเมื่อเร็ว ๆ นี้จะถูกทำเครื่องหมายให้ผู้ลงนามเห็น; ควรทำเครื่องหมายในระบบของคุณด้วย - บน Enterprise MultiSig ให้ขอให้สมาชิกเปิด ไวท์ลิสต์ และ วงเงินรายวัน: เมื่อนั้นแม้ดราฟต์ที่ผิดพลาดก็ไม่สามารถจ่ายไปยังที่อยู่ที่ไม่รู้จักหรือจ่ายเกินวงเงินได้ MultiSig แบบอื่นไม่มีไวท์ลิสต์ ดังนั้นการตรวจสอบของผู้ลงนามจึงเป็นการตรวจสอบเพียงอย่างเดียว
9. ข้อผิดพลาด
ข้อผิดพลาดทุกรายการมี body ดังนี้:
{"error":{"code":"<code>","message":"<English sentence>","details":{}},"requestId":"req_0123456789abcdef"}message คือประโยคภาษาอังกฤษที่ตายตัวสำหรับคนอ่าน; ให้เขียนโปรแกรมโดยอิงกับ code และ details ข้อความจะไม่สะท้อนข้อมูลที่คุณส่งมา
| HTTP | code | เมื่อใด |
|---|---|---|
| 400 | invalid_request | ไม่ใช่ JSON, ชนิดข้อมูลผิด, ฟิลด์ที่ไม่รู้จัก, clientRequestId ไม่ถูกต้อง, ไม่มีรายการหรือมีมากกว่า 500 รายการ, cursor หรือ limit ไม่ถูกต้อง, body ของคำขอที่มาไม่ครบภายใน 10 วินาที |
| 401 | unauthorized | ปัญหาเกี่ยวกับคีย์ใด ๆ (หัวข้อ 5) |
| 403 | forbidden | คีย์ที่ถูกต้องแต่ไม่มีสิทธิ์สำหรับการเรียกนั้น |
| 403 | https_required | คำขอไม่ได้มาทาง HTTPS (ให้เพิกถอนคีย์ที่แนบมากับคำขอ) |
| 404 | not_found | path ที่ไม่รู้จัก; ดราฟต์ที่ไม่ใช่ของคีย์นี้ หรือไม่ได้เก็บไว้แล้ว |
| 405 | method_not_allowed | method ที่ path นั้นไม่รองรับ (รวมถึง 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 | body ที่ใหญ่กว่า 256 KiB |
| 415 | unsupported_media_type | POST ที่ไม่ใช่ JSON |
| 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 ที่มี scope edge หรือ 413 ที่มาจากชั้นป้องกันซึ่งอยู่หน้า API จะมีรูปแบบเดียวกันโดยมี "requestId":null
10. ขีดจำกัดอัตราการเรียกและเพดานรายวัน
10.1 ขีดจำกัด
| ขีดจำกัด | ค่า | details.scope | code |
|---|---|---|---|
| คำขอจากที่อยู่หนึ่ง, burst | 20 ครั้งต่อวินาที (burst ได้ถึง 40), การเชื่อมต่อที่เปิดอยู่ 20 รายการ | edge | rate_limited |
| การเรียกต่อคีย์ | 10 ครั้งต่อวินาที | key_second | rate_limited |
| การเรียกต่อคีย์ | 300 ครั้งต่อนาที | key_minute | rate_limited |
POST /drafts ต่อคีย์ | 60 ครั้งต่อชั่วโมง | key_submit_hour | rate_limited |
| การเรียกที่ดำเนินอยู่พร้อมกัน ต่อคีย์ | 2 | key_concurrent | rate_limited |
| การเรียกที่ดำเนินอยู่พร้อมกัน ต่อ MultiSig (ทุกคีย์ของ MultiSig) | 4 | multisig_concurrent | rate_limited |
| การเรียกต่อที่อยู่ (คีย์ที่ถูกต้อง) | 600 ครั้งต่อนาที; ไม่ปฏิเสธคีย์ที่ allowlist ไม่ว่างและมีที่อยู่นี้อยู่ | ip_minute | rate_limited |
| การเรียกต่อคีย์ | 10,000 ครั้งต่อวัน | key_day | rate_limited |
| การเรียกต่อ MultiSig (ทุกคีย์รวมกัน) | 20,000 ครั้งต่อวัน | multisig_day | rate_limited |
| การเรียกต่อที่อยู่ (คีย์ที่ถูกต้อง) | 50,000 ครั้งต่อวัน; ไม่ปฏิเสธคีย์ที่ allowlist ไม่ว่างและมีที่อยู่นี้อยู่ | ip_day | rate_limited |
| การเรียกต่อที่อยู่ (คีย์ที่ถูกต้อง), เพดานตายตัว | 200,000 ครั้งต่อวัน สำหรับทุกคีย์ | ip_day (details.limit 200000) | rate_limited |
| การเรียกที่ล้มเหลวต่อที่อยู่ | 20 ครั้งต่อนาที; หากเกิน ที่อยู่จะถูกพักไว้ 10 นาที | ip_failures | rate_limited |
| การเรียกที่ล้มเหลวต่อที่อยู่ | 200 ครั้งต่อวัน; หากเกิน ที่อยู่จะถูกบล็อก 24 ชั่วโมง | ip_blocked | rate_limited |
| การเรียกที่ล้มเหลวต่อเครือข่าย (/24) | 1,000 ครั้งต่อวัน; หากเกิน เครือข่ายจะถูกบล็อก 24 ชั่วโมง | net_blocked | rate_limited |
| รายการชำระเงินต่อคีย์ | ขีดจำกัดของคีย์เอง (1 ถึง 10,000 ค่าเริ่มต้น 1,000) ในทุกช่วง 24 ชั่วโมง | key_lines_24h | daily_limit |
| รายการชำระเงินต่อ MultiSig | 10,000 ในทุกช่วง 24 ชั่วโมง | multisig_lines_24h | daily_limit |
| API ทั้งระบบไม่ว่าง | (เพื่อปกป้องบริการ) | api_busy (HTTP 503) | unavailable |
- หนึ่งวันคือวันตามปฏิทิน UTC: เพดานการเรียกและเพดานความล้มเหลวเริ่มนับใหม่ที่ 00:00 UTC (08:00 เวลาปักกิ่ง) ขีดจำกัดจำนวนรายการทั้งสองแบบเป็นแบบ rolling: ช่วง 24 ชั่วโมงใดก็ได้
- สิ่งที่ถูกนับ ทุกการเรียกที่ใช้คีย์ที่ถูกต้องจะถูกนับรวมในขีดจำกัดของคีย์ MultiSig และที่อยู่: รวมถึงการอ่าน การเรียกที่ถูกปฏิเสธหลังจากคีย์ได้รับการยอมรับแล้ว (
403,404,409,422หรือ429จากขีดจำกัดจำนวนรายการ) และPOST /draftsที่ส่งซ้ำ การเรียกที่ถูกปฏิเสธโดย rate limit หรือเพดานจะไม่ถูกนับในขีดจำกัดใดเลย ดังนั้นการรอจนครบRetry-Afterจะได้ผลเสมอ การเรียกที่คีย์ถูกปฏิเสธ (401) จะนับเฉพาะในการเรียกที่ล้มเหลวของที่อยู่และเครือข่ายของการเรียกนั้น - ที่อยู่หรือเครือข่ายที่ถูกพักหรือถูกบล็อก (พักไว้ 10 นาที หรือบล็อก 24 ชั่วโมง) ยังคงให้บริการทุกคีย์ที่ถูกต้องและมี allowlist ที่อนุญาตที่อยู่นั้น (allowlist ว่างอนุญาตทุกที่อยู่) เฉพาะการเรียกด้วยคีย์ที่ไม่ถูกต้อง และคีย์ที่ allowlist ไม่อนุญาตที่อยู่นั้นเท่านั้นที่ถูกปฏิเสธที่นั่น ดังนั้นคีย์ที่ถูกต้องจะไม่ถูกล็อกเพราะความล้มเหลวของผู้อื่นจากที่อยู่เดียวกัน
- ขีดจำกัดต่อที่อยู่ใช้ร่วมกับทุกคนที่เรียกจากที่อยู่นั้น คีย์ที่ allowlist ไม่ว่างและมีที่อยู่นั้นจะไม่ถูกปฏิเสธโดยขีดจำกัด 600 ครั้งต่อนาทีหรือ 50,000 ครั้งต่อวัน แต่ขีดจำกัด burst (20 ครั้งต่อวินาที) และเพดานตายตัว (200,000 ครั้งต่อวัน) นับทุกคนบนที่อยู่นั้น ดังนั้นบน NAT ที่ใช้ร่วมกัน, CI runner หรือ cloud egress ผู้อื่นยังอาจทำให้การเรียกของคุณช้าลงได้; และ
429ที่มี scopeip_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"}และ header Retry-After: 31260: จำนวนวินาทีเต็มที่ต้องรอ (อย่างน้อย 1) ค่านี้นับไปจนสิ้นสุดหน้าต่างเวลา การพัก หรือการบล็อก; จนถึง 00:00 UTC สำหรับเพดานการเรียกรายวัน; สำหรับขีดจำกัดจำนวนรายการ จนกว่ารายการเก่าสุดของคุณจะพ้นช่วง 24 ชั่วโมงมากพอ (อย่างน้อย 60 วินาที); 1 สำหรับ edge และ scope _concurrent ทั้งสอง; สำหรับ 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 Header
ทุกการตอบกลับของการเรียกที่คีย์ได้รับการยอมรับ (ทั้งที่สำเร็จ ข้อผิดพลาดที่เกิดหลังจากนั้น และ 429 ของการเรียกนั้น) จะมี:
| Header | ค่า |
|---|---|
X-RateLimit-Limit | เพดานการเรียกรายวันของคีย์ (10000) |
X-RateLimit-Remaining | จำนวนที่เหลือของวันนี้หลังการเรียกครั้งนี้: ค่าที่น้อยกว่าระหว่างจำนวนที่คีย์และ MultiSig ของคีย์เหลืออยู่ |
X-RateLimit-Reset | 00:00 UTC ถัดไป เป็น Unix seconds (ในวันที่ 2026-11-17: 1794960000) |
401, 429 ของ edge, ip_failures, ip_blocked หรือ net_blocked และ 503 จะไม่มี header เหล่านี้ GET /whoami ให้จำนวนเดียวกันใน body (callsToday, multisigCallsToday, callsResetAt)
10.4 วิธี poll และ back off สำหรับบอตที่ทำงานอย่างเหมาะสม
- poll
GET /drafts?since=<last nextCursor>ทุก 30 วินาที โดยมี poller หนึ่งตัวต่อคีย์ คิดเป็น 2,880 การเรียกต่อวัน หากบอตของคุณหลายอินสแตนซ์ใช้คีย์ร่วมกัน ให้มีเพียงอินสแตนซ์เดียวที่ poll และแบ่งปันสิ่งที่อ่านได้ เก็บnextCursorล่าสุดไว้แม้รีสตาร์ต; หน้าว่างจะคืนค่าเดิมโดยไม่เปลี่ยน เมื่อhasMoreเป็นtrueให้อ่านหน้าถัดไปทันที - อย่า poll ถี่เกินกว่างบประมาณจะรองรับ: ไม่เกินหนึ่งครั้งทุก 86,400 × 2 /
X-RateLimit-Limitวินาที (17.3 วินาทีเมื่อใช้ค่าเริ่มต้น 10,000) เพื่อให้การ poll ใช้การเรียกไม่เกินครึ่งหนึ่งของวัน การ poll ทุก 10 วินาทีอย่างเดียวใช้ 8,640 การเรียก และเหลือประมาณ 1,300 สำหรับทุกอย่างที่เหลือ; บอตสองอินสแตนซ์ที่ทำเช่นนั้นบนคีย์เดียวจะถูกปฏิเสธก่อนสิ้นวัน - อ่านดราฟต์เดี่ยวเฉพาะเมื่อคุณต้องการรายการของดราฟต์นั้น กล่าวคือเมื่อ
updatedAtของดราฟต์ขยับในลิสต์ และไม่เกินหนึ่งครั้งต่อนาทีต่อดราฟต์ อย่า poll ทุกดราฟต์แยกกัน - เฝ้าดู
X-RateLimit-Remainingเมื่อค่าลดลงต่ำกว่าหนึ่งในสิบของX-RateLimit-Limitให้ poll ห่างขึ้น จำไว้ว่าค่านี้ใช้ร่วมกับคีย์อื่นของ MultiSig - เมื่อได้
429: รอRetry-Afterวินาที บวกการหน่วงเวลาสุ่มเล็กน้อย แล้วจึงลองใหม่ อย่าลองใหม่ก่อนหน้านั้น: คำตอบจะเหมือนเดิม เมื่อเป็นkey_dayหรือmultisig_dayให้เก็บ cursor ไว้และทำงานต่อหลังX-RateLimit-Reset - เมื่อได้
503: หากมีRetry-Afterให้รอตามนั้นบวกเวลาสุ่ม 0 ถึง 30 วินาที; หากไม่มี ให้ back off แบบ exponential ตั้งแต่ 30 วินาทีจนถึง 10 นาที - เมื่อเกิดข้อผิดพลาดของเครือข่ายหรือ
500ระหว่างPOST /drafts: ส่งคำขอเดิมอีกครั้งด้วยclientRequestIdเดิม (หัวข้อ 6.2.2) หลังจาก back off ตามข้างต้น - เมื่อได้
401: หยุดใช้คีย์และแจ้งเตือนให้คนเข้ามาดู การลองใหม่กับคีย์ที่ถูกปฏิเสธไม่เคยช่วย และความล้มเหลวมากกว่า 200 ครั้งในหนึ่งวันจะทำให้ที่อยู่ของคุณถูกบล็อก 24 ชั่วโมงสำหรับทุกคีย์ที่ไม่ถูกต้อง (คีย์ที่ถูกต้องของคุณยังทำงานจากที่อยู่นั้นได้ หัวข้อ 10.1) - วางแผนสำหรับเที่ยงคืน UTC: คีย์หรือ MultiSig ที่ใช้การเรียกของวันหมดแล้วจะถูกปฏิเสธจนถึง 00:00 UTC จากนั้นให้ทำงานต่อหลังเวลาสุ่ม 0 ถึง 30 วินาที ไม่ใช่ตรงวินาทีนั้นพอดี
11. คำแนะนำด้านความปลอดภัย
- HTTPS เท่านั้น ห้ามส่งคีย์ผ่าน HTTP ธรรมดา; หากเกิดขึ้นแล้ว ให้เพิกถอนคีย์ ตรวจสอบใบรับรองของเซิร์ฟเวอร์ตามปกติ
- เก็บคีย์ไว้บนเซิร์ฟเวอร์ของคุณ ใน secret store ห้ามเก็บในเบราว์เซอร์ แอปมือถือ repository บรรทัด log, URL, ticket หรือข้อความแชท Ownbit ไม่เคยขอคีย์จากคุณ
- กำหนด allowlist IPv4 ให้ทุกคีย์ โดยใช้ที่อยู่ขาออกแบบคงที่ของเซิร์ฟเวอร์ของคุณ เมื่อนั้นคีย์ที่รั่วไหลจะไม่สามารถใช้จากที่อื่นได้ จึงไม่สามารถส่งดราฟต์หรือใช้การเรียกรายวันของ MultiSig ของคุณได้ ควรใช้ที่อยู่ขาออกเฉพาะแทน NAT ที่ใช้ร่วมกันหรือ cloud egress: ที่อยู่ที่ถูกพักหรือถูกบล็อกยังคงให้บริการคีย์ที่ถูกต้องของคุณ และคีย์ที่ allowlist มีที่อยู่นั้นจะไม่ถูกปฏิเสธโดยขีดจำกัดต่อที่อยู่ 600 ครั้งต่อนาทีหรือ 50,000 ครั้งต่อวัน แต่ขีดจำกัด burst และ 200,000 ครั้งต่อวันใช้ร่วมกับทุกคนบนที่อยู่นั้น (หัวข้อ 10.1)
- หนึ่งคีย์ต่อหนึ่งระบบ โดยตั้งชื่อที่บอกว่าเป็นระบบใด ไม่เกิน 5 คีย์ต่อ MultiSig
- หมุนเวียนคีย์ก่อนหมดอายุและเมื่อมีข้อสงสัยใด ๆ: ให้สมาชิกสร้างคีย์ใหม่ เปลี่ยนบอตของคุณไปใช้คีย์นั้น แล้วเพิกถอนคีย์เก่า คีย์ใหม่ต้องใช้
clientRequestIdใหม่ (หัวข้อ 6.2.2) - เมื่อคีย์รั่วไหล ให้เพิกถอนทันที ในเว็บคอนโซลหรือแอป Ownbit การเพิกถอนจะปฏิเสธดราฟต์ของคีย์ที่ยังไม่มีใครเริ่ม หากคีย์ที่รั่วไหลใช้การเรียกของ MultiSig ของคุณสำหรับวันนี้จนหมด คีย์ทดแทนจะใช้เพดานเดียวกันนั้นจนถึง 00:00 UTC: ให้ติดต่อฝ่ายสนับสนุนของ Ownbit ซึ่งสามารถเพิ่มเพดานของ MultiSig นั้นสำหรับวันนั้นได้
- ปิดงานที่ใช้คีย์ที่ถูกเพิกถอนแล้ว: ความล้มเหลวของงานเหล่านั้นจะถูกนับรวมกับที่อยู่ของคุณ
- แสดง
clientRequestIdและ fingerprint ในช่องทางอนุมัติของคุณ; ตรวจสอบcontentHashและการชำระเงินของ MultiSig บนเชน (หัวข้อ 8) - ส่ง
symbolในทุกรายการ - ถือว่าข้อความจาก API เป็นข้อมูล ไม่ใช่ HTML หรือคำสั่ง ใน log และแดชบอร์ดของคุณ
12. สิ่งที่ไม่มีในเฟส 1
Webhook; ผลลัพธ์ธุรกรรมรายรายการ (transaction id แฮช ลายเซ็น และข้อผิดพลาดของรายการ); MultiSig บนเชนอื่นและโทเคนอื่น; การเข้าถึงผ่าน IPv6 และรายการ IPv6 ใน allowlist; ขีดจำกัดการเรียกต่อคีย์ที่คุณกำหนดเอง; ดราฟต์ที่ลงนามด้วยคีย์ของคุณเอง หากคุณต้องการสิ่งใดในนี้ โปรดสอบถาม Ownbit
อัปเดตล่าสุด:
ดาวน์โหลด Ownbit
ติดตั้งแอป แล้วตั้งค่ากระเป๋าเย็นหรือมัลติซิกตามที่คุณต้องการ