Referenz

Ownbit MultiSig API v1 (Phase 1)

Lassen Sie Ihr eigenes System Auszahlungslisten an ein Ownbit-Multisig übergeben. Ein API-Schlüssel aus der Web-Konsole reicht Entwürfe ein; die Unterzeichner prüfen jede Zeile und starten sie auf ihrem Telefon. Die API bewegt niemals Gelder.

Stand vom 2026-11-18 (Entwürfe werden über lineId geändert; fünf Entwurfsstatus). Dieses Dokument beschreibt Phase 1 der API. Alle Schlüssel, Hashes, Adressen und IP-Adressen darin sind erfundene Beispiele (die IP-Adressen stammen aus den für Dokumentation reservierten Bereichen); die Vertragsadresse von USDT-TRC20 ist die echte, öffentliche.

1. Was die API tut

Ihr System (im Folgenden „Ihr Bot“) übergibt Ownbit eine Liste von Auszahlungen für ein Ownbit-Multisig, einen Entwurf, und liest später nach, was daraus geworden ist: von einem Unterzeichner gestartet, abgelehnt, zurückgezogen oder abgelaufen.

Die API bewegt niemals Gelder. Ein Entwurf wird erst dann zu Zahlungen, wenn ein Unterzeichner des Multisigs ihn in der Ownbit-Web-Konsole öffnet, ihn auf seinem eigenen Telefon startet und genügend Mitglieder des Multisigs jede Transaktion signieren (m von n). Unterzeichner sehen jede Zeile, bevor sie den Entwurf starten, jede Prüfung, die Ownbit bei einer Zahlung vornimmt, läuft weiterhin, und ein Unterzeichner kann einen Entwurf ablehnen. Ein Schlüssel kann weder signieren noch eine Zahlung starten, genehmigen, ablehnen oder die Richtlinie, die Whitelist oder die Mitglieder des Multisigs ändern.

Was ein Schlüssel tun kann:

AufrufBerechtigungWas er tut
GET /whoamidrafts:readBeschreibt den Schlüssel und sein Multisig, mit den heutigen Aufrufzählern
POST /draftsdrafts:submitReicht einen Entwurf ein (1 bis 500 Zeilen) oder ändert einen, den noch niemand gestartet hat: fügt Zeilen über Ihre lineId hinzu, ersetzt und entfernt sie
GET /draftsdrafts:readListet die Entwürfe dieses Schlüssels auf, älteste Änderung zuerst, mit einem Cursor
GET /drafts/{draftId}drafts:readLiest einen Entwurf mit seinen Zeilen
DELETE /drafts/{draftId}drafts:submitZieht einen Entwurf zurück, den noch niemand gestartet hat

2. Umfang von Phase 1

  • Nur Multisigs auf TRON. Zeilen zahlen in TRX oder USDT (USDT-TRC20, Vertrag TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t); beide haben 6 Dezimalstellen.
  • Nur IPv4. Die API ist nur über IPv4 erreichbar (api.bittool.com hat in Phase 1 keine IPv6-Adresse), und die Allowlist eines Schlüssels enthält IPv4-Bereiche.
  • Keine Webhooks. Ihr Bot fragt regelmäßig ab (Abschnitt 10 sagt, wie oft).
  • Höchstens 500 Zeilen pro Entwurf. Ein Unterzeichner kann einen großen Entwurf auf seinem Telefon als zwei Anfragen starten; für Sie ändert das nichts.

3. Basis-URL und Transport

https://api.bittool.com/ownbit/api/v1
  • Nur IPv4 in Phase 1: Der Name hat keine IPv6-Adresse, daher ruft ein Server mit IPv4 und IPv6 über IPv4 auf und wird mit seiner IPv4-Allowlist abgeglichen.
  • Nur HTTPS. Eine Anfrage, die nicht über HTTPS eintrifft, wird mit 403 https_required abgewiesen und niemals umgeleitet. Ein Schlüssel, der über unverschlüsseltes HTTP gesendet wurde, muss als kompromittiert gelten: Widerrufen Sie ihn und erstellen Sie einen neuen. HTTPS-Antworten enthalten Strict-Transport-Security: max-age=31536000.
  • JSON in UTF-8. POST-Anfragen senden Content-Type: application/json (ein Suffix ; charset=utf-8 ist zulässig). Ein Anfrage-Body ist höchstens 256 KiB groß.
  • Zeitangaben sind ISO-8601-Zeichenketten in UTC mit Millisekunden, zum Beispiel 2026-11-17T06:00:00.000Z.
  • Jede Antwort enthält Cache-Control: no-store, Pragma: no-cache und X-Request-Id (req_ gefolgt von 16 Zeichen aus [0-9a-z]). Der Body von Fehlerantworten wiederholt sie als requestId. Geben Sie sie an, wenn Sie den Support kontaktieren.
  • Kein CORS. Keine Browserseite kann die API aufrufen: Rufen Sie sie von Ihrem Server aus auf.
  • Strenge Anfragen, offene Antworten. Eine Anfrage mit einem Feld, das die API nicht kennt, wird abgewiesen (400 invalid_request). Antworten können mit der Zeit neue Felder erhalten: Ignorieren Sie Felder, die Sie nicht kennen.

