Skip to main content
Erfordert eine Silver-Mitgliedschaft oder höher — sowohl für die Bewerbung als auch für jeden authentifizierten Aufruf. Läuft die Mitgliedschaft des Schlüsselinhabers aus, wird das Projekt eingefroren, bis er sie erneuert.
Eine REST-API, mit der deine Anwendung das Vito-Guthaben eines Nutzers aus Discord heraus verwendet — lesen, belasten, gutschreiben oder zwischen Nutzern bewegen. Alle Endpunkte liefern JSON und sind unter /v1 versioniert.
Vito bewegt sich nie zu oder von echtem Geld. Es wandert ausschließlich zwischen Vetox-Guthaben.

Zugang erhalten

Der Zugang wird pro Projekt vergeben. Du brauchst alle vier:
1

Eine aktive Mitgliedschaft, Silver oder höher

Wird bei jedem Aufruf geprüft, nicht nur bei der Genehmigung.
2

Eine genehmigte Entwicklerbewerbung

Wird auf der Vito-API-Seite im Dashboard eingereicht und vom Vetox-Team manuell geprüft.
3

Akzeptierte API-Entwicklerbedingungen

Werden beim Einreichen der Bewerbung bestätigt.
4

Die Scopes, die dein Projekt benötigt

Werden vom Vetox-Team anhand deiner Beschreibung vergeben.
Sei konkret, was du baust und wie du den Schlüssel speicherst. Vage Bewerbungen sind die, die abgelehnt werden.

Scopes

Authentifizierung

Sende deinen geheimen Schlüssel als Bearer-Token:
Zwei optionale Ebenen härten ein Projekt zusätzlich ab:
  • IP-Allowlist — Aufrufe auf bestimmte Server-IPs beschränken
  • Rate-Limits — Obergrenzen pro Projekt, die mit der Mitgliedschaftsstufe des Inhabers steigen

Schlüssel, Rotation und Speicherung

Dein Schlüssel und dein Signing Secret werden genau einmal angezeigt. Nach der Genehmigung hast du ein 7-Tage-Fenster, um sie im Tab „API Keys“ aufzudecken. Vetox speichert nur einen Hash und kann sie nicht erneut anzeigen — verpasst du das Fenster, musst du rotieren.
  • Halte ihn ausschließlich serverseitig — wer ihn besitzt, kann deine Nutzer belasten
  • Rotiere im Tab „API Keys“. Der vorherige Schlüssel funktioniert weitere 24 Stunden als Karenzzeit, damit du ohne Ausfall deployen kannst
  • Das Webhook-Signing-Secret rotiert separat, mit eigener 24-Stunden-Überlappung
  • Bei einem Leak sofort rotieren

Einen Nutzer belasten

Dein Schlüssel allein kann das Vito eines Nutzers nicht bewegen. Jede Belastung erfordert die Freigabe des Nutzers mit seiner Wallet-PIN, auf vetox.io — niemals in deiner App und niemals in Discord.
1

Deine App ruft POST /v1/deduct auf

Mit dem Nutzer, dem Betrag, der auslösenden guildId und den Artikeldetails.
2

Vito liefert eine confirmUrl

Eine ausstehende Bestätigung, 10 Minuten gültig. Der Nutzer erhält zusätzlich eine DM.
3

Der Nutzer bestätigt mit seiner PIN

Auf vetox.io.
4

Vito bucht und benachrichtigt

Das Guthaben wird belastet, die Transaktion gespeichert und ein signierter Webhook gesendet, sofern konfiguriert.
5

Deine App prüft und schließt ab

Signatur prüfen, dann den Inhalt freischalten oder den Artikel ausliefern.
Schließe deine Aktion ausschließlich bei confirmation.completed ab — niemals bei der Antwort von /deduct. Zu diesem Zeitpunkt ist die Belastung noch nicht endgültig.

Request-Parameter — /v1/deduct

Einem Nutzer gutschreiben

POST /v1/add schreibt einem Nutzer Vito aus deinem eigenen Guthaben gut — für Belohnungen oder Erstattungen. Dieselben Felder wie /deduct, außer guildId und product.
Anders als eine Belastung hat eine Gutschrift keinen Bestätigungsschritt — sie wird sofort gebucht. Erfordert den Scope credit:create und ausreichendes Guthaben, sonst antwortet der Aufruf mit 402 VITO_INSUFFICIENT_OWNER_FUNDS.

Gebühren

