Cles API

IBANforge propose une offre gratuite via des cles API — 200 requetes/mois sur tous les endpoints. Aucune carte bancaire, aucun portefeuille crypto requis. Pour des volumes plus eleves, vous pouvez utiliser les micropaiements x402.

Générer une clé API gratuite

Envoyez une requête POST à /v1/keys/generate avec votre adresse email :

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

Utilisez une vraie adresse. Les domaines jetables ou fictifs (example.com, mailinator.com et le reste de la liste habituelle) sont refusés avec 400 disposable_email.

Réponse (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 est le secret : ifk_ suivi de 64 caractères hexadécimaux. Conservez-le en lieu sûr, il ne sera plus affiché.
• key_prefix en est les 8 premiers caractères. Il peut être journalisé sans risque, et c'est lui que le support vous demandera pour identifier une clé.

Si la demande de clé est refusée

La première clé d'un réseau reste instantanée. Au-delà, deux gardes protègent l'offre gratuite contre la fabrication de clés en série, et toutes deux répondent avec un champ error lisible par une machine.

403 verification_required : confirmez votre boîte mail

Ce cas survient dès qu'une clé a déjà été émise depuis votre réseau récemment (NAT partagé d'un bureau, université, VPN, opérateur mobile, ou simplement vous qui demandez une deuxième clé). L'API envoie alors un code à 6 chiffres à l'adresse indiquée et répond :

{
  "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\"}."
}

Renvoyez la même requête avec un champ code dans les 15 minutes :

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

Un code correct renvoie le 201 habituel et la clé. Un code faux renvoie 403 verification_failed avec un champ reason :

Ne renvoyez pas la requête sans code juste pour réessayer : cela envoie un nouveau code à chaque fois, et le nombre de codes envoyés à une même adresse par jour est plafonné.

429 : trop de clés demandées

{
  "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 (une clé par adresse et par jour) et verification_rate_limited (trop de codes demandés) sont les deux autres 429 de cet endpoint. Dans les trois cas : les clés que vous détenez déjà continuent de fonctionner, les crédits prépayés sont instantanés, et le paiement à l'appel x402 ne demande aucune clé.

Les autres refus

Rien de tout cela ne s'applique aux deux voies payantes : les packs de crédits prépayés et le paiement à l'appel x402 n'émettent aucune clé gratuite et ne passent par aucune vérification.

Utiliser votre clé API

Transmettez la clé dans l'en-tête Authorization en tant que token Bearer :

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_… fonctionne aussi, si l'en-tête Bearer est malcommode dans votre client.

La clé fonctionne sur tous les endpoints payants :

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

Les offres en un coup d'oeil

Les 200 requetes gratuites sont partagees entre tous les endpoints et se reinitalisent le 1er de chaque mois. La validation par lot compte 1 requete par IBAN — un lot de 50 IBANs consomme 50 requetes (ou 50 credits prepayes), la meme regle que le prix x402 par IBAN.

Vérifier votre consommation

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

Réponse (200 OK)

{
  "used": 47,
  "limit": 200,
  "remaining": 153,
  "month": "2026-08",
  "key_prefix": "ifk_3f9c1a7e"
}

month est le mois calendaire auquel se rapportent les compteurs (YYYY-MM), et ils se réinitialisent le 1er. Cet endpoint est gratuit et ne consomme pas de quota.

Surveiller votre quota

Chaque réponse authentifiée porte vos compteurs, en cas de succès comme de refus, pour que vous puissiez réagir avant le mur plutôt qu'au moment où vous le heurtez :

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

Les chiffres sont le solde une fois la requête réglée : un appel rejeté en 4xx est remboursé, et ces en-têtes tiennent déjà compte du remboursement. Si vous préférez interroger plutôt que lire des en-têtes, GET /v1/keys/usage renvoie les mêmes nombres, et c'est gratuit.

Lorsque votre quota est depasse

Votre intégration ne tombe pas sur un cul-de-sac. Une fois les 200 requêtes mensuelles épuisées, l'API répond 402 Payment Required (x402) plutôt qu'un 429 sec, avec des en-têtes qui disent exactement ce qui s'est passé :

X-Quota-Exhausted: true
X-Quota-Used: 200
X-Quota-Limit: 200
X-Quota-Month: 2026-08

Le corps du 402 liste vos trois options, lisibles par machine :

1. Acheter un pack de crédits prépayés — par carte sur la page tarifs, ou en USDC via POST /v1/credits/buy/1k|5k|25k. Les crédits n'expirent jamais et s'attachent à votre clé existante.
2. Payer à l'appel via x402 — un client compatible x402 paie automatiquement en USDC, sans changer de clé. Voir Paiements x402.
3. Attendre la réinitialisation mensuelle — le quota se réinitialise le 1er de chaque mois.

Exemple TypeScript

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);

Exemple Python

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)

Etapes suivantes

• Micropaiements x402 — paiement a l'appel illimite avec USDC
• Validation IBAN — reference complete de l'endpoint
• Reference des erreurs — tous les codes d'erreur et le depannage