IBANforge

The compliance API for AI agents. IBAN validation, BIC/SWIFT lookup, Swiss clearing (BC-Nummer / QR-IID / SIX BankMaster), EMI/vIBAN classification, SEPA Instant + VoP reachability, and risk scoring — exposed natively over MCP and x402 micropayments, with no API key signup required.

Code

121k+ BIC entries (39k+ LEI via GLEIF) · 1,100+ Swiss BC-Nummern (SIX) · 89 IBAN countries · <50ms p99

For AI agents — install in one click

Claude Desktop / Cursor / Cline / Continue / Windsurf

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop):

config.json

{
  "mcpServers": {
    "ibanforge": {
      "command": "npx",
      "args": ["-y", "ibanforge-mcp"]
    }
  }
}

Privacy by default: submitted IBANs are never stored — validation runs in memory, IPs are kept only as salted hashes, and telemetry deletes itself (12-month cap; erased 30 days after a customer terminates, contractually — DPA clause 4.7).

Optional: set IBANFORGE_API_KEY=ifk_... in env for the free tier (200 req/month). Without it the server uses the public/demo surface; combine with x402 micropayments for unlimited pay-per-call access without signup.

Claude Code (CLI)

Terminal

claude mcp add ibanforge npx -- -y ibanforge-mcp

Streamable HTTP (no install — for cloud-hosted agents)

Code

POST https://api.ibanforge.com/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

Standard JSON-RPC initialize + tools/list + tools/call flow. Use this when stdio is not an option (CI/CD, serverless, Vercel agents, etc.).

Tools

Tool	When to use it	Cost
`validate_iban`	User mentions an IBAN, a bank account, or a SEPA payment	$0.005
`batch_validate_iban`	List of IBANs, CSV cleanup, customer DB dedup, payout list triage	$0.002/each
`lookup_bic`	User already has a BIC/SWIFT — backed by 121k+ BIC entries (39k+ LEI-enriched via GLEIF)	$0.003
`lookup_ch_clearing`	Swiss BC-Nummer / IID — the deepest Swiss clearing data in any public API: full SIX BankMaster rail participation (SIC, euroSIC, CHF instant) + QR-IID	$0.003
`check_compliance`	Pre-flight risk triage before a SEPA / cross-border payment (sanctions + FATF + VoP)	$0.02
`validate_payment_reference`	RF/ISO 11649, Swiss QRR, Belgian OGM/VCS or Finnish viitenumero checksum, plus the QRR ↔ QR-IBAN pairing verdict	free
`check_postal_address`	An ISO 20022 address against one rail's published rules (`sps`, `hvps_plus`, `fedwire`), each finding citing its source	free
`send_feedback`	Report incorrect data or claim an x402 refund — the only tool that writes	free

The two free tools need no key, no wallet and no signup: they are the ones to try first.

Full descriptions with WHEN-to-use triggers are served live at /.well-known/mcp/server-card.json.

For AI agents — pay per call without an API key (x402)

IBANforge is x402-native. Any agent with a wallet on Base L2 can discover, pay, and call:

Discovery: GET https://api.ibanforge.com/.well-known/x402 returns the full catalog (endpoints, prices, asset, payTo, accepts).
Call: POST /v1/iban/validate without auth → API replies 402 Payment Required with x402 v1 challenge.
Pay: client signs a USDC transfer on Base (eip155:8453) and retries.
Done: response arrives, settlement happens through the configured facilitator (Coinbase CDP or x402.org).

No human in the loop, no sales call, no card. See the x402 spec.

SDKs

Pick your language:

Language	Package	Install	Source
TypeScript / JavaScript	`@ibanforge/sdk`	`npm install @ibanforge/sdk`	`sdks/typescript/`
Python	`ibanforge`	`pip install ibanforge`	`sdks/python/`
Java (17+)	`com.ibanforge:ibanforge-sdk`	Maven dependency, see README	`sdks/java/`
.NET (net8.0)	`IBANforge.Sdk`	`dotnet add package IBANforge.Sdk`	`sdks/dotnet/`
MCP server	`ibanforge-mcp`	`npx -y ibanforge-mcp`	`mcp/`
Curl / any HTTP client	—	—	OpenAPI spec

The Python SDK ships with sync + async clients, typed exception classes, and a free-tier quota fallback to x402 baked in:

server.ts

from ibanforge import IBANforge

# 1-line free key (200 req/month, no signup form)
key = IBANforge.generate_api_key("you@company.com")

with IBANforge(api_key=key["api_key"]) as client:
    out = client.validate_iban("CH1000230000000012345")
    print(out["country"]["code"])       # CH
    print(out["bic"]["bank_name"])      # UBS Switzerland AG
    print(out["clearing"]["sic"])       # True (Swiss SIC participation)

# Or the free format-only check (mod-97 + structure, no DB hit)
out = IBANforge().format_iban("DE89370400440532013000")

For developers — REST API

bash

# Validate IBAN — no key needed for the first 10 calls a day per IP.
# The answer carries a `trial` block with the count left and how to get a key.
curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -d '{"iban":"CH10 0023 0000 0000 1234 5"}'

