API-Dokumentation
Integrationsdokumentation der offenen Tovanix-API, nach Diensten gegliedert: Zahlung über mehrere Blockchains, Energiemiete, SMTP-API, KI-API, Virtuelle Karte, E-Mail, Objektspeicher, Verifizierung und Transaktionsrisiko, MCP-Zugang. Labore: Vertragsstudio, Zahlungswiedergabe, KI-Routinglabor.
- Zahlung über mehrere Blockchains
- Energiemiete
- SMTP-API
- KI-API
- Virtuelle Karte
- Objektspeicher
- Verifizierung und Transaktionsrisiko
- MCP-Zugang
USDT / USDC / ETH / TRX / BTC · TRON / EVM / Bitcoin · Zweifache Signierung mit HMAC-SHA256 (Zahlung) + RSA-2048 (Auszahlung) · Abrechnungs-Push nach 30 Sekunden
Integration in 3 Schritten
- 1 Konto registrieren und App erstellen Rufen Sie app_id und app_key unter „Meine Apps“ in der Konsole ab und konfigurieren Sie notify_url Kostenlos registrieren →
- 2 Signierungsfunktion implementieren Zahlung verwendet HMAC-SHA256 (symmetrisch), Auszahlung RSA-2048 (asymmetrisch). Das offizielle SDK kapselt beides und enthält vollständige Beispiele für verschiedene Programmiersprachen.
- 3 Modus wählen und erste Transaktion ausführen Eins-zu-eins (Adresse an Nutzer gebunden, ideal für Wallets/Kontoaufladungen) · Rotation (Adresse je Auftrag erzeugt, ideal für E-Commerce-Kassen)
Übersicht
Tovanix unterstützt zwei Zahlungsmodi, die gleichzeitig aktiviert werden können:
Eins-zu-eins-Modus
Nutzer verknüpfen eine feste Adresse; sämtliche Eingänge werden aktiv gemeldet. Ideal für Aufladungen und Zahlungseingänge.
- Nutzer verknüpft eine feste Empfangsadresse
- Echtzeit-Push zu Zahlungseingängen
- Wiederholte Zahlungen unterstützt
- Unabhängige Signaturprüfung
Rotationsmodus
Beim Erstellen eines Auftrags wird dynamisch eine Empfangsadresse zugewiesen und bei Zeitüberschreitung zurückgenommen. Ideal für einmalige Zahlungen.
- Dynamische Adresszuweisung
- Auftragsablauf steuern
- Automatische Wechselkursumrechnung
- Zahlungsseite
Signaturalgorithmus
Push-Benachrichtigungen im Eins-zu-eins-Modus verwenden webhook_secret zur Signierung, nicht app_key.
1. HMAC-SHA256 verwenden, den Geheimschlüssel als HMAC-Schlüsselparameter einsetzen (nicht an die Zeichenfolge anhängen)
2. Die Signatur ist eine hexadezimale Zeichenfolge mit 64 Zeichen in Kleinbuchstaben; der Vergleich unterscheidet Groß- und Kleinschreibung
3. Beim Erstellen eines Auftrags amount mit zwei Nachkommastellen formatieren, z. B. 100.00, und timeout als Ganzzahlzeichenfolge. Auch ohne übergebenes timeout muss timeout=0 signiert werden; der Server nimmt timeout immer in die Signaturzeichenfolge auf.
4. Felder mit leeren Werten werden von der Signaturberechnung ausgeschlossen
Schutz vor Wiederholungsangriffen
Um Wiederholungen abgefangener Anfragen zu verhindern, können signierte Anfragen einen Zeitstempel und nonce enthalten; beides wird mit signiert. Auftragsschließung sowie Adressverknüpfung und deren Aufhebung erfordern beide Angaben und liefern bei Fehlen 400 zurück. Für andere Endpunkte sind sie optional.
/api/v1/pay/close: timestamp und nonce erforderlich. /api/v1/pay/bind-address und /api/v1/pay/unbind-address: sign_ts und nonce erforderlich; das Zeitstempelfeld akzeptiert auch timestamp. /api/v1/pay/get-address verwendet ebenfalls sign_ts, dort optional. Auftrag erstellen, Auftrag abfragen und App-Konfiguration verwenden optional timestamp: Wenn Zeitstempel und nonce beide vorhanden sind, prüft der Server Zeitfenster und nonce. Bei nur einem oder keinem wird nur die Signatur geprüft.
timestamp darf höchstens 300 Sekunden von der Serverzeit abweichen. Synchronisieren Sie Ihre Server mit NTP. Ein nonce darf innerhalb von 5 Minuten nicht erneut verwendet werden. Anfragen außerhalb des Zeitfensters oder mit wiederverwendetem nonce werden abgewiesen: Auftrag erstellen und abfragen liefern HTTP 400, andere Endpunkte 401. Das Nachrichtenfeld der Antwort nennt den Grund.
Adresse verknüpfen
POST /api/v1/pay/bind-address
Einem Nutzer eine feste Zahlungsadresse zuweisen. Bei bestehender Verknüpfung wird die vorhandene Adresse zurückgegeben.
Verknüpfung abfragen
POST /api/v1/pay/get-address
Die mit einem Nutzer verknüpfte Zahlungsadresse abfragen.
Adressverknüpfung aufheben
POST /api/v1/pay/unbind-address
Zahlungsadressverknüpfung eines Nutzers aufheben.
Bestellung erstellen
POST /api/v1/pay/create
Zahlungsauftrag erstellen; das System weist automatisch eine Empfangsadresse zu.
Antwortfelder
amount akzeptiert Zahl und Zeichenfolge: 100 oder "100". Für die Signierung immer mit zwei Nachkommastellen formatieren, z. B. "100.00".
Auftrag abfragen
GET /api/v1/pay/query
Auftragsstatus anhand Ihrer eigenen Auftrags-ID abfragen. Parameter über die URL-Abfrage.
Auftrag schließen
POST /api/v1/pay/close
Unbezahlten Auftrag manuell schließen; die Adresse wird zurückgenommen. Nur ausstehende Aufträge (status=0) können geschlossen werden.
App-Konfiguration abfragen
GET /api/v1/pay/app-config
Moduseinstellungen, aktivierte Token, Push-Konfigurationen und weitere App-Einstellungen abfragen. Keine vertraulichen Daten werden offengelegt.
Push-Benachrichtigung im Eins-zu-eins-Modus
Wenn eine verknüpfte Adresse eine Überweisung empfängt, sendet das System eine POST-Anfrage an die konfigurierte notify_url.
Push-Benachrichtigungen werden mit webhook_secret signiert; dieser kann auf der App-Detailseite eingesehen oder neu erzeugt werden.
Push-Felder
Nach Empfang HTTP 200 oder {"code": 0} zurückgeben. Andernfalls wiederholt das System automatisch, bis zu 10 Mal mit exponentiellem Backoff.
Auftrags-Callback-Benachrichtigung
Nach Bezahlung eines Auftrags im Rotationsmodus sendet das System einen Callback an notify_url.
Callback-Benachrichtigungen werden mit webhook_secret signiert; dieser kann auf der App-Detailseite eingesehen oder zurückgesetzt werden.
Callback-Felder
Jeder 2xx-Status gilt als zugestellt; der Antworttext wird nicht geprüft ({"code": 0} mit einem Nicht-2xx-Status ist trotzdem ein Fehler). Nicht-2xx, keine Antwort innerhalb von 10 Sekunden, Verbindungsfehler und Weiterleitungen gelten als Fehler; die Plattform wiederholt nach 30 Sekunden, 1, 2 und 5 Minuten, danach alle 10 Minuten, bis zu 10-mal. Wiederholungen behalten dieselbe notify_id, tragen aber neue sign_ts, nonce und Signatur — deduplizieren Sie über notify_id.
Wechselkurs abrufen
GET /api/v1/rate
Aktuellen Wechselkurs zwischen zwei Währungen abrufen
Betrag umrechnen
POST /api/v1/convert
Betrag mit aktuellen Wechselkursen umrechnen
Wechselkurse gesammelt abrufen
GET /api/v1/rates
Wechselkurse mehrerer Währungen abfragen (Codes durch Kommas getrennt)
Alle Wechselkurse
GET /api/v1/rates/all
Wechselkursliste aller unterstützten Währungen abrufen
Fiatwechselkurse
GET /api/v1/rates/fiat
Alle Fiatwechselkurse auf Basis einer gewählten Fiatwährung abrufen (mehr als 30 Währungen, nach Region gruppiert)
Bestellstatus
Aufträge durchlaufen folgende Status:
Fehlercodes
Einheitliche Fehlercodes für die Zahlungs-API (/api/v1/pay/*); Fehlercodes der Auszahlungs-API stehen im Referenzabschnitt.
Auszahlungsübersicht / Voraussetzungen
Die Auszahlungs-API ist die Auszahlungsseite des Produkts für Zahlungen über mehrere Blockchains — sie überträgt programmatisch bereits in die zentrale Wallet eingesammelte Vermögenswerte an externe Adressen. Gegenseitige RSA-2048-Signaturen + IP-Freigabeliste + verzögerte Übertragung + Benachrichtigungen über mehrere Kanäle zur Intervention + Callback nach On-Chain-Bestätigung.
Die Auszahlungs-API verwendet ausschließlich Vermögenswerte, die im Modus Systemverwahrung in die zentrale Wallet eingesammelt wurden. Nutzt Ihre Zahlungs-App den Modus Eigenverwahrung — die Gelder gehen direkt an Ihre eigenen Adressen und werden von der Plattform nie eingesammelt — entsteht kein Guthaben „eingesammelt, zur Auszahlung ausstehend“. Auszahlungen über diese API sind dann nicht möglich.
In 4 Schritten aktivieren
- Öffnen Sie in der Konsole die Einstellungen „Zahlungen über mehrere Blockchains → API-Auszahlung“
- Erzeugen Sie lokal ein RSA-2048-Schlüsselpaar und laden Sie den öffentlichen Schlüssel bei uns hoch
- Tragen Sie mindestens eine IP-Adresse in die Freigabeliste ein (Pflicht); optional können Sie eine Adressfreigabeliste, ein Limit je Transaktion und eine Auszahlungsverzögerung festlegen
- Aktivieren Sie den Hauptschalter; das System erzeugt automatisch ein Plattform-Schlüsselpaar für das Konto. Kopieren Sie den öffentlichen Plattformschlüssel für die Callback-Prüfung auf Ihre Seite
Signatur · RSA-2048 (Auszahlung)
Alle /api/v1/withdraw*-Endpunkte müssen die folgenden Anfrage-Header enthalten. Anders als die symmetrische HMAC-Signatur der Zahlungs-API verwenden Auszahlungen asymmetrisches RSA. Die Plattform hält nur Ihren öffentlichen Schlüssel; das Risiko besteht daher bei einem Verlust Ihres privaten Schlüssels.
- X-API-Key — API-Schlüssel der Plattform (in der Konsole unter Tools und Einstellungen → API-Verwaltung); der Schlüssel muss die withdraw-Berechtigung besitzen
- X-Timestamp — Aktueller Unix-Zeitstempel in ms; die Abweichung zur Serverzeit darf höchstens 60 Sekunden betragen
- X-Nonce — Einmalige Nonce (uuid); darf innerhalb von 5 Minuten nicht erneut verwendet werden
- X-Withdraw-Signature — RSA-PKCS1v15-SHA256(caller_private_key, signString), Base64
Regel zum Zusammensetzen der Signaturzeichenfolge
BODY ist hier der unveränderte HTTP-Nachrichtenkörper (die JSON-Zeichenfolge wortgetreu — nicht erneut serialisieren). Bei GET-Anfragen ist BODY eine leere Zeichenfolge.
Zusätzlich zur oben beschriebenen RSA-Signatur und IP-Freigabeliste auf Kontoebene muss der verwendete API-Schlüssel die Berechtigung withdraw besitzen und unterliegt seiner eigenen Quell-IP-Freigabeliste: Fehlende Berechtigung liefert 403 / 4032, eine IP außerhalb der Schlüsselliste 403 / 4033. Beide Prüfungen gelten für /api/v1/withdraw, /api/v1/balance/withdrawable und /api/v1/fee/quote. Bereits zuvor bestehende Schlüssel erhalten withdraw automatisch und bleiben unbeeinträchtigt; für neue Schlüssel wählen Sie es unter Tools und Einstellungen → API-Verwaltung. Berechtigungen sind über GET /api/v1/whoami prüfbar (X-API-Key + X-Secret-Key oder HMAC-Signatur).
Callback zum Auszahlungsergebnis
Beim Anlegen eines Auftrags können Sie callback_url im Nachrichtenkörper übergeben; sobald die Auszahlung abgeschlossen, fehlgeschlagen oder storniert ist, sendet die Plattform das Ergebnis per POST an diese URL.
- Der Callback-Inhalt wird mit dem privaten Plattformschlüssel signiert; die Signatur wird im Header X-Platform-Signature übermittelt
- Prüfen Sie die Signatur mit dem öffentlichen Plattformschlüssel (auf der Einstellungsseite kopierbar); der Prüalgorithmus entspricht dem der Anfragen
- Bei Fehlschlag erfolgen Wiederholungen nach 1m / 5m / 30m / 2h / 6h / 24h — insgesamt 6 Versuche — danach wird abgebrochen und zur manuellen Bearbeitung eskaliert
- Ihre Seite muss HTTP 2xx zurückgeben; jede andere Antwort gilt als Fehlschlag
Header
- X-Timestamp — Aktueller Unix-Zeitstempel in Millisekunden
- X-Platform-Signature — Base64(RSA-PKCS1v15-SHA256(privater Plattformschlüssel, Signaturstring))
Regel zum Zusammensetzen der Signaturzeichenfolge
PATH ist der Pfad von callback_url (ohne Host und Query-String), BODY der empfangene Request-Body im Original — nicht neu serialisieren. Prüfen Sie mit dem öffentlichen Plattformschlüssel von der Einstellungsseite.
status ist completed / failed / failed_onchain / cancelled; Beträge und Gebühren sind Strings; created_at und completed_at sind Unix-Sekunden, 0 ohne Abschlusszeit. Der Body ändert sich zwischen Wiederholungen derselben Bestellung nicht — deduplizieren Sie über order_id.
Auszahlung starten
POST /api/v1/withdraw
Nach Auftragserstellung ist der Status pending. Nach Ablauf der Verzögerung überträgt ein Worker die Transaktion automatisch. Während dieser Zeit können Sie den Auftrag in der Konsole pausieren, beschleunigen oder stornieren.
Feldbeschreibungen
- chain — string — Ja — tron / eth / bsc / polygon / arbitrum / base / optimism / avax / xlayer / btc
- symbol — string — Ja — USDT / TRX / ETH usw.
- amount — string — Ja — Bis zu 18 Dezimalstellen; als Zeichenfolge verwenden, um Gleitkommafehler zu vermeiden
- to_address — string — Ja — Zieladresse (bei aktivierter Adressfreigabeliste zuvor in der Konsole eintragen)
- memo — string — Nein — Beschreibung (≤500 Zeichen); wird zusammen mit der Benachrichtigung an den Kontoinhaber gesendet
- callback_url — string — Nein — Callback-URL für das Ergebnis; bei leerem Wert wird kein Callback gesendet
- request_id — string — Dringend empfohlen — Idempotenzschlüssel; erneutes Senden desselben Wertes für dasselbe Konto liefert den ursprünglichen Auftrag; weichen Chain, Währung, Adresse oder Betrag ab, kommt 409 und es wird kein Auftrag angelegt Ohne ihn gibt es keinen Idempotenzschutz: Ein erneuter Versuch nach einem Timeout oder einer 5xx-Antwort löst eine zweite echte Auszahlung aus.
Antwortfelder
- order_id — string — ID des Auszahlungsauftrags; für den Endpunkt zur Abfrage einer einzelnen Auszahlung
- status — string — Aktueller Auftragsstatus mit denselben Werten wie status_label im Abfrage-Endpunkt. Ein neuer Auftrag ist pending (Guthaben abgezogen, wartet auf Sicherheitsverzögerung und Übertragung). Erneutes Senden derselben request_id liefert den tatsächlichen Status, der bereits completed, failed usw. sein kann.
- amount — string — Auszahlungsbetrag (Zeichenfolge)
- fee — string — Voraussichtliche Gebühr (bei Auftragserstellung festgehalten)
- fee_mode — string — in_amount = vom Betrag abgezogen (Empfang = amount − fee, Guthabenbelastung = amount); out_amount = separat berechnet (Empfang = amount, Guthabenbelastung = amount + fee)
- delayed_until — string | null — Geplanter Übertragungszeitpunkt (Sicherheitsverzögerung); null = keine Verzögerung
Status einer einzelnen Auszahlung abfragen
GET /api/v1/withdraw/:id
Liefert die Auftragsdetails; kann zur wiederholten Statusabfrage genutzt werden (Callbacks werden weiterhin empfohlen).
Antwortfelder
- id — string — ID des Auszahlungsauftrags
- request_id — string — Übergebener Idempotenzschlüssel
- chain / symbol — string — Blockchain / Tokensymbol
- amount / expected_fee / fee_mode — string — Auszahlungsbetrag / bei Auftragserstellung festgehaltene Gebühr / Gebührenmodus (in_amount, out_amount)
- to_address — string — Zieladresse
- memo — string — Memo (TAG/Memo)
- status / status_label — int / string — Statuscode und Textbezeichnung; siehe „Auftragsstatus“ unten
- tx_hash — string — On-Chain-Transaktionshash (nach Übertragung gesetzt)
- fail_reason — string — Fehlergrund (bei Fehlschlag gesetzt)
- delayed_until / broadcast_at / confirmed_at / paused_at / cancelled_at — string | null — Zeitstempel der Phasen: geplante Übertragung / Übertragung / On-Chain-Bestätigung / Pause / Stornierung; null, wenn noch nicht erreicht
- callback_url / callback_retry — string / int — Ergebnis-Callback-URL / bisherige Wiederholungsanzahl
- callback_state — string — Callback-Status: pending = noch nicht aufgerufen oder Wiederholung läuft, success = 2xx empfangen, giveup = Wiederholungen ausgeschöpft, no_url = kein Callback konfiguriert
- created_at — string — Erstellungszeitpunkt
Verfügbares Guthaben abfragen
GET /api/v1/balance/withdrawable
Liefert das Guthaben „eingesammelt, zur Auszahlung ausstehend“ dieses Kontos je Blockchain × Vermögenswert. Nur dieser Anteil kann für API-Auszahlungen verwendet werden.
Zweistufige Struktur: Blockchain → Tokensymbol → auszahlbares Guthaben (Zeichenfolge); nur Einträge mit Guthaben größer als 0 werden zurückgegeben.
Gebührenschätzung
Liefert die vom Administrator für diese Kombination aus Blockchain × Symbol konfigurierte vorab abzuziehende Gebühr (ein fester Wert nach dem OKX-Modell).
Antwortfelder
- chain / symbol / amount — string — Zurückgegebene Anfrageparameter: chain / symbol / amount
- fee_amount — string — Gebührenbetrag
- fee_asset — string — Vermögenswert für die Gebührenabrechnung
Vollständiges cURL-Beispiel
Vollständiger Ablauf für Signatur und Anfrage; zum Testen direkt ins Terminal kopieren.
Auftragsstatus · Auszahlung
Zustandsautomat: pending → broadcasted → completed / failed_onchain; dazwischen sind paused / cancelled / failed möglich.
- 0 — pending — Guthaben abgezogen; wartet auf das Ende der Verzögerung / noch nicht übertragen
- 1 — completed — On-Chain-Transaktion erfolgreich bestätigt (Callback möglich)
- 2 — failed — Vor der Übertragung fehlgeschlagen (Guthaben erstattet)
- 3 — broadcasted — Übertragen; wartet auf On-Chain-Bestätigung
- 4 — failed_onchain — On-Chain-Fehlschlag (Rückabwicklung / lange nicht in einen Block aufgenommen; Guthaben erstattet)
- 5 — paused — Vom Benutzer manuell pausiert; kann fortgesetzt oder storniert werden
- 6 — cancelled — Vom Benutzer manuell storniert; Guthaben erstattet
- 7 — broadcasting — Wird übertragen (kurzer Übergangszustand zur Vermeidung doppelter Übertragung)
Fehlercodes · Auszahlungs-API
- 400 — Ungültige Parameter / unzureichendes Guthaben / Betrag außerhalb der Limits für Blockchain × Symbol / Adressprüfung fehlgeschlagen
- 401 — Ungültiger API-Schlüssel / zu große Zeitabweichung / Nonce bereits verwendet / Signaturprüfung fehlgeschlagen
- 403 — API-Auszahlung für das Konto nicht aktiviert / IP nicht in der Konto-Freigabeliste; oder dem API-Schlüssel fehlt die withdraw-Berechtigung (code 4032) bzw. die Quell-IP steht nicht in der Freigabeliste dieses Schlüssels (code 4033)
- 404 — Bestellung nicht gefunden
- 429 — Zu viele Anfragen (höchstens 10 pro Sekunde je Konto). Die Antwort enthält Retry-After: 1; eine Sekunde warten und mit derselben request_id wiederholen
- 5xx — Plattformfehler; Wiederholung möglich (dieselbe request_id verwenden, um Idempotenz sicherzustellen)
Sicherheitshinweise zu Auszahlungen
- Bewahren Sie Ihren privaten Schlüssel sicher lokal auf; bei einem Verlust könnten andere Auszahlungen in Ihrem Namen anweisen
- Vor Aktivierung von API-Auszahlungen ist eine IP-Freigabeliste Pflicht; nicht freigegebene IPs werden auch mit gültiger Signatur abgelehnt
- Wir empfehlen außerdem, die Adressfreigabeliste für Auszahlungen zu aktivieren und bekannte Zieladressen vorab einzutragen
- Nach Aktivierung von 2FA kann der Kontoinhaber in der Konsole Aufträge während der Verzögerung mit 2FA beschleunigen oder stornieren
- Bei großen Aufträgen eine längere Verzögerung (mehrere Stunden) erwägen, damit nach Benachrichtigungen Zeit für manuelle Intervention bleibt
Verwandte Seiten: Krypto-Zahlungen über mehrere Blockchains · SMTP-Aggregations-API · KI-Dienste
Wird geladen…