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@company.com"}'

Use a real address. Placeholder and throwaway domains (example.com, mailinator.com and the rest of the usual list) are refused with 400 disposable_email.

Response (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 is the secret: ifk_ followed by 64 hexadecimal characters. Store it securely, it will not be shown again.
• key_prefix is its first 8 characters. It is safe to log and it is what our support will ask for to identify a key.

If the key request is refused

The first key from a given network is instant. Beyond that, two guards protect the free tier from bulk key farming, and both answer with a machine-readable error field.

403 verification_required: confirm your mailbox

This lands whenever a key was already issued from your network recently (a shared office NAT, a university, a VPN, a mobile carrier, or simply you asking for a second key). The API mails a 6-digit code to the address you supplied and answers:

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

Send the same request again with a code field within 15 minutes:

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

A correct code returns the usual 201 and the key. A wrong one returns 403 verification_failed with a reason field:

Do not resend the request without a code just to retry: that mails a new code every time, and the number of codes we send to one address per day is capped.

429: you asked for too many keys

{
  "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 (one key per address per day) and verification_rate_limited (too many codes requested) are the two other 429s on this endpoint. In all three cases: keys you already hold keep working, prepaid credits are instant, and x402 pay-per-call needs no key at all.

The other refusals

None of this applies to the two paid rails: prepaid credit packs and x402 pay-per-call issue no free key and go through no verification.

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_3f9c1a7e2b5d40c8…" \
  -d '{"iban": "CH10 0023 0000 0000 1234 5"}'

X-API-Key: ifk_… works too, if a Bearer header is awkward in your client.

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_3f9c1a7e2b5d40c8…"

Response (200 OK)

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

month is the calendar month the counters belong to (YYYY-MM), and they reset on the 1st. This endpoint is free and does not consume quota.

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-08

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-08

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