4. Schlüssel

  • Woher sie kommen. Ein Mitglied des Multisigs erstellt einen Schlüssel in der Ownbit-Web-Konsole auf dem API-Tab des Multisigs (jedes Mitglied mit der Unterzeichnerrolle kann das) und autorisiert ihn auf seinem Telefon mit der Ownbit-App. Der Schlüssel wird einmal angezeigt, in diesem Browser-Tab, direkt nachdem das Telefon ihn autorisiert hat. Ownbit speichert nur einen Hash davon und kann ihn nicht erneut anzeigen: Geht er verloren, widerrufen Sie ihn und erstellen Sie einen neuen.
  • Format. obk_ gefolgt von 43 Zeichen aus [0-9A-Za-z] (insgesamt 47 Zeichen, etwa 256 Bit Zufälligkeit). Überall, wo Ownbit einen Schlüssel anzeigt, zeigt es nur dessen letzte 4 Zeichen, als obk_…defg.
  • Bei der Erstellung gewählte Optionen. Ein Name (höchstens 30 Zeichen, eindeutig unter den Schlüsseln des Multisigs); eine Gültigkeit von 30, 90 (Standard), 180 oder 365 Tagen, 2 Jahren oder 5 Jahren, gerechnet ab der Autorisierung auf dem Telefon; eine IPv4-Allowlist mit bis zu 20 Bereichen, jeweils von /8 bis /32 (eine leere Liste bedeutet jede Adresse); und die maximale Anzahl an Zahlungszeilen, die der Schlüssel innerhalb beliebiger 24 Stunden einreichen darf (1 bis 10.000, Standard 1.000).
  • Berechtigungen. Jeder Schlüssel in Phase 1 hat drafts:submit und drafts:read.
  • Ein Multisig. Ein Schlüssel gilt für eine Multisig-Adresse: deren TRX und, sofern vorhanden, deren USDT an dieser Adresse. Ownbit kann eine Adresse als mehrere Multisigs aufführen, eines pro Token; sie teilen sich dieselben Schlüssel. Ein Schlüssel sieht niemals die Daten eines anderen Multisigs.
  • Höchstens 5 Schlüssel pro Multisig (ausstehende eingeschlossen).
  • Widerruf. Jedes Mitglied kann einen Schlüssel jederzeit widerrufen, in der Web-Konsole oder in der Ownbit-App. Ein widerrufener oder abgelaufener Schlüssel schlägt sofort fehl. Der Widerruf eines Schlüssels lehnt außerdem dessen Entwürfe ab, die noch niemand gestartet hat (Grund key_revoked); bereits gestartete Entwürfe laufen weiter.
  • Benachrichtigungen. Das Telefon jedes Mitglieds wird benachrichtigt, wenn ein Schlüssel autorisiert oder widerrufen wird. Wenn Ihr Team eine solche Meldung sieht, die es nicht erwartet hat, widerrufen Sie den Schlüssel.

5. Authentifizierung

Senden Sie den Schlüssel bei jedem Aufruf, und zwar nur in diesem Header:

Authorization: Bearer obk_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefg

Setzen Sie einen Schlüssel niemals in eine URL, einen Query-String oder einen Body.

curl -sS https://api.bittool.com/ownbit/api/v1/whoami \
  -H "Authorization: Bearer $OWNBIT_API_KEY"
  • Jedes Schlüsselproblem erhält dieselbe Antwort: 401 {"error":{"code":"unauthorized","message":"Invalid or unusable API key"},"requestId":"req_…"}. Das umfasst einen fehlenden oder fehlerhaften Header, einen unbekannten Schlüssel, einen noch nicht autorisierten Schlüssel, einen widerrufenen oder abgelaufenen Schlüssel, eine Aufruferadresse außerhalb der Allowlist des Schlüssels, einen Ersteller, der kein Mitglied mehr ist oder die Unterzeichnerrolle nicht mehr hat, und ein Multisig, das nicht mehr aktiv ist. Die Mitglieder des Multisigs sehen in der Web-Konsole die letzte Abweisung jedes Schlüssels und deren Grund; fragen Sie sie also, wenn Sie nicht erkennen können, warum.
  • Ein gültiger Schlüssel ohne die Berechtigung, die ein Aufruf benötigt, erhält 403 forbidden.
  • Ein 401 verschwindet nicht durch erneute Versuche. Hören Sie auf und lassen Sie eine Person nachsehen (Abschnitt 10.4: wiederholte Fehlschläge sperren Ihre Adresse).

6. Aufrufe

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: das Zeilenlimit des Schlüssels und die Zeilen, die er in den letzten 24 Stunden eingereicht hat.
  • callsToday, dailyCalls: die seit 00:00 UTC gezählten Aufrufe dieses Schlüssels (dieser Aufruf eingeschlossen) und seine tägliche Aufrufobergrenze. multisigCallsToday, multisigDailyCalls: dasselbe für alle Schlüssel des Multisigs zusammen. callsResetAt: wann die Tageszähler neu beginnen (Abschnitt 10).
  • multisig.symbols: die Symbole, in denen Sie zahlen können. multisig.defaultSymbol: das Symbol, in dem eine Zeile ohne symbol zahlt. Bei einem TRON-Multisig ist das TRX, nicht USDT: Senden Sie symbol in jeder Zeile mit (Abschnitt 6.2).
  • requiredNum von ownerNum: die Signaturen, die jede Zahlung benötigt.

6.2 POST /drafts

