io.github.cammac-creator/ibanforge
Pre-payout IBAN screening for AI agents: validation, sanctions, Swiss clearing, risk scoring
Open source Repository Open in the app JSON README (API)
About
Pre-payout IBAN screening for AI agents: validation, sanctions, Swiss clearing, risk scoring
Details
- Kind
- MCP servers
- Topic
- Security & identity
- Publisher
- cammac-creator
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.5.0
- Stars
- 3
- Forks
- 3
- Open pull requests
- 7
- Last push
- 2026-09-07T20:51:16Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:33
- Updated
- 2026-09-07 16:05:20
- Origin id
io.github.cammac-creator/ibanforge
README
# IBANforge
[](https://api.ibanforge.com/health)
[](https://registry.modelcontextprotocol.io/v0/servers?search=ibanforge)
[](https://www.npmjs.com/package/ibanforge-mcp)
[](https://www.npmjs.com/package/@ibanforge/sdk)
[](https://pypi.org/project/ibanforge/)
[](https://glama.ai/mcp/servers/cammac-creator/ibanforge)
[](https://api.ibanforge.com/.well-known/x402)
[](https://www.typescriptlang.org/)
[](LICENSE)
> **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.
```
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):
```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](https://ibanforge.com/en/legal/dpa?src=github-readme)).
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)
```bash
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.).
## 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`](https://api.ibanforge.com/.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](https://x402.org).
---
## SDKs
Pick your language:
| Language | Package | Install | Source |
|---|---|---|---|
| **TypeScript / JavaScript** | [`@ibanforge/sdk`](https://www.npmjs.com/package/@ibanforge/sdk) | `npm install @ibanforge/sdk` | [`sdks/typescript/`](sdks/typescript/) |
| **Python** | [`ibanforge`](https://pypi.org/project/ibanforge/) | `pip install ibanforge` | [`sdks/python/`](sdks/python/) |
| **Java** (17+) | [`com.ibanforge:ibanforge-sdk`](https://central.sonatype.com/artifact/com.ibanforge/ibanforge-sdk) | Maven dependency, see README | [`sdks/java/`](sdks/java/) |
| **.NET** (net8.0) | [`IBANforge.Sdk`](https://www.nuget.org/packages/IBANforge.Sdk) | `dotnet add package IBANforge.Sdk` | [`sdks/dotnet/`](sdks/dotnet/) |
| **MCP server** | [`ibanforge-mcp`](https://www.npmjs.com/package/ibanforge-mcp) | `npx -y ibanforge-mcp` | [`mcp/`](mcp/) |
| Curl / any HTTP client | — | — | [OpenAPI spec](https://api.ibanforge.com/openapi.json) |
The Python SDK ships with sync + async clients, typed exception classes, and a free-tier quota fallback to x402 baked in:
```python
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](https://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
```bash
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
```bash
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`](https://api.ibanforge.com/llms.txt) and `/health`. Breakdown as of the 2026-07 refresh (121,610 total):
- 81,949 from [PeterNotenboom/SwiftCodes](https://github.com/PeterNotenboom/SwiftCodes) (MIT-licensed SWIFT directory aggregate)
- 39,288 from [GLEIF BIC-LEI mapping](https://www.gleif.org/en/lei-data/lei-mapping/download-bic-to-lei-relationship-files) (the only rows with LEI)
- 189 from [EBA Clearing STEP2 SCT](https://www.ebaclearing.eu/services/step2/) (official SEPA Reachable PSPs directory)
- 144 from [Deutsche Bundesbank BLZ](https://www.bundesbank.de/en/tasks/payment-systems/services/bank-sort-codes) (official quarterly BLZ→BIC file)
- 21 from [NBP EWIB](https://ewib.nbp.pl/) (official Polish bank registry)
- 19 from [SIX Group BankMaster](https://www.six-group.com/en/products-services/banking-services/bank-master-data.html) Swiss BICs not covered elsewhere
- **LEI enrichment** for the GLEIF rows: [GLEIF API](https://api.gleif.org)
- **1,100+ Swiss BC-Nummern / IIDs** (1,165 as of 2026-07): Official [SIX BankMaster](https://www.six-group.com/en/products-services/banking-services/bank-master-data.html) 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`](https://ibanforge.com/llms.txt) — short summary + recommended starter prompt
- [`/.well-known/x402`](https://api.ibanforge.com/.well-known/x402) — x402 discovery (machine-readable catalog)
- [`/.well-known/mcp/server-card.json`](https://api.ibanforge.com/.well-known/mcp/server-card.json) — MCP server card with all 5 tool descriptions
- [`/.well-known/agents.json`](https://api.ibanforge.com/.well-known/agents.json) — Google A2A agent capabilities
- [`/openapi.json`](https://api.ibanforge.com/openapi.json) — OpenAPI 3.1 spec
- [npm `ibanforge-mcp`](https://www.npmjs.com/package/ibanforge-mcp) — stdio MCP server
- [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=ibanforge) — official listing
## Legal
Use of the hosted API (`api.ibanforge.com`) is governed by the
[Terms of Service](https://ibanforge.com/legal/terms?src=github-readme). See also the
[Privacy Policy](https://ibanforge.com/legal/privacy?src=github-readme) and the pre-signed
[Data Processing Agreement](https://ibanforge.com/legal/dpa?src=github-readme) (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](LICENSE).
This project includes third-party components licensed under the Apache License 2.0
(notably `@coinbase/x402` and related x402 packages). See [NOTICE](NOTICE) for
full attributions and required Apache 2.0 notices.