# IBANforge

> IBANforge checks the bank behind an IBAN before you pay. It validates IBANs from all 89 IBAN countries and names the bank and its BIC, with the source of that answer. Where it reads the national register (Germany, Austria, Belgium, Slovakia, Czech Republic, Bulgaria, Switzerland and Liechtenstein), it also tells you whether the bank code is allocated at all; elsewhere it names the bank from a partial register or a composite map, and says that such an answer cannot rule a code out. For a SEPA bank it resolves, it gives the SEPA schemes that reach it (Credit Transfer, Instant, Direct Debit), from the EPC scheme registers when they list the bank and from the country otherwise (the answer says which), and says whether the EPC Verification of Payee (VoP) register lists the bank as ready to answer VoP requests. It does not check who holds the account: that name check belongs to the payee's bank, through VoP.

Not a name check (VoP, BAV, CoP), not proof that an account exists or is open, not a sanctions screening of the payee (bank and country only), not a licensed copy of the SWIFT BIC directory. The national check digits inside the BBAN are checked for France and Monaco (RIB key), Belgium, Italy and San Marino (CIN), Spain (DC) and the United Kingdom (modulus check): a wrong key shows in checks.national_check_digits and never turns valid to false. The Polish settlement-number check digit is checked with the bank code. The German account-number methods and the national keys of the other countries are not checked yet.

BIC directory, 121k+ entries (entries, not institutions): GLEIF and national registers, refreshed monthly, plus a public copy of the SWIFT directory frozen in January 2018 that still makes up about two thirds of the rows. Also 1,100+ Swiss BC-Nummern (SIX) · 89 IBAN countries · 900+ non-bank issuer classifications (EMI, payment institutions, digital banks). Live counts at https://api.ibanforge.com/llms.txt

## What IBANforge checks, country by country

