API-Schlüssel

IBANforge hat zwei kostenlose Stufen, und die erste verlangt gar nichts. Ein POST mit leerem Body liefert einen ifk_-Schlüssel für 25 Anfragen pro Monat: keine Adresse, keine Karte, nichts zu bestätigen. Ein weiterer Schritt — ein zugesandter Code — hebt denselben Schlüssel dauerhaft auf 200 Anfragen pro Monat. Darüber hinaus: x402-Mikrozahlungen oder Prepaid-Pakete.

Diese Seite ist die Referenz allein zu Schlüsseln. Wenn Sie noch keinen Aufruf gemacht haben, sind die Ersten Schritte der kürzere Weg: der Aufruf ohne Schlüssel, dieser Schlüssel, die Antwort Block für Block gelesen und ein Stapel von 100 — in zehn Minuten.

Vor dem Schlüssel: 25 Aufrufe pro Woche, ohne Schlüssel

POST /v1/iban/validate mit einer echten iban und ganz ohne Zugangsdaten wird vollständig beantwortet — samt Anreicherung — 25-mal pro Woche für die Adresse, von der der Aufruf kommt. Die Woche ist die ISO-Woche in UTC: Der Zähler beginnt am Montag um 00:00 UTC wieder bei null.

curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -d '{"iban": "CH10 0023 0000 0000 1234 5"}'

Die Antwort enthält einen trial-Block mit der Zahl der in dieser Woche verbleibenden Aufrufe, dem Zeitpunkt der Rücksetzung (resets_at) und der Anfrage, die den Schlüssel erzeugt. Eine Kostprobe, keine Stufe: über 25 Aufrufe in der Woche antwortet der Endpunkt bis Montag wieder mit 402 und cause.reason: "trial_exhausted".

Die Kostprobe ohne Schlüssel und der Schlüssel sind zwei verschiedene Türen. Die Kostprobe gilt nur auf dieser Route und kommt jeden Montag zurück. Der Schlüssel gilt auf allen Endpunkten: Batch, BIC, Schweizer Clearing, Compliance. Er wird pro Monat gezählt, und erst die Beanspruchung hebt ihn auf 200 Anfragen pro Monat. Wer nur ein paar IBANs pro Woche einzeln prüft, kommt mit der Kostprobe ohne Schlüssel womöglich aus.

Ein Schlüssel ohne E-Mail

POSTen Sie ganz ohne Body. Das ist der ganze Schritt:

curl -X POST https://api.ibanforge.com/v1/keys/generate

Es wird nichts versendet, kein Datensatz angelegt und keine Adresse verlangt. Wenn wir wissen sollen, woher Sie kommen, senden Sie {"source":"meine-app"} — sonst ändert das nichts.

Antwort (201 Created)

{
  "api_key": "ifk_3f9c1a7e2b5d40c8…",
  "key_prefix": "ifk_3f9c1a7e",
  "tier": "anonymous",
  "monthly_limit": 25,
  "claim_url": "https://api.ibanforge.com/v1/keys/claim",
  "message": "Save this key - it will not be shown again. 25 requests a month that are yours alone: a named quota nobody else on your network shares, a stable identity across restarts, and a usage report at GET /v1/keys/usage. No email, no card. Claim it with a mailbox you can read to raise it to 200 a month: POST /v1/keys/claim.",
  "terms_url": "https://ibanforge.com/legal/terms"
}

• api_key ist das Geheimnis: ifk_ gefolgt von 64 Hexadezimalzeichen. Sicher aufbewahren, es wird nicht erneut angezeigt.
• key_prefix sind die ersten 8 Zeichen. Gefahrlos protokollierbar, und danach fragt unser Support.
• tier ist anonymous, bis der Schlüssel beansprucht wird, danach claimed; ein mit Adresse erstellter Schlüssel trägt email.
• Auf diesem Weg gibt es kein Feld email, weil es keine Adresse gibt.