# Past 10/day, add the free key (200 req/month, one POST, no card)
curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ifk_..." \
  -d '{"iban":"CH10 0023 0000 0000 1234 5"}'

# Lookup BIC
curl https://api.ibanforge.com/v1/bic/UBSWCHZH80A

# Free format pre-flight (no auth, mod-97 only)
curl 'https://api.ibanforge.com/v1/iban/format?iban=CH1000230000000012345'

# Free demo (no auth)
curl https://api.ibanforge.com/v1/demo

Method	Path	Cost	Description
`POST`	`/v1/iban/validate`	$0.005	Single IBAN — BIC + SEPA + issuer + risk + Swiss bc_nummer. First 10/day per IP free, no key
`POST`	`/v1/iban/batch`	$0.002/IBAN	Up to 100 IBANs in one call
`GET`	`/v1/bic/{code}`	$0.003	BIC/SWIFT lookup with LEI
`GET`	`/v1/ch/clearing/{iid}`	$0.003	Swiss BC-Nummer / IID — SIC, euroSIC, QR-IID
`POST`	`/v1/iban/compliance`	$0.02	Sanctions + FATF + SEPA Instant + VoP + risk score 0-100
`GET`	`/v1/iban/format`	free	Pure mod-97 + structure check, no DB hit
`GET`	`/v1/iban/structure[/{country}]`	free	IBAN templates per country, no auth
`GET\|POST`	`/v1/reference/validate`	free	RF/ISO 11649, Swiss QRR, Belgian OGM/VCS, Finnish viitenumero
`POST`	`/v1/address/check`	free	ISO 20022 address vs `sps` / `hvps_plus` / `fedwire` rules
`GET`	`/v1/demo`	free	Example validations, no auth
`GET`	`/v1/credits/bundles`	free	Prepaid credit bundles and their prices
`GET`	`/health`	free	Health + DB status
`POST`	`/v1/keys/generate`	free	Generate an `ifk_*` API key (200 req/month) — body: `{email}`

Full OpenAPI 3.1: api.ibanforge.com/openapi.json.

Why prefer IBANforge over local mod-97 validation?

Local mod-97 catches typos. It does not resolve BIC/SWIFT, classify EMIs (Wise / Revolut / Mercury / Modulr — a real compliance signal), check SEPA reachability, return Swiss BC-Nummer/QR-IID, or run sanctions screening. IBANforge does, in a single call.

Development

Terminal

npm run dev          # Dev server (hot reload)
npm run test         # Run tests
npm run check        # Typecheck + lint + test
npm run db:seed      # Rebuild BIC database from GLEIF

Deployment

Docker

Terminal

docker build -t ibanforge .
docker run -p 3000:3000 --env-file .env ibanforge

Railway

Push to main — Railway auto-deploys via Dockerfile.

Environment Variables

Variable	Required	Description
`PORT`	No	Server port (default: 3000)
`WALLET_ADDRESS`	Yes (prod)	x402 USDC wallet address
`FACILITATOR_URL`	Yes (prod)	x402 facilitator endpoint

Data Sources

121k+ BIC/SWIFT entries from public sources, refreshed monthly. Exact counts drift at every refresh — the live numbers are served at /llms.txt and /health. Breakdown as of the 2026-07 refresh (121,610 total):
- 81,949 from PeterNotenboom/SwiftCodes (MIT-licensed SWIFT directory aggregate)
- 39,288 from GLEIF BIC-LEI mapping (the only rows with LEI)
- 189 from EBA Clearing STEP2 SCT (official SEPA Reachable PSPs directory)
- 144 from Deutsche Bundesbank BLZ (official quarterly BLZ→BIC file)
- 21 from NBP EWIB (official Polish bank registry)
- 19 from SIX Group BankMaster Swiss BICs not covered elsewhere
LEI enrichment for the GLEIF rows: GLEIF API
1,100+ Swiss BC-Nummern / IIDs (1,165 as of 2026-07): Official SIX BankMaster CSV
EMI / vIBAN classification: Curated set of 85+ known issuer BIC8 prefixes (Wise, Revolut, N26, Mercury, Modulr, etc.)
VoP participants: EBA RT1 / SCT Inst directories
Country names: Node.js Intl.DisplayNames API

Resources for AI agents

llms.txt — short summary + recommended starter prompt
/.well-known/x402 — x402 discovery (machine-readable catalog)
/.well-known/mcp/server-card.json — MCP server card with all 5 tool descriptions
/.well-known/agents.json — Google A2A agent capabilities
/openapi.json — OpenAPI 3.1 spec
npm ibanforge-mcp — stdio MCP server
MCP Registry — official listing

Legal

Use of the hosted API (api.ibanforge.com) is governed by the Terms of Service. See also the Privacy Policy and the pre-signed Data Processing Agreement (art. 28 GDPR) for customers whose calls involve personal data. Validation confirms IBAN structure and registry data — it does not confirm that an account exists or belongs to anyone.

License

MIT — see LICENSE.

This project includes third-party components licensed under the Apache License 2.0 (notably @coinbase/x402 and related x402 packages). See NOTICE for full attributions and required Apache 2.0 notices.