- Checked against the national register, read in full: a code it does not hold comes back `not_allocated`, `authoritative: true`. Germany (Deutsche Bundesbank), Austria (Oesterreichische Nationalbank), Belgium (Banque nationale de Belgique), Slovakia (Národná banka Slovenska), Czech Republic (Česká národní banka, Zdroj: ČNB), Bulgaria (Bulgarian National Bank, bank code only), Switzerland and Liechtenstein (SIX BankMaster).
- A partial register: a hit names the holder, a miss is not a refusal (`authoritative: false`). Finland (Finance Finland, codes of banking groups), Italy (Banca d'Italia, registers of banks, payment and e-money institutions; a code it has struck off comes back `retired`, with its date and legal successor, never as a refusal), San Marino (Central Bank of the Republic of San Marino, operating banks) and Luxembourg (ABBL register of IBAN/BIC codes).
- A structural rule the authority publishes, not a register: Latvia and Gibraltar, where IBAN positions 5-8 are the first four characters of the BIC.
- Official identity of the bank, from its national bank code: France (European Central Bank list of monetary financial institutions) and Spain (Banco de España). Spain also: whether the code belongs to a payment or e-money institution in the EBA PSD2 register.
- United Kingdom: the Vocalink modulus check on the sort code and account number, and whether the bank is on the Bank of England list of banks authorised to take deposits.
- Poland: the check digit of the settlement number. Netherlands: whether the identifier belongs to a provider on the Betaalvereniging Nederland list of IBAN-issuing institutions.
- Every SEPA bank we resolve: whether the EPC Verification of Payee register lists it as ready (a bank absent from that register comes back `false`, which does not prove it ignores VoP requests); SCT, SCT Inst and SDD reachability from the EPC scheme registers where they list the bank (`sepa.basis: "epc_register"`), the country's schemes otherwise (`sepa.basis: "country_default"`).
- Every other IBAN country: structure, mod-97 and a composite BIC map, answered with `authoritative: false`.

## Three questions, three layers

1. Is the number well written? Structure and mod-97: free, offline with the MIT library `ibanforge` on npm, or GET /v1/iban/format.
2. Which bank is it, does its code exist, and can it be reached? That is IBANforge: the bank-code verdict (the national register where we read it, which can say "not allocated"; a partial register or a composite map elsewhere, which cannot; every validation says which), the bank and BIC with their source, the SEPA reachability and VoP register listing of that bank (from the EPC registers where they list it), e-money and virtual-IBAN detection, and bank-level sanctions.
3. Is the account open, and in this name? Only the payee's bank can answer, through Verification of Payee or an equivalent service. IBANforge tells you whether the EPC VoP register lists that bank as ready; it never runs the name check.

## Data sources and attribution

GLEIF · SIX BankMaster · SwiftCodes (MIT, a public copy of the SWIFT directory frozen in January 2018) · Deutsche Bundesbank · Oesterreichische Nationalbank · Banque nationale de Belgique · Národná banka Slovenska · Česká národní banka · Bulgarian National Bank · Banca d'Italia · Central Bank of the Republic of San Marino · Finance Finland · ABBL · European Central Bank · Banco de España · EBA · Betaalvereniging Nederland · NBP · EBA STEP2 · OFAC · EU · UN · FATF · EPC.
BIC-to-LEI relationship file (Mapping Table), developed by SWIFT and published by GLEIF: the notice its licence asks for, with the Mapping Table version loaded at the last monthly refresh, is served live at https://api.ibanforge.com/llms.txt
Dutch issuer list: Betaalvereniging Nederland, reused with attribution — a BIC or a bank code may be modified, withdrawn or added at any time, and the association does not guarantee the permanent accuracy of the list.
UK deposit-taking authorisation: Bank of England (List of Banks, 2026-08), used with the Bank of England's written permission. The month of the list in force is served live at https://api.ibanforge.com/llms.txt
Slovak bank codes: Národná banka Slovenska, Directory of identification codes for the domestic payment system (version 225, effective 2026-05-18), reproduced under the NBS site terms — the source is named and the file is not altered. The edition in force is served live at https://api.ibanforge.com/llms.txt
Czech bank codes: Zdroj: ČNB, Číselník kódů platebního styku v ČR, reproduced under the ČNB site terms — the ČNB is named as the source and the facts are not altered. The ČNB publishes each numbered edition ahead of its effective date and we apply it from that date; this static file does not follow the editions, so the edition in force and its date are served live at https://api.ibanforge.com/llms.txt
Italian bank codes: Banca d'Italia, Albi ed elenchi di vigilanza (open data, CC BY 4.0, https://creativecommons.org/licenses/by/4.0/), https://infostat.bancaditalia.it/GIAVAInquiry-public/ng/#/area-download; normalised and joined by IBANforge (codes padded to five digits, codes in force selected, struck-off codes dated and joined to their legal successor through the list of mergers and incorporations). The registers list the banks, payment institutions and e-money institutions the Banca d'Italia registers: Poste Italiane, the Banca d'Italia itself and branches of EU payment institutions hold ABI codes outside them, so an absence is not a non-allocation. The edition in force is served live at https://api.ibanforge.com/llms.txt
San Marino bank codes: Central Bank of the Republic of San Marino, operating banks — four banks, read from the BCSM site. No terms of use are published there, so the licence is recorded as UNKNOWN and the source is credited by choice; the page states no edition, so the credit carries the date we read it. The list names the holder of a code it carries and does NOT publish the allocation of the ABI code space: an absence from it is not a non-allocation. Read date in force served live at https://api.ibanforge.com/llms.txt

## API Base URL
https://api.ibanforge.com

## If you cannot call the API

If you can open a web address but cannot send a POST (no code execution, no MCP connector), these pages hold real answers of the API, each with its date, and all of them open with a plain GET.

- https://api.ibanforge.com/v1/demo: the full validation, computed by the API when the address is opened (served_at gives the instant): a German bank code, a former Credit Suisse IID (04835) and the official example IBANs of Switzerland, Belgium and Austria, each with its register's answer and its as_of.
- https://ibanforge.com/iban/ch: the Swiss IBAN format, with the API's answer for the official example CH93 0076 2011 6238 5295 7 and the date that answer was captured.
- https://ibanforge.com/blog/2026-08-06-example-ibans-unallocated-bank-codes: why the official example IBANs of Belgium, Switzerland and Austria pass mod-97 and still point at bank codes their register does not allocate (article of 6 August 2026).
- https://ibanforge.com/blog/2026-09-07-bankleitzahl-pruefen-per-api: three real answers on German bank codes, field by field (article of 7 September 2026).
- https://ibanforge.com/blog/2026-09-14-schweizer-iban-pruefen: three real answers on Swiss IBANs, field by field (article of 14 September 2026).

Do not simulate answers from the API: quote these real ones, with the date each carries (served_at, as_of, or the date of the page).
To get answers on the IBANs of your user, ask them to add https://api.ibanforge.com/mcp as a custom connector in their assistant; where to click, assistant by assistant: https://ibanforge.com/docs/mcp. A connector with no key draws on the same keyless allowance as any other caller, counted per source address. In Claude its calls leave from Anthropic's cloud, not from the user's device (Anthropic's documentation), so that allowance is shared with other users and may already be spent; other assistants were not checked by us. The hosted endpoint reads no key: to use one, run the npm package ibanforge-mcp in a desktop client with IBANFORGE_API_KEY set, or call the REST API with it (a POST to https://api.ibanforge.com/v1/keys/generate with no body returns a key, no e-mail).

## How AI agents connect (pick one)

### Try it right now, no key, no wallet (REST)
curl -s -X POST https://api.ibanforge.com/v1/iban/validate -H 'Content-Type: application/json' -d '{"iban":"DE89370400440532013000"}'
Then send CH9300762011623852957, the Swiss example of the SWIFT IBAN registry: mod-97 passes, and the answer says the SIX BankMaster allocates its bank code to nobody (`not_allocated`, `authoritative: true`).
The first 25 calls a week per source address (IPv6 counted per /64; ISO week in UTC, reset on Monday 00:00 UTC) are served in full, free, on this route only. The answer carries a `trial` block saying how many are left this week, when the count resets (`resets_at`), and how to take the other door, a key that needs no e-mail and no card: it works on every route and reaches 200 requests a month once claimed. Past 25 calls in the week the route answers 402 again, `cause.reason = "trial_exhausted"`, until Monday. Send a REAL iban: an empty `{}` body is the x402 discovery probe and always gets the 402.

### MCP server (stdio — easiest, no signup)
npx -y ibanforge-mcp
Claude Desktop / Cursor / Cline config:
{"mcpServers": {"ibanforge": {"command": "npx", "args": ["-y", "ibanforge-mcp"]}}}
Optional: set IBANFORGE_API_KEY=ifk_... in env. Get one with no e-mail: POST https://api.ibanforge.com/v1/keys/generate with no body at all (25 req/month), then POST /v1/keys/claim with the key in the Authorization header to raise it to 200 a month.

### MCP server (streamable HTTP — no install)
POST https://api.ibanforge.com/mcp  (JSON-RPC: initialize → tools/list → tools/call)

### OpenAI agents (no Custom GPT or ChatGPT Plus needed)
Agents SDK: point MCPServerStreamableHttp at the MCP URL above — the 11 tools auto-load.
Function-calling (Chat Completions / Responses): wire tools to the OpenAPI at /openapi.json.

### Pay-per-call without an API key (x402, USDC on Base L2)
GET https://api.ibanforge.com/.well-known/x402 returns the full catalog. Any agent with a Base wallet can discover, pay, and call.
Zero to first payment in 3 steps (wallet with budget → USDC on Base → one $4 payment for 1,000 credits): https://ibanforge.com/docs/pay-as-an-agent?src=llms

## 11 MCP tools
- validate_iban — validate one IBAN + enrich (bank-code verdict, BIC with its source, issuer EMI/vIBAN, SEPA and VoP readiness, risk, Swiss bc_nummer). Cost: $0.005
- batch_validate_iban — up to 100 IBANs in one call. Cost: $0.002 USDC per IBAN via x402 (e.g. 100 = $0.20); on a key, a credit pack or Pro, each IBAN in the batch uses one request or credit
- lookup_bic — resolve a BIC/SWIFT into bank, country, city, LEI. Cost: $0.003
- lookup_ch_clearing — Swiss BC-Nummer / IID → institution, address, full rail participation (SIC, euroSIC, CHF instant, LSV+/BDD), QR-IID, for every IID of the SIX BankMaster, refreshed monthly. Cost: $0.003
- check_compliance — sanctions lists (OFAC, EU, UN) on the bank (BIC8), the country against a fixed list of sanctioned jurisdictions, never the payee's name + FATF + SEPA Instant + VoP readiness + risk score 0-100. Informational, not regulated AML/CFT. Cost: $0.02
- validate_payment_reference — RF/ISO 11649, Swiss QRR, Belgian OGM/VCS, Finnish viitenumero checksums against the dated document that publishes each rule, plus the QRR/QR-IBAN pairing verdict. Cost: free
- check_postal_address — ISO 20022 postal address against one rail's published rules (sps, hvps_plus, fedwire), one finding per rule with its source and date. Cost: free
- check_swiss_qr_bill — Swiss QR-bill payload check: header, QR-IBAN and reference pairing, checksums, structured (S) versus combined (K) addresses ahead of 14.11.2026, with a proposed structured form. Free.
- send_feedback — report incorrect data or claim an x402 refund, no account. Cost: free
- request_api_key — open a key request a human approves in a browser: no e-mail, no card, no account. Free, and it works even after the free allowance is spent. Cost: free
- poll_api_key — collect the key once a human has approved it, handed over exactly once, with the config line to paste. Cost: free

## REST endpoints
- POST /v1/iban/validate — single IBAN, full enrichment ($0.005; first 25 a week per source address (IPv6 counted per /64) free, no key — see the keyless trial above)
- POST /v1/iban/batch — up to 100 IBANs ($0.002 USDC each via x402; one credit per IBAN on a key or a credit pack)
- GET  /v1/bic/{code} — BIC/SWIFT lookup with LEI ($0.003)
- GET  /v1/ch/clearing/{iid} — Swiss clearing lookup ($0.003)
- GET  /v1/gb/firm/{frn} — one UK-regulated firm by Firm Reference Number, from the FCA Financial Services Register: name, status and its date, business type, Companies House number, PSD/EMD status, notices; credited, dated, cached one day ($0.003; answers 503 not_configured, uncharged, on a deployment without the Register API credential)
- POST /v1/iban/compliance — bank-level sanctions (OFAC, EU, UN) + FATF + SEPA + VoP readiness + risk ($0.02)
- GET  /v1/iban/format?iban=... — free mod-97 + structure check (no auth)
- GET  /v1/iban/structure[/{country}] — free IBAN templates for 89 countries (no auth)
- GET|POST /v1/reference/validate — free structured payment reference check: RF/ISO 11649, Swiss QRR, Belgian OGM/VCS, Finnish viitenumero (no auth)
- POST /v1/address/check — free ISO 20022 postal address conformity check: sps, hvps_plus, fedwire (no auth)
- GET  /v1/credits/bundles — free, list prepaid credit bundles
- GET  /v1/demo — free example validations
- POST /v1/keys/generate (no body at all) — free API key, no e-mail, no card, 25 req/month
- POST /v1/keys/generate {"email":"you@company.com"} — same route, optional address, and the key is issued already at the full allowance (tier "email", nothing left to claim)
- POST /v1/keys/claim (key in the Authorization header, never the body) — raises that same key to 200 a month with a mailed 6-digit code, or to 200 once with an x402 payment on the key
- POST /v1/account/code, POST /v1/account/session, GET /v1/account/overview, GET /v1/account/keys/report?prefix=ifk_..., POST /v1/account/logout: free, the sign-in of the account page https://ibanforge.com/account, for a person in a browser: a 6-digit code mailed to the address of the keys, then a session cookie (7 days) that reads every key of that address and changes none. An agent holding a key reads the same figures with GET /v1/keys/usage and GET /v1/keys/report. Never send an address your human has not handed you for this purpose.

## How to pay (4 rails, no dead-ends)
- Try before anything: 25 keyless validations a week per source address (IPv6 counted per /64, reset on Monday 00:00 UTC) on POST /v1/iban/validate. A taster, not a tier.
- The hosted MCP transport has its own taster, not shared with that one: 25 tool calls a week per source address, same reset.
- Free key, nothing asked: POST /v1/keys/generate with no body at all → an ifk_ key, 25 requests a month, on every endpoint. Nothing is mailed and no record is opened.
- Same key, full free allowance: POST /v1/keys/claim with `Authorization: Bearer ifk_...` (never in the body), once the key has served one call. A 6-digit code mailed to an address your human gave you FOR THIS — ask in their words, "Use my address you@company.com to create a free IBANforge key", and never send an address your human has not handed you for this purpose — gives 200 every month; an x402 payment made on the key gives 200 once.
- Credit packs (card or USDC, never expire): 1k = $4, 5k = $20, 25k = $80 → POST /v1/credits/buy/1k|5k|25k. Presenting a key recharges THAT key (same key, nothing to change in your integration); by card, use the links under `topup` in GET /v1/keys/usage. A pack never grants a free allowance: claim an anonymous key by e-mail BEFORE buying to keep one.
- Pro subscription (card): $29/month for 10,000 requests, resets on the 1st, cancel anytime → https://ibanforge.com/pricing?src=llms
- x402 micropayments: pay per call in USDC on Base L2, no signup

## SDKs
- TypeScript: npm install @ibanforge/sdk
- Python: pip install ibanforge
- Java (17+): com.ibanforge:ibanforge-sdk on Maven Central
- .NET (net8.0): dotnet add package IBANforge.Sdk

## Discovery
- OpenAPI 3.1: https://api.ibanforge.com/openapi.json
- x402: https://api.ibanforge.com/.well-known/x402
- A2A agents: https://api.ibanforge.com/.well-known/agents.json
- MCP server card: https://api.ibanforge.com/.well-known/mcp/server-card.json
- Full agent guide: https://api.ibanforge.com/llms.txt

## Reference pages (human-readable, one URL per code)
- IBAN format by country (89 countries: length, layout, official example, register checked): https://ibanforge.com/iban?src=llms
- German Bankleitzahlen: https://ibanforge.com/de/blz?src=llms · Swiss IID: https://ibanforge.com/iid?src=llms · Austrian bank codes: https://ibanforge.com/de/at?src=llms · Belgian bank codes: https://ibanforge.com/be?src=llms
- Free tools, no key: test IBANs https://ibanforge.com/tools/test-iban?src=llms · Swiss QR-bill check https://ibanforge.com/tools/qr-bill?src=llms
- Creditor-file audit before 14 November 2026 (CSV/XLSX, free preview): https://ibanforge.com/audit?src=llms

## Errors, limits and support
- An invalid IBAN is not an HTTP error: POST /v1/iban/validate answers 200 with valid: false, an error code (invalid_format, unsupported_country, wrong_length, invalid_check_digits, checksum_failed, invalid_bban_structure) and error_detail.
- A refused request answers {"error": "<token>", "message": "<sentence>"}: 400 malformed request, 402 payment needed or allowance used up (cause.reason says which), 413 body over 256 KB, 429 over 100 requests a minute per IP address (Retry-After header). Statuses and shared codes: https://ibanforge.com/docs/errors?src=llms
- Support: support@ibanforge.com (quote your key_prefix, never the key) or https://github.com/cammac-creator/ibanforge/issues
- Live availability: https://ibanforge.com/status · Written SLA, for Editor/OEM subscriptions only (99.5% monthly availability, service credits): https://ibanforge.com/legal/sla

## Links
Docs: https://ibanforge.com/docs?src=llms · Playground: https://ibanforge.com/playground?src=llms · Pricing: https://ibanforge.com/pricing?src=llms · GitHub: https://github.com/cammac-creator/ibanforge · Status: https://ibanforge.com/status · SLA: https://ibanforge.com/legal/sla