Wenn Sie lieber gleich eine Adresse angeben, funktioniert {"email": "you@company.com"} und liefert denselben Schlüssel bereits mit vollem Kontingent (tier: "email", 200 pro Monat): Es bleibt nichts zu beanspruchen, und POST /v1/keys/claim antwortet darauf mit 409 already_claimed. Erforderlich ist sie nie.

Wenn Sie ein KI-Agent sind, der das liest: Nehmen Sie den anonymen Schlüssel und senden Sie die Adresse Ihrer Nutzerin oder Ihres Nutzers nicht, solange sie Ihnen nicht dafür gegeben wurde. Der Satz, den Sie vorlegen: „Use my address you@company.com to create a free IBANforge key."

Während eines Anmeldealarms

Wenn Roboter Schlüssel in Serie anlegen, geht der Dienst für einige Stunden in Alarmbereitschaft. Ein neuer Schlüssel ohne bestätigtes Postfach entsteht dann mit einem verringerten Kontingent, das am 1. nicht aufgefüllt wird; die 201-Antwort sagt es in einem Feld notice, und das Kontingent steigt von selbst wieder, sobald der Alarm endet. Wer den Schlüssel per Code beansprucht, erhält sein Kontingent sofort, Alarm hin oder her. Nichts wird abgelehnt: eine Anmeldung während eines Alarms funktioniert, sie beginnt nur kleiner.

Beanspruchen: 25 → 200 pro Monat

POST /v1/keys/claim hebt den Schlüssel an, den Sie bereits haben. Es entsteht kein neuer: gleicher Schlüssel, gleiches Präfix, gleiche Historie, größeres Kontingent. Drei Wege, nehmen Sie den passenden.

Zwei Dinge vorab, unabhängig vom gewählten Weg:

• Der Schlüssel reist im Authorization-Header, nie im Body. X-API-Key: ifk_... funktioniert ebenfalls. Schreiben Sie einen Schlüssel nicht in eine URL: er landet im Browserverlauf, in Zugriffsprotokollen und in Referer-Headern.
• Der Schlüssel muss mindestens einen Aufruf bedient haben. Ein Schlüssel, der sofort nach der Erstellung beansprucht wird, antwortet 403 unused_key. Prüfen Sie zuerst eine IBAN damit — dieser Aufruf gehört ohnehin zu Ihrem Kontingent.

Und ein Hinweis darauf, was jeder Weg gewährt, denn sie sind nicht gleichwertig:

1. Ein 6-stelliger Code per E-Mail

curl -X POST https://api.ibanforge.com/v1/keys/claim \
  -H "Authorization: Bearer ifk_3f9c1a7e2b5d40c8…" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

Antwortet 202 Accepted und schickt einen 6-stelligen Code:

{
  "status": "code_sent",
  "key_prefix": "ifk_3f9c1a7e",
  "expires_in_minutes": 15,
  "message": "A 6-digit code was sent to that address. Repeat this request within 15 minutes as {\"email\":\"...\",\"code\":\"123456\"} to raise this key to 200 requests a month."
}

Wiederholen Sie den Aufruf binnen 15 Minuten mit dem Code:

curl -X POST https://api.ibanforge.com/v1/keys/claim \
  -H "Authorization: Bearer ifk_3f9c1a7e2b5d40c8…" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "code": "123456"}'

Ein richtiger Code antwortet 200 mit claimed: true, tier: "claimed", basis: "monthly" und dem neuen Kontingent. Gleicher Schlüssel, nichts zu ersetzen.

Verwenden Sie eine echte Adresse. Wegwerf- und Platzhalter-Domains (example.com, mailinator.com und der übliche Rest) werden mit 400 disposable_email abgelehnt, eine Domain ohne Mailserver mit 400 undeliverable_email. Eine Adresse allein beansprucht nie einen Schlüssel — nur ein zurückgegebener Code tut das.

Ein falscher Code antwortet 403 verification_failed mit einem reason-Feld:

Eine Adresse beansprucht einen Schlüssel zur Zeit, und eine Beanspruchung pro Tag: Eine Adresse, die bereits einen aktiven kostenlosen Schlüssel trägt oder in den letzten 24 Stunden einen anderen beansprucht hat, erhält 409 already_claimed_elsewhere. Das ist die Fair-Use-Regel der AGB §6(e), gemessen an der Person statt am Postfach. Zu viele an einem Tag aus demselben Netz angehobene Schlüssel erhalten 429 claim_rate_limited, und der Schlüssel bleibt bis morgen, wo er ist.

2. Eine x402-Zahlung

Eine x402-Abrechnung, die mit dem Schlüssel vorgelegt wird, beansprucht ihn. Nichts zu senden, gar keine Adresse. Die Schwelle ist der Katalogpreis dessen, was die Beanspruchung gewährt: gering und in einem Aufruf zu begleichen.

3. Ein Prepaid-Paket, mit dem Schlüssel gekauft

Ein Paket, das mit vorgelegtem Schlüssel gekauft wird, lädt genau diesen Schlüssel auf und gewährt kein Gratiskontingent: Ein Kauf schafft nie eines. Erst beanspruchen, dann kaufen. Ein anonymer Schlüssel, der Guthaben kauft, verlässt die anonyme Stufe endgültig: Er behält sein Guthaben und kein monatliches Gratiskontingent, und POST /v1/keys/claim antwortet dann mit 409 already_claimed. Zuerst per zugesandtem Code beansprucht, behält derselbe Schlüssel seine 200 pro Monat und nutzt sein Guthaben, sobald der Monat verbraucht ist (siehe unten, «Einen Schlüssel aufladen»).

Der x402-Weg gewährt 200 Anfragen einmalig, nicht 200 pro Monat. GET /v1/keys/usage meldet dann basis: "lifetime", und die Zähler laufen über die ganze Lebensdauer des Schlüssels statt über den Kalendermonat. Der zugesandte Code ist der wiederkehrende Weg, und er kostet nichts: Wer ein Postfach lesen kann, fährt damit besser.

Die Rotation erhält die Stufe

POST /v1/keys/rotate gibt ein neues Geheimnis für denselben Inhaber zurück. Ein beanspruchter Schlüssel bleibt beansprucht und behält seine 200 pro Monat; ein anonymer bleibt anonym. Rotation ist kein Weg, ein Kontingent zurückzusetzen.

Wenn eine Schlüsselanfrage abgelehnt wird

Der anonyme Weg hat einen einzigen Wächter: die Zahl kostenloser Schlüssel, die ein einzelnes Netz an einem Tag erzeugen darf. Darüber hinaus antwortet POST /v1/keys/generate mit 429:

{
  "error": "key_creation_limit",
  "message": "At most 3 free keys per network per day — existing keys keep working. Need more capacity today? Prepaid credits are instant ($4 per 1,000, POST /v1/credits/buy/1k) and x402 pay-per-call needs no key at all."
}

Bereits ausgestellte Schlüssel funktionieren weiter, Prepaid-Guthaben ist sofort verfügbar, und x402 Pay-per-Call braucht überhaupt keinen Schlüssel.

403 verification_required: nur wenn Sie eine Adresse angegeben haben

Wenn Sie eine Adresse angeben und aus Ihrem Netz kürzlich bereits ein Schlüssel ausgestellt wurde (gemeinsames Büro-NAT, Universität, VPN, Mobilfunkanbieter, oder schlicht Sie selbst beim zweiten Schlüssel), schickt die API einen 6-stelligen Code an diese Adresse und antwortet:

{
  "error": "verification_required",
  "message": "A key was already issued from this network recently, so this one needs a verified mailbox: we sent a 6-digit code to you@company.com. Repeat this request within 15 minutes as {\"email\": \"...\", \"code\": \"123456\"}."
}

Senden Sie dieselbe Anfrage erneut mit einem code-Feld, innerhalb von 15 Minuten. Die Werte von reason sind die aus der Tabelle oben, dazu too_many_attempts nach 5 falschen Codes: einmal gesperrt, lehnt die Abfrage auch den richtigen Code ab, und nur eine neue Anfrage ohne code hilft.

