API-Schluessel

IBANforge bietet ein kostenloses Kontingent ueber API-Schluessel — 200 Anfragen/Monat auf allen Endpunkten. Keine Kreditkarte, keine Krypto-Wallet erforderlich. Fuer hoehere Volumen koennen Sie x402-Mikrozahlungen verwenden.

Kostenlosen API-Schlüssel generieren

Senden Sie eine POST-Anfrage an /v1/keys/generate mit Ihrer E-Mail-Adresse:

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

Verwenden Sie eine echte Adresse. Wegwerf- und Platzhalter-Domains (example.com, mailinator.com und der Rest der üblichen Liste) werden mit 400 disposable_email abgelehnt.

Antwort (201 Created)

{
  "api_key": "ifk_3f9c1a7e2b5d40c8…",
  "key_prefix": "ifk_3f9c1a7e",
  "email": "you@company.com",
  "monthly_limit": 200,
  "message": "Save this key — it will not be shown again.",
  "terms_url": "https://ibanforge.com/legal/terms"
}

• api_key ist das Geheimnis: ifk_ gefolgt von 64 Hexadezimalzeichen. Bewahren Sie ihn sicher auf, er wird nicht erneut angezeigt.
• key_prefix sind seine ersten 8 Zeichen. Er darf protokolliert werden, und danach fragt unser Support, um einen Schlüssel zu identifizieren.

Wenn die Schlüsselanfrage abgelehnt wird

Der erste Schlüssel aus einem Netzwerk bleibt sofort verfügbar. Danach schützen zwei Wächter das kostenlose Kontingent vor der Massenerzeugung von Schlüsseln, und beide antworten mit einem maschinenlesbaren error-Feld.

403 verification_required: Postfach bestätigen

Das passiert, sobald aus Ihrem Netzwerk kürzlich bereits ein Schlüssel ausgestellt wurde (gemeinsames Büro-NAT, Universität, VPN, Mobilfunkanbieter, oder schlicht Sie selbst beim zweiten Schlüssel). Die API schickt dann einen 6-stelligen Code an die angegebene 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:

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

Ein richtiger Code liefert das übliche 201 und den Schlüssel. Ein falscher liefert 403 verification_failed mit einem reason-Feld:

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.

429: zu viele Schlüssel angefordert

{
  "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 ($5 per 1,000, POST /v1/credits/buy/1k) and x402 pay-per-call needs no key at all."
}

rate_limited (ein Schlüssel pro Adresse und Tag) und verification_rate_limited (zu viele Codes angefordert) sind die beiden anderen 429 dieses Endpunkts. In allen drei Fällen gilt: bereits ausgestellte Schlüssel funktionieren weiter, Prepaid-Guthaben ist sofort verfügbar, und x402 Pay-per-Call braucht überhaupt keinen Schlüssel.

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

Die 200 kostenlosen Anfragen werden ueber alle Endpunkte geteilt und setzen sich am 1. jedes Monats zurueck. Batch-Validierung zaehlt 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": 47,
  "limit": 200,
  "remaining": 153,
  "month": "2026-08",
  "key_prefix": "ifk_3f9c1a7e"
}

month ist der Kalendermonat, zu dem die Zähler gehören (YYYY-MM); sie setzen sich am 1. zurück. Dieser Endpunkt ist kostenlos und verbraucht kein Kontingent.

Ihr Kontingent im Blick behalten

Jede authentifizierte Antwort traegt Ihre Zaehler mit, bei Erfolg wie bei Ablehnung, damit Sie handeln koennen bevor Sie an die Grenze stossen und nicht erst dann:

X-Quota-Used: 47
X-Quota-Limit: 200
X-Quota-Remaining: 153
X-Quota-Month: 2026-08

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

Wenn Ihr Kontingent erschoepft ist

Ihre Integration landet nicht in einer Sackgasse. Sind die 200 monatlichen Anfragen 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: 200
X-Quota-Limit: 200
X-Quota-Month: 2026-08

Der 402-Body listet Ihre drei Optionen maschinenlesbar auf:

1. Prepaid-Guthabenpaket kaufen — per Karte auf der Preisseite oder in USDC via POST /v1/credits/buy/1k|5k|25k. Guthaben verfällt nie und wird an Ihren bestehenden Schlüssel gebunden.
2. Pay-per-Call via x402 — ein x402-kompatibler Client zahlt automatisch in USDC, ohne Schlüsselwechsel. Siehe x402-Zahlungen.
3. Auf den monatlichen Reset warten — das Kontingent setzt sich am 1. jedes Monats zurueck.

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)

Naechste Schritte

• x402-Mikrozahlungen — unbegrenztes Pay-per-Call mit USDC
• IBAN-Validierung — vollstaendige Endpunktreferenz
• Fehlerreferenz — alle Fehlercodes und Fehlerbehebung