API Keys

IBANforge offers a free tier via API keys — 200 requests/month across all endpoints. No credit card, no crypto wallet required. For higher volumes, you can use x402 micropayments.

Generate a free API key

Send a POST request to /v1/keys/generate with your email address:

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

Response

{
  "key": "ifk_live_xxxxxxxxxxxxxxxxxxxx",
  "email": "you@example.com",
  "tier": "free",
  "quota": {
    "requests_per_month": 200,
    "used": 0,
    "resets_at": "2026-05-01T00:00:00.000Z"
  }
}

Your key starts with ifk_ (IBANforge Key). Store it securely — it will not be shown again.

Using your API key

Pass the key in the Authorization header as a Bearer token:

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

The key works on all paid endpoints:

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

Plans at a glance

The 200 free requests are shared across all endpoints and reset on the 1st of each month. Batch validation counts 1 request per IBAN — a batch of 50 IBANs uses 50 requests (or 50 prepaid credits), the same rule as the x402 per-IBAN price.

Check your usage

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

Response

{
  "tier": "free",
  "quota": {
    "requests_per_month": 200,
    "used": 47,
    "remaining": 153,
    "resets_at": "2026-05-01T00:00:00.000Z"
  }
}

Watching your quota

Every authenticated response carries your counters, on success as well as on refusal, so you can act before you reach the wall rather than when you hit it:

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

The figures are the balance after the request settled: a call rejected with a 4xx is refunded, and these headers already reflect the refund. If you prefer polling to reading headers, GET /v1/keys/usage returns the same numbers, and it is free.

When you exceed the quota

Your integration does not hit a hard dead-end. Once the 200 monthly requests are used up, the API answers 402 Payment Required (x402) instead of a blunt 429, with hint headers telling you exactly what happened:

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

The 402 body lists your three options in machine-readable form:

1. Buy a prepaid credit pack — by card on the pricing page, or in USDC via POST /v1/credits/buy/1k|5k|25k. Credits never expire and attach to your existing key.
2. Pay per call via x402 — an x402-compatible client pays automatically in USDC, no key change needed. See x402 Payments.
3. Wait for the monthly reset — the quota resets on the 1st of each month.

TypeScript example

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 example

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)

Next steps

• x402 Micropayments — unlimited pay-per-call with USDC
• IBAN Validation — full endpoint reference
• Error Reference — all error codes and troubleshooting