Senden Sie die Anfrage nicht ohne code erneut, nur um es nochmals zu versuchen: das verschickt jedes Mal einen neuen Code, und die Zahl der Codes pro Adresse und Tag ist gedeckelt. Dieser ganze Schritt entfällt, wenn Sie keine Adresse senden: der anonyme Weg verschickt nie etwas.

Die übrigen Ablehnungen

Nichts davon betrifft die beiden kostenpflichtigen Wege: Prepaid-Guthabenpakete und x402 Pay-per-Call stellen keinen kostenlosen Schlüssel aus und durchlaufen keine Bestätigung.

Ihren API-Schlüssel verwenden

Übermitteln Sie den Schlüssel im Authorization-Header als Bearer-Token:

curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ifk_3f9c1a7e2b5d40c8…" \
  -d '{"iban": "CH10 0023 0000 0000 1234 5"}'

X-API-Key: ifk_… funktioniert ebenfalls, falls ein Bearer-Header in Ihrem Client unpraktisch ist.

Der Schlüssel funktioniert auf allen kostenpflichtigen Endpunkten:

• POST /v1/iban/validate
• POST /v1/iban/batch
• GET /v1/bic/:code
• POST /v1/iban/compliance
• GET /v1/ch/clearing/:iid

Die Angebote im Überblick

Namensnennung auf beiden kostenlosen Stufen. Jede Antwort eines kostenpflichtigen Endpunkts, die über einen kostenlosen Schlüssel läuft — anonym oder beansprucht —, trägt ein Objekt attribution (text, url, note). Wenn Sie diese Ergebnisse Menschen zeigen (eine Seite, ein Bildschirm, ein Dokument), blenden Sie „Powered by IBANforge" mit dem Link ein; ein Ergebnis, das in Ihrem Backend bleibt, schuldet nichts. Bezahlte Tarife tragen keine Namensnennung.

Das Kontingent wird über alle Endpunkte geteilt und setzt sich auf Basis monthly am 1. jedes Monats zurück (ein gegen eine Zahlung angehobener oder während eines Alarms entstandener Schlüssel trägt basis: lifetime und setzt sich nicht zurück). Batch-Validierung zählt 1 Anfrage pro IBAN — ein Batch mit 50 IBANs verbraucht 50 Anfragen (oder 50 Prepaid-Credits), dieselbe Regel wie der x402-Preis pro IBAN.

Ihre Nutzung prüfen

curl https://api.ibanforge.com/v1/keys/usage \
  -H "Authorization: Bearer ifk_3f9c1a7e2b5d40c8…"

Antwort (200 OK)

{
  "used": 7,
  "limit": 25,
  "remaining": 18,
  "month": "2026-09",
  "key_prefix": "ifk_3f9c1a7e",
  "basis": "monthly",
  "tier": "anonymous",
  "claim": {
    "url": "https://api.ibanforge.com/v1/keys/claim",
    "raises_limit_to": 200,
    "methods": ["email_code", "x402", "credits"],
    "paid_so_far_usd": 0,
    "paid_needed_usd": 1
  }
}

limit ist 25 bei einem anonymen und 200 bei einem beanspruchten Schlüssel; tier sagt, welcher vorliegt. basis sagt, welche Obergrenze wirklich gilt: monthly ist der Normalfall mit Reset am 1., lifetime gehört zu einem per Zahlung beanspruchten Schlüssel — seine 200 zählen einmalig über alle Monate und werden nicht aufgefüllt — und credits bezeichnet einen aus einem Kauf entstandenen Schlüssel, der nur sein Prepaid-Guthaben nutzt: gegen limit wird nichts durchgesetzt. Der claim-Block wird nur bei einem noch beanspruchbaren Schlüssel mitgeliefert.

Ein Schlüssel mit Kontingent und Guthaben, etwa ein aufgeladener Gratisschlüssel, behält die basis seines Kontingents und trägt zusätzlich credits_remaining, credits_total und billing_order: "allowance_then_credits". Bei jedem Schlüssel trägt topup die Kartenlinks, die genau diesen Schlüssel aufladen.