Ein Aufruf erstellt einen Entwurf, und spätere Aufrufe mit derselben clientRequestId ändern ihn: Diese fügen Zeilen hinzu, ersetzen Zeilen und entfernen Zeilen, wobei jede Zeile über Ihre eigene lineId benannt wird. Ein Entwurf kann nur geändert werden, solange ihn noch niemand gestartet hat (Status submitted).

Anfrage (genau diese Felder; alles andere ergibt 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"}]}

Ein späterer Aufruf, der eine Zeile hinzufügt, po-1 ändert und po-2 entfernt:

{"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"]}
FeldRegel
clientRequestId1 bis 64 Zeichen aus [A-Za-z0-9._:-], Ihre eigene ID für diese Auszahlungsliste. Sie benennt einen Entwurf des Multisigs, und zwar dauerhaft (Abschnitt 6.2.2)
lines0 bis 500 Objekte, jedes nur mit den unten aufgeführten Feldern. Der erste Aufruf muss mindestens eines senden
removeOptional. Die lineIds der Zeilen, die aus dem Entwurf entfernt werden sollen. Eine lineId, die der Entwurf nicht hat, wird ignoriert, ein erneuter Versuch ist also sicher. Eine lineId darf nicht zugleich in lines und in remove stehen
lineIdErforderlich. 1 bis 64 Zeichen aus [A-Za-z0-9._:/-], Ihre eigene ID für die Zeile, eindeutig innerhalb des Entwurfs (eine andere clientRequestId beginnt von vorn). Eine lineId, die der Entwurf bereits hat, ersetzt diese Zeile an Ort und Stelle; eine neue wird am Ende angefügt. Wird an Sie zurückgegeben; niemals on-chain gespeichert, niemals den Unterzeichnern angezeigt
toEine TRON-Adresse (34 Zeichen, base58check). Nicht die eigene Adresse des Multisigs, nicht die TRON-Nulladresse T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb, nicht der USDT-Vertrag (dorthin gesendete Token gehen verloren)
amountEine Zeichenkette, die ^(0|[1-9][0-9]*)(\.[0-9]+)?$ entspricht, größer als null, höchstens 6 Dezimalstellen, gezählt wie gesendet ("1.0000000" wird mit amount_decimals abgewiesen; "80.500000" wird akzeptiert und als "80.5" gespeichert), höchstens 9223372036854775807 in der kleinsten Einheit. Senden Sie eine Zeichenkette, niemals eine JSON-Zahl. Ownbit speichert den Betrag in kanonischer Form: Abschließende Nullen des Nachkommateils werden entfernt, danach ein alleinstehender Punkt ("80.50" wird zu "80.5", "2.0" wird zu "2")
symbolTRX oder USDT. Senden Sie es in jeder Zeile mit. Wenn Sie es weglassen, zahlt die Zeile im defaultSymbol des Multisigs, das bei einem TRON-Multisig TRX ist: Eine USDT-Auszahlung ohne symbol würde zu einer TRX-Auszahlung mit derselben Zahl. Das Multisig muss dieses Symbol führen (laut whoami, Feld symbols)
memoOptional. Höchstens 80 Zeichen; keines von , ' " \; keine Steuer-, Zeilenumbruch- oder unsichtbaren Zeichen; kein Leerzeichen am Anfang oder Ende; kein reserviertes Memo (beginnend mit admin:, -no-broadcast enthaltend oder auf ***br*** endend, unabhängig von Groß- und Kleinschreibung). Fehlend und "" sind gleichbedeutend

Ownbit entfernt zuerst die Zeilen aus remove, ersetzt oder ergänzt dann jede Zeile aus lines und prüft danach den Entwurf als Ganzes: höchstens 500 Zeilen, mindestens eine und keine zwei Zeilen mit demselben to, demselben kanonischen amount und demselben symbol (die Chain würde die zweite als Duplikat abweisen, während die erste auf Signaturen wartet). Jede Zeile, die Sie senden, wird wie beim ersten Aufruf geprüft; wird etwas abgewiesen, ändert sich nichts.

Antworten:

StatusBodyWann
201{"draft":<draft>}Ein neuer Entwurf, Status submitted, Revision 1, jede Zeile pending
200{"draft":<draft>}Der Entwurf wurde geändert (seine revision ist um eins gestiegen), oder der Aufruf hat nichts geändert (ein erneuter Versuch): der Entwurf in seinem aktuellen Stand
409 not_editabledetails.draftId, details.statusDer Entwurf ist nicht mehr submitted (ein Unterzeichner hat ihn gestartet, oder er wurde zurückgezogen, abgelehnt oder ist abgelaufen): Nichts wurde geändert
409 idempotency_conflictDie clientRequestId wurde von einem anderen Schlüssel desselben Multisigs verwendet
410 goneDer Entwurf zu dieser clientRequestId wurde gelöscht (Aufbewahrung, Abschnitt 7.3)
422 invalid_linesdetails.errorsEine oder mehrere Zeilen sind ungültig, oder der Entwurf wäre leer; nichts wurde geändert
429 daily_limitdetails.scopeDas 24-Stunden-Zeilenlimit des Schlüssels oder des Multisigs würde überschritten (Abschnitt 10). Mit details.neverFits: true und ohne Retry-After enthält allein dieser Aufruf mehr Zeilen als das Limit, Warten hilft also nie: Senden Sie weniger Zeilen pro Aufruf

details.errors listet die ersten 50 Probleme als {"line":<index in lines>,"lineId":"po-1","field":"amount","reason":"amount_decimals"} auf. Gründe: 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 und lineId sind null: Das Entfernen würde keine Zeile übrig lassen; ziehen Sie stattdessen den Entwurf zurück, Abschnitt 6.5).

