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:
| Aufruf | Berechtigung | Was er tut |
|---|---|---|
GET /whoami | drafts:read | Beschreibt den Schlüssel und sein Multisig, mit den heutigen Aufrufzählern |
POST /drafts | drafts:submit | Reicht 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 /drafts | drafts:read | Listet die Entwürfe dieses Schlüssels auf, älteste Änderung zuerst, mit einem Cursor |
GET /drafts/{draftId} | drafts:read | Liest einen Entwurf mit seinen Zeilen |
DELETE /drafts/{draftId} | drafts:submit | Zieht einen Entwurf zurück, den noch niemand gestartet hat |
2. Umfang von Phase 1
- Nur Multisigs auf TRON. Zeilen zahlen in
TRXoderUSDT(USDT-TRC20, VertragTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t); beide haben 6 Dezimalstellen. - Nur IPv4. Die API ist nur über IPv4 erreichbar (
api.bittool.comhat 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_requiredabgewiesen 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 enthaltenStrict-Transport-Security: max-age=31536000. - JSON in UTF-8.
POST-Anfragen sendenContent-Type: application/json(ein Suffix; charset=utf-8ist 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-cacheundX-Request-Id(req_gefolgt von 16 Zeichen aus[0-9a-z]). Der Body von Fehlerantworten wiederholt sie alsrequestId. 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, alsobk_…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
/8bis/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:submitunddrafts: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_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefgSetzen 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
401verschwindet 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 ohnesymbolzahlt. Bei einem TRON-Multisig ist dasTRX, nichtUSDT: Senden Siesymbolin jeder Zeile mit (Abschnitt 6.2).requiredNumvonownerNum: 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"]}| Feld | Regel |
|---|---|
clientRequestId | 1 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) |
lines | 0 bis 500 Objekte, jedes nur mit den unten aufgeführten Feldern. Der erste Aufruf muss mindestens eines senden |
remove | Optional. 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 |
lineId | Erforderlich. 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 |
to | Eine 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) |
amount | Eine 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") |
symbol | TRX 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) |
memo | Optional. 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:
| Status | Body | Wann |
|---|---|---|
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_editable | details.draftId, details.status | Der 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_conflict | Die clientRequestId wurde von einem anderen Schlüssel desselben Multisigs verwendet | |
410 gone | Der Entwurf zu dieser clientRequestId wurde gelöscht (Aufbewahrung, Abschnitt 7.3) | |
422 invalid_lines | details.errors | Eine oder mehrere Zeilen sind ungültig, oder der Entwurf wäre leer; nichts wurde geändert |
429 daily_limit | details.scope | Das 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, sonstnull. 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 überlineIdzu).memoist"", 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, sonstnull. Gründe:whitelist,address,amount,duplicate,other(von einem Unterzeichner in der Web-Konsole gewählt, der eine einzeiligenotehinzufügen kann),phone(ein Unterzeichner hat ihn auf seinem Telefon abgelehnt; keinenote) undkey_revoked. Die API verrät nie, welches Mitglied abgelehnt hat.
6.2.2 Wiederholungen und Änderungen
clientRequestIdbenennt 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ält409 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
submittedist. Sobald ein Unterzeichner ihn startet, antwortet ein Aufruf mit409 not_editable: Bitten Sie die Unterzeichner, Zeilen abzulehnen, die nicht bezahlt werden dürfen, und senden Sie neue unter einer neuenclientRequestId. - 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
| Status | Bedeutung |
|---|---|
submitted | Noch niemand hat ihn gestartet. Nur jetzt kann Ihr Bot ihn ändern (Abschnitt 6.2) oder zurückziehen (Abschnitt 6.5) |
started | Ein 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 |
rejected | Ein 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 |
withdrawn | Ihr Bot hat ihn zurückgezogen |
expired | Niemand 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.
| Zustand | Bedeutung |
|---|---|
pending | Der Entwurf ist submitted |
started | Der Entwurf ist started |
rejected, withdrawn, expired | Der 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:
- Zeigen Sie die
clientRequestIdund den Fingerabdruck (die ersten 16 Hex-Zeichen voncontentHash) 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. - Berechnen Sie
contentHashneu (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. - Prüfen Sie die Zahlungen des Multisigs selbst on-chain. In Phase 1 meldet Ownbit nicht die Transaktion jeder Zeile. Sobald ein Entwurf
startedist, vergleichen Sie seine Zeilen mit den ausgehenden Transaktionen der Adresse des Multisigs (lautwhoami, Feldmultisig.address): Empfänger, Betrag und Token jeder Zahlung müssen denen einer Ihrer Zeilen entsprechen, und jede Zeile sollte höchstens einmal bezahlt werden. - 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. - 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.
| HTTP | code | Wann |
|---|---|---|
| 400 | invalid_request | Kein 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 |
| 401 | unauthorized | Jedes Schlüsselproblem (Abschnitt 5) |
| 403 | forbidden | Ein gültiger Schlüssel ohne die Berechtigung für den Aufruf |
| 403 | https_required | Die Anfrage kam nicht über HTTPS (widerrufen Sie den Schlüssel, den sie enthielt) |
| 404 | not_found | Ein unbekannter Pfad; ein Entwurf, der nicht zu diesem Schlüssel gehört oder nicht mehr aufbewahrt wird |
| 405 | method_not_allowed | Eine Methode, die der Pfad nicht annimmt (OPTIONS eingeschlossen) |
| 409 | idempotency_conflict | Abschnitt 6.2 |
| 409 | not_editable | Abschnitt 6.2 (details.status) |
| 409 | not_withdrawable | Abschnitt 6.5 (details.status) |
| 410 | gone | Eine clientRequestId, deren Entwurf gelöscht wurde |
| 413 | too_large | Ein Body über 256 KiB |
| 415 | unsupported_media_type | Ein POST, der kein JSON ist |
| 422 | invalid_lines | Abschnitt 6.2 (details.errors) |
| 429 | rate_limited, daily_limit | Ein Limit (Abschnitt 10), mit Retry-After, details.scope, details.limit, details.retryAfter |
| 500 | internal | Ein Fehler auf der Seite von Ownbit; später erneut versuchen |
| 503 | unavailable | Die 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
| Limit | Wert | details.scope | code |
|---|---|---|---|
| Anfragen von einer Adresse, Burst | 20 pro Sekunde (Bursts bis 40), 20 offene Verbindungen | edge | rate_limited |
| Aufrufe pro Schlüssel | 10 pro Sekunde | key_second | rate_limited |
| Aufrufe pro Schlüssel | 300 pro Minute | key_minute | rate_limited |
POST /drafts pro Schlüssel | 60 pro Stunde | key_submit_hour | rate_limited |
| Gleichzeitig laufende Aufrufe, pro Schlüssel | 2 | key_concurrent | rate_limited |
| Gleichzeitig laufende Aufrufe, pro Multisig (alle seine Schlüssel) | 4 | multisig_concurrent | rate_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ält | ip_minute | rate_limited |
| Aufrufe pro Schlüssel | 10.000 pro Tag | key_day | rate_limited |
| Aufrufe pro Multisig (alle seine Schlüssel zusammen) | 20.000 pro Tag | multisig_day | rate_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ält | ip_day | rate_limited |
| Aufrufe pro Adresse (gültige Schlüssel), harte Obergrenze | 200.000 pro Tag, für jeden Schlüssel | ip_day (details.limit 200000) | rate_limited |
| Fehlgeschlagene Aufrufe pro Adresse | 20 pro Minute; darüber hinaus wird die Adresse für 10 Minuten ausgesetzt | ip_failures | rate_limited |
| Fehlgeschlagene Aufrufe pro Adresse | 200 pro Tag; darüber hinaus wird die Adresse für 24 Stunden gesperrt | ip_blocked | rate_limited |
| Fehlgeschlagene Aufrufe pro Netz (ein /24) | 1.000 pro Tag; darüber hinaus wird das Netz für 24 Stunden gesperrt | net_blocked | rate_limited |
| Zahlungszeilen pro Schlüssel | das eigene Limit des Schlüssels (1 bis 10.000, Standard 1.000) innerhalb beliebiger 24 Stunden | key_lines_24h | daily_limit |
| Zahlungszeilen pro Multisig | 10.000 innerhalb beliebiger 24 Stunden | multisig_lines_24h | daily_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,422oder ein429eines Zeilenlimits), sowie ein wiederholtesPOST /drafts. Ein Aufruf, der von einem Ratenlimit oder einer Obergrenze abgewiesen wird, zählt für keines davon, daher funktioniert das Abwarten vonRetry-Afterimmer. 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
429mit Scopeip_minuteoderip_daysagt 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:
| Header | Wert |
|---|---|
X-RateLimit-Limit | Die tägliche Aufrufobergrenze des Schlüssels (10000) |
X-RateLimit-Remaining | Was heute nach diesem Aufruf übrig ist: der kleinere der Restwerte von Schlüssel und Multisig |
X-RateLimit-Reset | Das 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 letztennextCursorüber Neustarts hinweg auf; eine leere Seite gibt ihn unverändert zurück. WennhasMoretrueist, 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-LimitSekunden (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
updatedAtin 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 vonX-RateLimit-Limitfällt, fragen Sie seltener ab. Denken Sie daran, dass er mit den anderen Schlüsseln des Multisigs geteilt wird. - Bei
429: Warten SieRetry-AfterSekunden plus eine kleine zufällige Verzögerung, dann versuchen Sie es erneut. Versuchen Sie es nicht früher: Die Antwort wird dieselbe sein. Beikey_dayodermultisig_daybehalten Sie Ihren Cursor und setzen nachX-RateLimit-Resetfort. - Bei
503: MitRetry-Afterwarten 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
500währendPOST /drafts: Senden Sie dieselbe Anfrage mit derselbenclientRequestIderneut (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
clientRequestIdund den Fingerabdruck in Ihrem Genehmigungskanal an; prüfen SiecontentHashund die Zahlungen des Multisigs on-chain (Abschnitt 8). - Senden Sie
symbolin 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:
Ownbit herunterladen
Installiere die App und richte dann eine Cold Wallet oder MultiSig nach Bedarf ein.