month ist der Kalendermonat, zu dem die Zähler gehören (YYYY-MM). Die Kostprobe ohne Schlüssel hat hier keinen Schlüssel abzufragen: Ihre Zähler laufen pro Woche (ISO-Woche in UTC, Rücksetzung am Montag um 00:00 UTC), und in ihrem 402 trial_exhausted trägt das Feld cause.quota.month den Wert week. Eine ohne Schlüssel bediente Antwort trägt X-Trial-Period: week; der 402 trägt keinen X-Trial-*-Header. Ohne Schlüssel antwortet dieser Endpunkt mit 401 missing_key, mit einem unbekannten oder inaktiven Schlüssel mit 401 invalid_key; GET /v1/keys/report, GET /v1/credits/balance und POST /v1/keys/claim antworten ebenso (die Beanspruchung nimmt einen wegen einer Welle automatischer Anmeldungen gesperrten Schlüssel weiterhin an, denn sie holt ihn zurück). POST /v1/keys/revoke und POST /v1/keys/rotate antworten ohne Schlüssel mit 401 missing_key und bei einem unbekannten oder bereits widerrufenen mit 404 invalid_key. Dieser Endpunkt ist kostenlos und verbraucht kein Kontingent.

Ihre Kontoseite

ibanforge.com/account zeigt alle Schlüssel, die mit Ihrer E-Mail-Adresse verknüpft sind, ohne dass Sie einen Schlüssel einfügen müssen. Für jeden Schlüssel: der Tarif, was in diesem Monat übrig ist oder das verbleibende Guthaben, die Aufrufe dieses Monats, der letzte Aufruf, die von uns gesendeten Hinweise und, bei einem Pro- oder Editor-/OEM-Abo, der Link, mit dem Sie es verwalten. Öffnen Sie einen Schlüssel, um seine letzten 30 Tage zu sehen: die Aufrufe, die erreichten Endpunkte und was mit welcher Ursache fehlgeschlagen ist. Die Seite zeigt die ersten Zeichen eines Schlüssels, nie den Schlüssel selbst.

Zur Anmeldung geben Sie die Adresse ein, die mit Ihren Schlüsseln verknüpft ist: die Adresse, die Sie beim Erstellen oder Beanspruchen eines Schlüssels angegeben haben, oder die beim Bezahlen eingegebene. Wir senden Ihnen einen 6-stelligen Code, 15 Minuten gültig, den Sie auf der Seite eingeben. Kein Passwort und kein Link in der E-Mail. Der Code wird verschickt, ob die Adresse einen Schlüssel trägt oder nicht: Die Seite verrät also niemandem, welche Adressen einen haben.

Die Sitzung dauert 7 Tage ab der Anmeldung; danach fragt die Seite nach einem neuen Code. Sie liegt in einem Anmelde-Cookie, das zu nichts anderem dient. Abmelden beendet sie in diesem Browser, Überall abmelden beendet alle Sitzungen Ihrer Adresse.

Zahlungsbelege. Unter Ihren Schlüsseln listet Zahlungsbelege die mit Ihrer Adresse bezahlten Guthabenpakete und Abos auf, die neuesten zuerst. Eine Kartenzahlung erscheint unter der beim Bezahlen angegebenen Adresse, gleich auf welchem Schlüssel sie gelandet ist; eine USDC-Zahlung unter der Adresse ihres Schlüssels. Bei einem per Karte bezahlten Paket öffnet Beleg den Zahlungsbeleg bei Stripe, unserem Zahlungsdienstleister. Bei einem Pro-Abo öffnet Rechnungen das Kundenportal von Stripe, in dem seine Rechnungen liegen. Eine Rechnung auf Ihr Unternehmen, mit seiner Mehrwertsteuernummer, stellen wir auf Anfrage an support@ibanforge.com aus.

