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.

121,197 BIC entries (38K LEI via GLEIF) · 1,190 Swiss BC-Nummern (SIX) · 84 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):

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

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)

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

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

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

5 MCP 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 121,197 BIC entries (38,761 LEI-enriched via GLEIF) | $0.003 | | lookup_ch_clearing | Swiss BC-Nummer / IID — the only API with this data (1,190 SIX BankMaster entries) | $0.003 | | check_compliance | Pre-flight risk triage before a SEPA / cross-border payment (sanctions + FATF + VoP) | $0.02 |

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:

1. Discovery: GET https://api.ibanforge.com/.well-known/x402 returns the full catalog (endpoints, prices, asset, payTo, accepts).
2. Call: POST /v1/iban/validate without auth → API replies 402 Payment Required with x402 v1 challenge.
3. Pay: client signs a USDC transfer on Base (eip155:8453) and retries.
4. 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/ | | 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:

from ibanforge import IBANforge

# 1-line free key (200 req/month, no signup form)
key = IBANforge.generate_api_key("[email protected]")

with IBANforge(api_key=key["api_key"]) as client:
    out = client.validate_iban("CH9300762011623852957")
    print(out["country"]["code"])      # CH
    print(out["bic"]["bankName"])      # UBS Switzerland AG
    print(out["sepa"]["instant"])      # True

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

For developers — REST API

# Validate IBAN
curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ifk_..." \
  -d '{"iban":"CH93 0076 2011 6238 5295 7"}'

# 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=CH9300762011623852957'

# 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 | | 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/demo | free | Example validations, no auth | | 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

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

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

• 121,197 BIC/SWIFT entries from public sources, refreshed monthly:
  • 38,761 from GLEIF BIC-LEI mapping (the only rows with LEI)
  • 81,642 from PeterNotenboom/SwiftCodes (MIT-licensed SWIFT directory aggregate)
  • 142 from Deutsche Bundesbank BLZ (official quarterly BLZ→BIC file)
  • 633 from SIX Group BankMaster Swiss BICs
  • 19 from NBP EWIB (official Polish bank registry)
• LEI enrichment for the 38,761 GLEIF rows: GLEIF API
• 1,190 Swiss BC-Nummern / IIDs: 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

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.