Jede Belastung wird an dich ausgezahlt, abzüglich der Plattformgebühr — nach demselben Schema wie In-App-Vito-Transfers, basierend auf deiner Mitgliedschaftsstufe:
Beträge von 5 Vito oder weniger sind gebührenfrei, und Gutschriften über /v1/add sind immer gebührenfrei.

Webhooks

Trage im Tab „Settings“ eine oder mehrere https-Callback-URLs ein. Vito sendet ein signiertes POST, sobald eine Bestätigung einen Endzustand erreicht.
Webhooks werden nur ausgeliefert, wenn dein Projekt sowohl eine Callback-URL als auch ein Signing Secret hat. Decke das Secret (whsec_…) einmalig im Tab „API Keys“ auf.

Signatur prüfen

Jede Auslieferung trägt einen X-Vito-Signature-Header:
Zwei weitere Header begleiten jede Auslieferung — nutze X-Vito-Event-Id als Deduplizierungsschlüssel, denn ein Retry sendet dieselbe ID erneut:
Während einer Signing-Secret-Rotation enthält der Header mehr als eine Signatur, die neueste zuerst:
Akzeptiere die Auslieferung, wenn irgendein h1 passt. Ein Verifier, der nur den ersten liest, lehnt jeden Webhook ab, bis er das neue Secret ausgerollt hat — was den Sinn der 24-Stunden-Überlappung zunichtemacht.
Berechne den HMAC über <ts>:<rawBody> mit deinem Signing Secret neu und vergleiche in konstanter Zeit.
Prüfe gegen den Raw Body, bevor JSON-Parsing oder Middleware ihn umschreibt.

Events

Fünf Event-Typen, alle mit derselben Payload-Struktur. data.status trägt das Ergebnis.
Webhooks werden 5-mal mit Backoff wiederholt. Bestätige schnell mit 2xx und erledige deine Auslieferung asynchron.

Fehlercodes

Jede Antwort ist in einen Envelope verpackt. Ein Erfolg trägt data, ein Fehler error — nie beides:
Jeder Code beginnt mit VITO_. Vergleiche den vollständigen String — ein blankes RATE_LIMITED oder FORBIDDEN erscheint nie auf der Leitung.

Rate-Limits

Zusätzlich gilt ein Limit pro IP in Höhe der halben Minutenquote, mindestens jedoch 30.
Unter Last scheitern Schreib-Endpunkte geschlossen — eine Belastung wird abgelehnt, statt ein Double-Spend zu riskieren. Lesende Endpunkte scheitern offen. Behandle eine abgelehnte Schreiboperation als „nicht passiert“ und wiederhole sie.
Sende einen Idempotency-Key-Header, um Retries sicher zu deduplizieren.

Endpunkte

Grenzwerte

  • Bestätigungen verfallen nach 10 Minuten — behandle unbestätigte Anfragen als abgebrochen
  • amount muss eine positive Ganzzahl sein
  • metadata ist auf 10 Schlüssel begrenzt
  • Limits pro Transaktion und pro Tag legt das Vetox-Team fest; sie erscheinen schreibgeschützt im Tab „Settings“

Sicherheits-Checkliste

API-Schlüssel und Signing Secret gehören niemals in Client-Code. Bei einem Leak sofort rotieren.
Signatur gegen den Raw Body prüfen und Auslieferungen älter als ~5 Minuten ablehnen.
Niemals auf die /deduct-Antwort hin ausliefern — die Belastung ist erst mit confirmation.completed endgültig.
Fordere nur die Scopes an, die du wirklich nutzt, und aktiviere die IP-Allowlist.

Fehlerbehebung

Die Mitgliedschaft des Inhabers ist abgelaufen. Sie wird bei jedem Aufruf erneut geprüft.
Er lässt sich nicht wiederherstellen — gespeichert wird nur ein Hash. Rotiere für einen neuen.
Akzeptiere während der 24-stündigen Überlappung beide Secrets.
Der Nutzer hat sie nicht freigegeben. Bestätigungen verfallen nach 10 Minuten.
Ein Projekt braucht Callback-URL und Signing Secret. Mit nur einem von beiden wird nichts ausgeliefert.
Das ist die Abrechnungsgebühr. Nutze Beträge von 5 Vito oder weniger, um sie zu vermeiden, oder kalkuliere sie ein.
/v1/add wird aus deinem eigenen Guthaben finanziert, nicht aus dem Nichts erzeugt. Lade auf.

Vito

Guthaben, PIN und Gebühren.

Zahlungsanfragen

Was der Nutzer sieht, wenn du ihn belastest.