Ein Schlüssel ohne Adresse, ohne Adresse erstellt oder gekauft, gehört zu keinem Konto: Fügen Sie ihn stattdessen auf derselben Seite ein. Er geht direkt von Ihrem Browser an die API und nirgendwohin sonst. Sie können auch jederzeit einen Schlüssel einfügen, statt sich anzumelden.

Einen Schlüssel erneuern oder widerrufen erfordert weiterhin den Schlüssel selbst: Fügen Sie ihn auf dieser Seite ein oder senden Sie ihn an POST /v1/keys/rotate bzw. POST /v1/keys/revoke. Die Sitzung liest nur; sie ändert keinen Schlüssel und kann einen verlorenen Schlüssel nicht zurückgeben.

Die Seite ruft sieben öffentliche Routen auf, POST /v1/account/code, POST /v1/account/session, GET /v1/account/overview, GET /v1/account/keys/report, GET /v1/account/receipts, GET /v1/account/receipt und POST /v1/account/logout, beschrieben im OpenAPI-Vertrag. Sie sind für eine Person im Browser gedacht: Mit einem Schlüssel in der Hand liefern GET /v1/keys/usage und GET /v1/keys/report dieselben Zahlen.

Ihr Kontingent im Blick behalten

Jede Antwort auf einen Monatsschlüssel trägt Ihre Zähler mit, bei Erfolg wie bei Ablehnung, damit Sie handeln können bevor Sie an die Grenze stossen und nicht erst dann (ein Schlüssel mit Prepaid-Guthaben trägt stattdessen X-Credits-Remaining und X-Credits-Total):

X-Quota-Used: 7
X-Quota-Limit: 25
X-Quota-Remaining: 18
X-Quota-Month: 2026-09

Die Zahlen sind der Stand nach Abschluss der Anfrage: ein mit 4xx abgelehnter Aufruf wird erstattet, und diese Header berücksichtigen die Erstattung bereits. Wer lieber abfragt als Header liest: GET /v1/keys/usage liefert dieselben Zahlen, kostenlos.

Einen Schlüssel aufladen

Ein Paket landet auf dem Schlüssel, den Sie schon haben: An Ihrer Integration ändert sich nichts, und das Guthaben verfällt nie.

• Per Karte: Öffnen Sie einen der Links unter topup.by_card (in GET /v1/keys/usage, GET /v1/credits/balance und credit_packs.topup_this_key in einem 402 für den Schlüssel) oder die Schaltflächen Diesen Schlüssel aufladen auf Ihrer Kontoseite. Jeder Link trägt die Aufladereferenz des Schlüssels, nie den Schlüssel selbst: Er erlaubt nur, für diesen Schlüssel zu zahlen. Die Erfolgsseite nennt danach den aufgeladenen Schlüssel, und Sie erhalten eine Bestätigung per E-Mail.
• In USDC: POST /v1/credits/buy/1k|5k|25k mit wie gewohnt vorgelegtem Schlüssel. Das Vorlegen kostet keine Anfrage, die Antwort trägt same_key: true, und das Guthaben wird gutgeschrieben, sobald die Zahlung abgewickelt ist. Ohne Schlüssel verkauft dieselbe Route einen neuen Schlüssel, wie die Preisseite.

credits_total zählt alles, was je auf den Schlüssel gekauft wurde, Aufladungen inbegriffen, und X-Credits-Total sagt dasselbe.

Bei einem Schlüssel mit beidem nutzt jeder Aufruf zuerst das Kontingent, dann das Guthaben; ein Batch, der vom einen ins andere übergeht, wird zwischen beiden aufgeteilt, ganz oder gar nicht. Jede abgerechnete Antwort sagt, was sie bezahlt hat:

X-Charged-From: allowance
X-Charged-From: credits
X-Charged-From: allowance+credits

Ist das Guthaben aufgebraucht, bleibt der Schlüssel gültig. Ein Gratisschlüssel kehrt zu seinem Monatskontingent zurück. Ein aus einem Kauf entstandener Schlüssel antwortet mit 402, cause.reason: "credits_exhausted" und den Links, die ihn aufladen (X-Credits-Topup-Url trägt den für das Paket mit 1.000 Credits).

