IBANforge

IBAN validation & BIC/SWIFT lookup API with SEPA compliance data, issuer classification, risk indicators, x402 micropayments, and MCP integration for AI agents.

Features

• IBAN Validation — Full mod-97 checksum verification, BBAN structure parsing, 84 countries
• BIC/SWIFT Lookup — 121,000+ entries from GLEIF with LEI enrichment
• SEPA Compliance — Membership status, payment schemes (SCT/SDD/SCT_INST), VoP requirement per country
• Issuer Classification — Detects traditional banks, neobanks, EMIs (Wise, Revolut, N26...), and payment institutions for vIBAN detection (85 known BIC8 mappings)
• Risk Indicators — Composite risk signal: issuer type, country risk (FATF-based), test BIC, SEPA reachability, VoP coverage
• Batch Processing — Validate up to 100 IBANs in one call
• x402 Micropayments — Pay-per-call with USDC (from $0.002/request)
• MCP Server — Native AI agent integration via Model Context Protocol
• Swiss Clearing — 1,190 BC-Nummer entries from SIX BankMaster with SIC, euroSIC, Instant Payments, and QR-IID data for CH/LI IBANs
• Self-hosted — Docker deployment, SQLite database, no external dependencies

Quick Start

git clone https://github.com/cammac-creator/ibanforge.git
cd ibanforge
npm install
cp .env.example .env
npm run dev

API Endpoints

Method	Path	Cost	Description
POST	/v1/iban/validate	$0.005	Validate a single IBAN
POST	/v1/iban/batch	$0.002/IBAN	Validate up to 100 IBANs
GET	/v1/bic/:code	$0.003	Lookup BIC/SWIFT code
GET	/v1/ch/clearing/:iid	$0.003	Swiss BC-Nummer / IID clearing lookup
GET	/v1/demo	Free	Example validations
GET	/health	Free	Health check
GET	/stats	Free	Usage statistics

Examples

Validate IBAN

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

Lookup BIC

curl https://api.ibanforge.com/v1/bic/UBSWCHZH80A

MCP Integration

Add to your Claude Desktop or AI agent config:

{
  "mcpServers": {
    "ibanforge": {
      "command": "npx",
      "args": ["tsx", "src/mcp/server.ts"],
      "cwd": "/path/to/ibanforge"
    }
  }
}

Available tools: validate_iban, batch_validate_iban, lookup_bic, check_compliance, lookup_ch_clearing

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

• BIC/SWIFT entries: GLEIF BIC-LEI mapping
• LEI enrichment: GLEIF API
• Country names: Node.js Intl.DisplayNames API

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.