6.2.1 Der Entwurf

Die vollständige Form (die Form in der Liste hat kein 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_ gefolgt von 24 Zeichen aus [0-9a-z].
  • revision: 1 für einen neuen Entwurf, um eins höher nach jedem Aufruf, der ihn geändert hat.
  • startedAt: wann ein Unterzeichner den Entwurf zum ersten Mal auf seinem Telefon gestartet hat, sonst null. Der Wert ändert sich nicht, wenn ein Unterzeichner ihn erneut startet.
  • lines[].lineId: Ihre ID der Zeile. lines[].index: ihre aktuelle Position, ab 0 (sie verschiebt sich, wenn eine Zeile davor entfernt wird: Ordnen Sie Zeilen über lineId zu). memo ist "", wenn es fehlt.
  • lines[].state: folgt immer dem Status des Entwurfs (Abschnitt 7.2). In Phase 1 trägt eine Zeile keine Transaktions-ID, keinen Hash, keine Signaturanzahl und keinen Fehler: Prüfen Sie die Zahlungen wie in Abschnitt 8 beschrieben.
  • totals: die Summe pro Symbol; counts: die Anzahl der Zeilen in jedem Zustand (nur Zustände mit Zeilen).
  • repeated: true, wenn ein anderer Entwurf dieses Multisigs aus den letzten 7 Tagen eine Zeile mit derselben Adresse, demselben Betrag und demselben Symbol hat. Unterzeichner sehen die Markierung und müssen sie bestätigen, bevor sie den Entwurf starten; prüfen Sie Ihr eigenes System, wenn Sie sie sehen.
  • rejection: {"reason","note","at"}, wenn der Entwurf abgelehnt wurde, sonst null. Gründe: whitelist, address, amount, duplicate, other (von einem Unterzeichner in der Web-Konsole gewählt, der eine einzeilige note hinzufügen kann), phone (ein Unterzeichner hat ihn auf seinem Telefon abgelehnt; keine note) und key_revoked. Die API verrät nie, welches Mitglied abgelehnt hat.

6.2.2 Wiederholungen und Änderungen

  • clientRequestId benennt einen Entwurf des Multisigs dauerhaft: Die ID bleibt belegt, solange ihr Entwurf aufbewahrt wird, und noch 365 Tage, nachdem der Entwurf gelöscht wurde (410). Nur der Schlüssel, der den Entwurf erstellt hat, kann ihn ändern; ein anderer Schlüssel desselben Multisigs erhält 409 idempotency_conflict (verwenden Sie nach einer Schlüsselrotation neue IDs). Machen Sie Ihre IDs für immer eindeutig, zum Beispiel ein Datum plus eine laufende Nummer.
  • Jeder Aufruf kann gefahrlos wiederholt werden. Senden Sie nach einem Timeout oder einem Netzwerkfehler dieselbe Anfrage erneut: Gesendete Zeilen ersetzen sich selbst mit demselben Inhalt, und entfernte Zeilen sind bereits weg, die Antwort ist also der Entwurf in seinem aktuellen Stand, niemals ein zweiter Entwurf oder eine zweite Kopie einer Zeile.
  • Eine Änderung ist nur möglich, solange der Entwurf submitted ist. Sobald ein Unterzeichner ihn startet, antwortet ein Aufruf mit 409 not_editable: Bitten Sie die Unterzeichner, Zeilen abzulehnen, die nicht bezahlt werden dürfen, und senden Sie neue unter einer neuen clientRequestId.
  • Unterzeichner sehen den Entwurf so, wie er ist, wenn sie ihn öffnen. Ändert er sich, während ein Unterzeichner ihn geöffnet hat, verweigert dessen Konsole den Start und fordert ihn auf, den Entwurf erneut zu öffnen.
  • Zwei gleichzeitige Aufrufe mit derselben ID werden nacheinander angewendet.

6.2.3 Der Inhalts-Hash

contentHash ist der SHA-256 in Hex-Kleinbuchstaben über die UTF-8-Bytes des kompakten JSON-Arrays der Zeilen des Entwurfs in ihrer Reihenfolge, jede geschrieben als {"lineId","to","amount","symbol","memo"} in dieser Reihenfolge, mit dem kanonischen Betrag, dem stets ausgeschriebenen Symbol und "" für ein fehlendes memo. Er ändert sich mit jeder Änderung des Entwurfs. Für die erste Anfrage oben:

[{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001"},{"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT","memo":""}]

→ cc43baacd7df98efac68139dd9be5dba47d4fa0343c034e3fd54098409cf59a4. Bauen Sie die Zeichenkette selbst zusammen (die Schlüsselreihenfolge oder das Escaping einer JSON-Bibliothek wird nicht benötigt: Keines dieser Felder darf ein Zeichen enthalten, das escaped werden muss). Der Fingerabdruck, den die Unterzeichner sehen, sind die ersten 16 Hex-Zeichen von contentHash (hier cc43baacd7df98ef). Abschnitt 8 sagt, was damit zu tun ist.

6.3 GET /drafts?since=<cursor>&limit=<n>

Die Entwürfe dieses Schlüssels, sortiert nach updatedAt, dann draftId, nach dem Cursor (ohne since: ab dem ältesten aufbewahrten). limit ist 1 bis 100, Standard 50.

{"drafts":[<draft without lines>],"nextCursor":"<opaque>","hasMore":false}

Das updatedAt eines Entwurfs ändert sich, sobald sich sein Status oder seine Zeilen ändern, daher sieht ein Polling mit dem letzten nextCursor jede Änderung. Eine leere Seite gibt den gesendeten Cursor zurück; verwenden Sie ihn weiter. Ein Cursor, der nicht gelesen werden kann, ergibt 400 invalid_request.

6.4 GET /drafts/{draftId}

200 {"draft":<draft>}. Ein Entwurf eines anderen Schlüssels (auch desselben Multisigs) oder einer, der nicht mehr aufbewahrt wird: 404 not_found.

6.5 DELETE /drafts/{draftId}

Zieht einen Entwurf zurück, den noch niemand gestartet hat. Nur solange sein Status submitted ist: Jede Zeile wird withdrawn, 200 {"draft":<draft>}. Bereits withdrawn: erneut 200. Andernfalls 409 not_withdrawable mit details.status. Sobald ein Unterzeichner einen Entwurf gestartet hat, bitten Sie stattdessen die Unterzeichner, den Rest abzulehnen.

7. Status

7.1 status des Entwurfs

StatusBedeutung
submittedNoch niemand hat ihn gestartet. Nur jetzt kann Ihr Bot ihn ändern (Abschnitt 6.2) oder zurückziehen (Abschnitt 6.5)
startedEin Unterzeichner hat ihn auf seinem Telefon gestartet (startedAt sagt, wann das zum ersten Mal geschah). Ein Unterzeichner kann ihn öffnen und erneut starten, zum Beispiel nachdem sein Telefon mittendrin angehalten hat; er bleibt started
rejectedEin Unterzeichner hat ihn abgelehnt, in der Web-Konsole oder auf seinem Telefon (bevor oder nachdem er gestartet wurde), oder sein Schlüssel wurde widerrufen, bevor ihn jemand gestartet hat. rejection sagt, warum
withdrawnIhr Bot hat ihn zurückgezogen
expiredNiemand hat ihn innerhalb von 7 Tagen gestartet

Ownbit meldet nur, was es sicher weiß: dass ein Unterzeichner den Entwurf auf seinem Telefon gestartet hat. Es erfährt nicht, welche Zahlungen folgten, daher kann ein started-Entwurf vollständig, teilweise oder gar nicht bezahlt sein. Die Zahlungen sind Transaktionen des Multisigs: Prüfen Sie sie wie in Abschnitt 8 beschrieben, und reichen Sie die Zeilen eines gestarteten Entwurfs nicht erneut ein, es sei denn, die Unterzeichner teilen Ihnen mit, dass sie nicht bezahlt wurden.

7.2 state der Zeile

Der state einer Zeile ist immer der ihres Entwurfs: In Phase 1 verfolgt Ownbit die Transaktion der einzelnen Zeilen nicht.

ZustandBedeutung
pendingDer Entwurf ist submitted
startedDer Entwurf ist started
rejected, withdrawn, expiredDer Status des Entwurfs

7.3 Lebensdauer

Ein Entwurf, den niemand startet, läuft nach 7 Tagen ab. Ein gestarteter Entwurf bleibt started, bis ein Unterzeichner ihn ablehnt. Abgelehnte, zurückgezogene und abgelaufene Entwürfe werden 30 Tage nach ihrem Ende aufbewahrt, ein gestarteter Entwurf 30 Tage nach seiner letzten Änderung; danach werden sie gelöscht (GET antwortet dann mit 404; dieselbe clientRequestId antwortet noch 365 weitere Tage mit 410).

8. Prüfen, was bezahlt wird

Ownbit trägt Ihre Liste von Ihrem Bot bis auf die Bildschirme der Unterzeichner. Um sicherzustellen, dass sich unterwegs nichts geändert hat:

  1. Zeigen Sie die clientRequestId und den Fingerabdruck (die ersten 16 Hex-Zeichen von contentHash) in Ihrem eigenen Genehmigungskanal an, neben der genehmigten Auszahlungsliste. Ein Entwurf, den Sie ändern, hat einen neuen Fingerabdruck: Zeigen Sie den neuesten an. Die Unterzeichner sehen beide in der Web-Konsole, von ihrem Browser neu berechnet aus den Zeilen, die sie gleich starten werden, und werden gebeten, sie mit Ihrem Protokoll zu vergleichen. Dieser Vergleich ist nur möglich, wenn Ihr Genehmigungsprotokoll sie zeigt.
  2. Berechnen Sie contentHash neu (Abschnitt 6.2.3) aus den Zeilen jedes Entwurfs, den Sie lesen, und vergleichen Sie ihn mit dem Wert, den Sie für die neueste Revision des Entwurfs berechnet haben.
  3. Prüfen Sie die Zahlungen des Multisigs selbst on-chain. In Phase 1 meldet Ownbit nicht die Transaktion jeder Zeile. Sobald ein Entwurf started ist, vergleichen Sie seine Zeilen mit den ausgehenden Transaktionen der Adresse des Multisigs (laut whoami, Feld multisig.address): Empfänger, Betrag und Token jeder Zahlung müssen denen einer Ihrer Zeilen entsprechen, und jede Zeile sollte höchstens einmal bezahlt werden.
  4. Achten Sie auf repeated: Eine Zeile, die eine Zeile eines anderen aktuellen Entwurfs wiederholt, wird für die Unterzeichner markiert; sie sollte auch in Ihrem System markiert sein.
  5. Bitten Sie bei einem Enterprise-Multisig dessen Mitglieder, die Whitelist und ein Tageslimit einzuschalten: Dann kann selbst ein falscher Entwurf weder an eine unbekannte Adresse noch mehr als das Limit zahlen. Andere Multisigs haben keine Whitelist, daher ist die Prüfung durch die Unterzeichner die einzige.

9. Fehler

Jeder Fehler hat diesen Body:

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

message ist ein fester englischer Satz für Menschen; programmieren Sie gegen code und details. Meldungen geben Ihre Eingabe nie wieder.

HTTPcodeWann
400invalid_requestKein JSON, ein falscher Typ, ein unbekanntes Feld, eine ungültige clientRequestId, keine Zeile oder mehr als 500, ein ungültiger Cursor oder ein ungültiges Limit, ein Anfrage-Body, der nicht innerhalb von 10 Sekunden eingetroffen ist
401unauthorizedJedes Schlüsselproblem (Abschnitt 5)
403forbiddenEin gültiger Schlüssel ohne die Berechtigung für den Aufruf
403https_requiredDie Anfrage kam nicht über HTTPS (widerrufen Sie den Schlüssel, den sie enthielt)
404not_foundEin unbekannter Pfad; ein Entwurf, der nicht zu diesem Schlüssel gehört oder nicht mehr aufbewahrt wird
405method_not_allowedEine Methode, die der Pfad nicht annimmt (OPTIONS eingeschlossen)
409idempotency_conflictAbschnitt 6.2
409not_editableAbschnitt 6.2 (details.status)
409not_withdrawableAbschnitt 6.5 (details.status)
410goneEine clientRequestId, deren Entwurf gelöscht wurde
413too_largeEin Body über 256 KiB
415unsupported_media_typeEin POST, der kein JSON ist
422invalid_linesAbschnitt 6.2 (details.errors)
429rate_limited, daily_limitEin Limit (Abschnitt 10), mit Retry-After, details.scope, details.limit, details.retryAfter
500internalEin Fehler auf der Seite von Ownbit; später erneut versuchen
503unavailableDie API ist abgeschaltet oder kann gerade nicht antworten; mit details.scope api_busy und Retry-After, wenn sie ausgelastet ist

Ein 429 mit Scope edge oder ein 413, der von der Schutzschicht vor der API kommt, hat dieselbe Form mit "requestId":null.

10. Ratenlimits und Tagesobergrenzen

10.1 Die Limits

LimitWertdetails.scopecode
Anfragen von einer Adresse, Burst20 pro Sekunde (Bursts bis 40), 20 offene Verbindungenedgerate_limited
Aufrufe pro Schlüssel10 pro Sekundekey_secondrate_limited
Aufrufe pro Schlüssel300 pro Minutekey_minuterate_limited
POST /drafts pro Schlüssel60 pro Stundekey_submit_hourrate_limited
Gleichzeitig laufende Aufrufe, pro Schlüssel2key_concurrentrate_limited
Gleichzeitig laufende Aufrufe, pro Multisig (alle seine Schlüssel)4multisig_concurrentrate_limited
Aufrufe pro Adresse (gültige Schlüssel)600 pro Minute; weist nie einen Schlüssel ab, dessen Allowlist nicht leer ist und die Adresse enthältip_minuterate_limited
Aufrufe pro Schlüssel10.000 pro Tagkey_dayrate_limited
Aufrufe pro Multisig (alle seine Schlüssel zusammen)20.000 pro Tagmultisig_dayrate_limited
Aufrufe pro Adresse (gültige Schlüssel)50.000 pro Tag; weist nie einen Schlüssel ab, dessen Allowlist nicht leer ist und die Adresse enthältip_dayrate_limited
Aufrufe pro Adresse (gültige Schlüssel), harte Obergrenze200.000 pro Tag, für jeden Schlüsselip_day (details.limit 200000)rate_limited
Fehlgeschlagene Aufrufe pro Adresse20 pro Minute; darüber hinaus wird die Adresse für 10 Minuten ausgesetztip_failuresrate_limited
Fehlgeschlagene Aufrufe pro Adresse200 pro Tag; darüber hinaus wird die Adresse für 24 Stunden gesperrtip_blockedrate_limited
Fehlgeschlagene Aufrufe pro Netz (ein /24)1.000 pro Tag; darüber hinaus wird das Netz für 24 Stunden gesperrtnet_blockedrate_limited
Zahlungszeilen pro Schlüsseldas eigene Limit des Schlüssels (1 bis 10.000, Standard 1.000) innerhalb beliebiger 24 Stundenkey_lines_24hdaily_limit
Zahlungszeilen pro Multisig10.000 innerhalb beliebiger 24 Stundenmultisig_lines_24hdaily_limit
Gesamte API ausgelastet(schützt den Dienst)api_busy (HTTP 503)unavailable
  • Ein Tag ist der UTC-Kalendertag: Die Aufrufobergrenzen und die Fehlerobergrenzen beginnen um 00:00 UTC neu (08:00 in Peking). Die beiden Zeilenlimits sind gleitend: beliebige 24 Stunden.
  • Was zählt. Jeder Aufruf mit einem gültigen Schlüssel zählt für die Limits von Schlüssel, Multisig und Adresse: auch Lesezugriffe, und Aufrufe, die nach Annahme des Schlüssels abgewiesen werden (ein 403, 404, 409, 422 oder ein 429 eines Zeilenlimits), sowie ein wiederholtes POST /drafts. Ein Aufruf, der von einem Ratenlimit oder einer Obergrenze abgewiesen wird, zählt für keines davon, daher funktioniert das Abwarten von Retry-After immer. Ein Aufruf, dessen Schlüssel abgewiesen wird (401), zählt nur für die fehlgeschlagenen Aufrufe seiner Adresse und seines Netzes.
  • Eine ausgesetzte oder gesperrte Adresse bzw. ein solches Netz (für 10 Minuten ausgesetzt oder für 24 Stunden gesperrt) bedient weiterhin jeden Schlüssel, der gültig ist und dessen Allowlist die Adresse zulässt (eine leere Allowlist lässt alle zu). Nur Aufrufe mit ungültigen Schlüsseln und mit Schlüsseln, deren Allowlist die Adresse nicht zulässt, werden dort abgewiesen. Ein gültiger Schlüssel wird daher nie durch die Fehlschläge anderer von derselben Adresse ausgesperrt.
  • Limits pro Adresse werden mit allen geteilt, die von ihr aus aufrufen. Ein Schlüssel, dessen Allowlist nicht leer ist und die Adresse enthält, wird von den 600 pro Minute oder den 50.000 pro Tag nicht abgewiesen, aber das Burst-Limit (20 pro Sekunde) und die harte Obergrenze (200.000 pro Tag) zählen alle auf der Adresse, sodass auf einem gemeinsam genutzten NAT, CI-Runner oder Cloud-Egress andere Ihre Aufrufe dennoch verlangsamen können; und ein 429 mit Scope ip_minute oder ip_day sagt Ihnen, dass andere auf Ihrer Adresse aktiv sind. Verwenden Sie eine dedizierte ausgehende Adresse.

10.2 Die Antworten

Ein Limit antwortet mit 429 (oder 503 für api_busy), und zwar mit:

{"error":{"code":"rate_limited","message":"Daily call limit of this key reached",
  "details":{"scope":"key_day","limit":10000,"retryAfter":31260}},"requestId":"req_0123456789abcdef"}

und dem Header Retry-After: 31260: die ganzen Sekunden, die zu warten sind (mindestens 1). Der Wert reicht bis zum Ende des Fensters, der Aussetzung oder der Sperre; bis 00:00 UTC bei den täglichen Aufrufobergrenzen; bei den Zeilenlimits, bis genug Ihrer ältesten Zeilen aus den 24 Stunden herausfallen (mindestens 60 Sekunden); 1 für edge und die beiden _concurrent-Scopes; bei api_busy 1 bis etwa 90 Sekunden, mit einem Zufallsanteil, damit abgewiesene Clients nicht alle gleichzeitig zurückkehren. Wenn mehrere Limits gleichzeitig abweisen, nennt die Antwort das mit der längsten Wartezeit. details.limit ist der Wert dieses Limits (bei api_busy nicht angegeben). Der einzige 429 ohne Retry-After ist ein Entwurf, der nie in sein Zeilenlimit passen kann: details.neverFits ist true und details.retryAfter ist null (Abschnitt 6.2).

Die Meldungen: 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 Die Header

Jede Antwort auf einen Aufruf, dessen Schlüssel angenommen wurde (Erfolge, die Fehler danach und seine 429-Antworten), enthält:

HeaderWert
X-RateLimit-LimitDie tägliche Aufrufobergrenze des Schlüssels (10000)
X-RateLimit-RemainingWas heute nach diesem Aufruf übrig ist: der kleinere der Restwerte von Schlüssel und Multisig
X-RateLimit-ResetDas nächste 00:00 UTC, in Unix-Sekunden (am 2026-11-17: 1794960000)

Ein 401, ein 429 von edge, ip_failures, ip_blocked oder net_blocked und ein 503 enthalten keinen davon. GET /whoami liefert dieselben Zähler in seinem Body (callsToday, multisigCallsToday, callsResetAt).

10.4 Wie ein gut programmierter Bot abfragt und sich zurücknimmt

  • Fragen Sie GET /drafts?since=<last nextCursor> alle 30 Sekunden ab, mit einem Poller pro Schlüssel. Das sind 2.880 Aufrufe pro Tag. Wenn sich mehrere Instanzen Ihres Bots einen Schlüssel teilen, lassen Sie eine davon abfragen und das Gelesene teilen. Bewahren Sie den letzten nextCursor über Neustarts hinweg auf; eine leere Seite gibt ihn unverändert zurück. Wenn hasMore true ist, lesen Sie sofort die nächste Seite.
  • Fragen Sie nie schneller ab, als das Budget erlaubt: höchstens einmal alle 86.400 × 2 / X-RateLimit-Limit Sekunden (17,3 Sekunden beim Standardwert 10.000), damit das Polling höchstens die Hälfte der Tagesaufrufe verbraucht. Allein ein Polling alle 10 Sekunden kostet 8.640 Aufrufe und lässt etwa 1.300 für alles andere übrig; zwei Instanzen eines Bots, die das mit einem Schlüssel tun, werden vor Ende des Tages abgewiesen.
  • Lesen Sie einen einzelnen Entwurf nur, wenn Sie seine Zeilen brauchen, also wenn sich sein updatedAt in der Liste geändert hat, und höchstens einmal pro Minute und Entwurf. Fragen Sie nicht jeden Entwurf einzeln ab.
  • Beobachten Sie X-RateLimit-Remaining. Wenn der Wert unter ein Zehntel von X-RateLimit-Limit fällt, fragen Sie seltener ab. Denken Sie daran, dass er mit den anderen Schlüsseln des Multisigs geteilt wird.
  • Bei 429: Warten Sie Retry-After Sekunden plus eine kleine zufällige Verzögerung, dann versuchen Sie es erneut. Versuchen Sie es nicht früher: Die Antwort wird dieselbe sein. Bei key_day oder multisig_day behalten Sie Ihren Cursor und setzen nach X-RateLimit-Reset fort.
  • Bei 503: Mit Retry-After warten Sie diese Zeit plus zufällige 0 bis 30 Sekunden; ohne verlängern Sie die Wartezeit exponentiell von 30 Sekunden bis zu 10 Minuten.
  • Bei einem Netzwerkfehler oder 500 während POST /drafts: Senden Sie dieselbe Anfrage mit derselben clientRequestId erneut (Abschnitt 6.2.2), nach einer Wartezeit wie oben.
  • Bei 401: Verwenden Sie den Schlüssel nicht mehr und alarmieren Sie eine Person. Einen abgewiesenen Schlüssel erneut zu versuchen hilft nie, und mehr als 200 Fehlschläge an einem Tag sperren Ihre Adresse für 24 Stunden für jeden ungültigen Schlüssel (Ihre gültigen Schlüssel funktionieren von dort aus weiter, Abschnitt 10.1).
  • Planen Sie für Mitternacht UTC: Ein Schlüssel oder Multisig, der bzw. das seine Tagesaufrufe verbraucht hat, wird bis 00:00 UTC abgewiesen. Setzen Sie dann nach zufälligen 0 bis 30 Sekunden fort, nicht auf die Sekunde genau.

11. Sicherheitshinweise

  • Nur HTTPS. Senden Sie einen Schlüssel nie über unverschlüsseltes HTTP; ist es passiert, widerrufen Sie den Schlüssel. Prüfen Sie das Zertifikat des Servers wie üblich.
  • Bewahren Sie den Schlüssel auf Ihrem Server auf, in einem Secret Store. Niemals in einem Browser, einer mobilen App, einem Repository, einer Logzeile, einer URL, einem Ticket oder einer Chatnachricht. Ownbit fragt Sie niemals danach.
  • Geben Sie jedem Schlüssel eine IPv4-Allowlist mit den festen ausgehenden Adressen Ihrer Server. Dann kann ein geleakter Schlüssel nirgendwo sonst verwendet werden, er kann also weder Entwürfe einreichen noch die Tagesaufrufe Ihres Multisigs verbrauchen. Bevorzugen Sie eine dedizierte ausgehende Adresse gegenüber einem gemeinsam genutzten NAT oder Cloud-Egress: Eine ausgesetzte oder gesperrte Adresse bedient Ihre gültigen Schlüssel weiterhin, und ein Schlüssel, dessen Allowlist die Adresse enthält, wird von den 600 pro Minute oder den 50.000 pro Tag pro Adresse nicht abgewiesen, aber das Burst-Limit und die 200.000 pro Tag werden mit allen auf der Adresse geteilt (Abschnitt 10.1).
  • Ein Schlüssel pro System, mit einem Namen, der sagt, welches. Höchstens 5 Schlüssel pro Multisig.
  • Rotieren Sie vor dem Ablauf und bei jedem Zweifel: Lassen Sie ein Mitglied einen neuen Schlüssel erstellen, stellen Sie Ihren Bot darauf um und widerrufen Sie dann den alten. Ein neuer Schlüssel muss neue clientRequestIds verwenden (Abschnitt 6.2.2).
  • Bei einem Leak sofort widerrufen, in der Web-Konsole oder in der Ownbit-App. Der Widerruf lehnt die Entwürfe des Schlüssels ab, die noch niemand gestartet hat. Hat ein geleakter Schlüssel die heutigen Aufrufe Ihres Multisigs aufgebraucht, teilt der Ersatzschlüssel diese Obergrenze bis 00:00 UTC: Wenden Sie sich an den Ownbit-Support, der die Obergrenze dieses Multisigs für den Tag anheben kann.
  • Schalten Sie Jobs ab, die widerrufene Schlüssel verwenden: Ihre Fehlschläge zählen gegen Ihre Adresse.
  • Zeigen Sie die clientRequestId und den Fingerabdruck in Ihrem Genehmigungskanal an; prüfen Sie contentHash und die Zahlungen des Multisigs on-chain (Abschnitt 8).
  • Senden Sie symbol in jeder Zeile mit.
  • Behandeln Sie Text aus der API als Daten, niemals als HTML oder Befehle, in Ihren Logs und Dashboards.

12. Nicht in Phase 1

Webhooks; Transaktionsergebnisse pro Zeile (Transaktions-ID, Hash, Signaturen und Fehler einer Zeile); Multisigs auf anderen Chains und andere Token; Zugriff über IPv6 und IPv6-Einträge in der Allowlist; von Ihnen festgelegte Aufruflimits pro Schlüssel; mit Ihrem eigenen Schlüssel signierte Entwürfe. Fragen Sie bei Ownbit nach, wenn Sie eines davon benötigen.

Zuletzt aktualisiert:

Download

Ownbit herunterladen

Installiere die App und richte dann eine Cold Wallet oder MultiSig nach Bedarf ein.