Pro auf dem Schlüssel, den Sie schon haben. Dieselben Stellen tragen einen Pro-Link, der das Abonnement auf DIESEN Schlüssel legt: topup.pro in GET /v1/keys/usage und GET /v1/credits/balance, credit_packs.topup_this_key.pro in einem 402 an den Schlüssel, und die Kontoseite. Der Schlüssel hat dann 10.000 Anfragen pro Monat, die vor seinem restlichen Guthaben genutzt werden. Einem Schlüssel, der schon ein Abonnement trägt, wird der Link nicht angeboten. Eine Kündigung deaktiviert den Schlüssel nicht: Am Ende des bereits bezahlten Monats erhält er zurück, was er vor dem Abonnement hatte, sein Gratiskontingent, falls er eines hatte, und sein restliches Guthaben. Ein durch das Abonnement selbst entstandener Schlüssel antwortet dann mit 402 und den Links, die ihn aufladen oder erneut abonnieren, ohne ersetzt zu werden. Ein anonymer Schlüssel, der Pro nimmt, verlässt die anonyme Stufe und kann daher nicht mehr per E-Mail beansprucht werden; am Ende des Abonnements erhält er sein anonymes Monatskontingent zurück. Einer, der zuerst Guthaben gekauft hat, hatte sie schon endgültig verlassen, ohne Gratiskontingent.

Wenn Ihr Kontingent erschöpft ist

Ihre Integration landet nicht in einer Sackgasse. Sind die Anfragen des Monats aufgebraucht, antwortet die API mit 402 Payment Required (x402) statt einem harten 429 — mit Hinweis-Headern, die genau sagen, was passiert ist:

X-Quota-Exhausted: true
X-Quota-Used: 25
X-Quota-Limit: 25
X-Quota-Month: 2026-09

Der 402-Body listet Ihre Optionen maschinenlesbar auf:

1. Den Schlüssel beanspruchen — ist er noch anonym, hebt ihn ein zugesandter Code an, und das kostet nichts.
2. Diesen Schlüssel aufladen: per Karte mit den Links, die der 402 trägt (credit_packs.topup_this_key, X-Credits-Topup-Url), oder über Ihre Kontoseite, oder in USDC via POST /v1/credits/buy/1k|5k|25k mit vorgelegtem Schlüssel. Das Guthaben landet auf genau diesem Schlüssel und verfällt nie. Siehe oben, «Einen Schlüssel aufladen».
3. Pay-per-Call via x402 — ein x402-kompatibler Client zahlt automatisch in USDC, ohne Schlüsselwechsel. Siehe x402-Zahlungen.
4. Auf den monatlichen Reset warten — auf Basis monthly setzt sich das Kontingent am 1. zurück; ein gegen eine Zahlung angehobener oder während eines Alarms entstandener Schlüssel trägt basis: lifetime und tut es nicht.

TypeScript-Beispiel

const API_KEY = process.env.IBANFORGE_API_KEY;
 
const response = await fetch("https://api.ibanforge.com/v1/iban/validate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({ iban: "CH10 0023 0000 0000 1234 5" }),
});
 
const data = await response.json();
console.log(data);

Python-Beispiel

import os
import requests
 
API_KEY = os.environ["IBANFORGE_API_KEY"]
 
response = requests.post(
    "https://api.ibanforge.com/v1/iban/validate",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    },
    json={"iban": "CH10 0023 0000 0000 1234 5"},
)
 
data = response.json()
print(data)

Nächste Schritte

• Erste Schritte — der ganze Weg in zehn Minuten, vom Aufruf ohne Schlüssel bis zum Stapel von 100
• x402-Mikrozahlungen — unbegrenztes Pay-per-Call mit USDC
• IBAN-Validierung — vollständige Endpunktreferenz
• Fehlerreferenz — alle Fehlercodes und Fehlerbehebung