{
  "markdown": "# IBANforge\n\n[![API Status](https://img.shields.io/badge/API-live-brightgreen)](https://api.ibanforge.com/health)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-1.5.0-purple)](https://registry.modelcontextprotocol.io/v0/servers?search=ibanforge)\n[![npm ibanforge-mcp](https://img.shields.io/npm/v/ibanforge-mcp?label=ibanforge-mcp)](https://www.npmjs.com/package/ibanforge-mcp)\n[![npm @ibanforge/sdk](https://img.shields.io/npm/v/@ibanforge/sdk?label=@ibanforge/sdk)](https://www.npmjs.com/package/@ibanforge/sdk)\n[![PyPI ibanforge](https://img.shields.io/pypi/v/ibanforge?label=pypi%20ibanforge)](https://pypi.org/project/ibanforge/)\n[![Glama MCP](https://glama.ai/mcp/servers/cammac-creator/ibanforge/badges/score.svg)](https://glama.ai/mcp/servers/cammac-creator/ibanforge)\n[![x402](https://img.shields.io/badge/x402-USDC_on_Base-blueviolet)](https://api.ibanforge.com/.well-known/x402)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n> **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.\n\n```\n121k+ BIC entries (39k+ LEI via GLEIF) · 1,100+ Swiss BC-Nummern (SIX) · 89 IBAN countries · <50ms p99\n```\n\n---\n\n## For AI agents — install in one click\n\n### Claude Desktop / Cursor / Cline / Continue / Windsurf\n\nAdd to your MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json` for Claude Desktop):\n\n```json\n{\n  \"mcpServers\": {\n    \"ibanforge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"ibanforge-mcp\"]\n    }\n  }\n}\n```\n\n**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)).\n\nOptional: 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.\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add ibanforge npx -- -y ibanforge-mcp\n```\n\n### Streamable HTTP (no install — for cloud-hosted agents)\n\n```\nPOST https://api.ibanforge.com/mcp\nContent-Type: application/json\nAccept: application/json, text/event-stream\n```\n\nStandard JSON-RPC `initialize` + `tools/list` + `tools/call` flow. Use this when stdio is not an option (CI/CD, serverless, Vercel agents, etc.).\n\n## Tools\n\n| Tool                  | When to use it                                                                            | Cost     |\n| --------------------- | ----------------------------------------------------------------------------------------- | -------- |\n| `validate_iban`       | User mentions an IBAN, a bank account, or a SEPA payment                                  | $0.005   |\n| `batch_validate_iban` | List of IBANs, CSV cleanup, customer DB dedup, payout list triage                         | $0.002/each |\n| `lookup_bic`          | User already has a BIC/SWIFT — backed by 121k+ BIC entries (39k+ LEI-enriched via GLEIF) | $0.003   |\n| `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   |\n| `check_compliance`    | Pre-flight risk triage before a SEPA / cross-border payment (sanctions + FATF + VoP)      | $0.02    |\n| `validate_payment_reference` | RF/ISO 11649, Swiss QRR, Belgian OGM/VCS or Finnish viitenumero checksum, plus the QRR ↔ QR-IBAN pairing verdict | **free** |\n| `check_postal_address` | An ISO 20022 address against one rail's published rules (`sps`, `hvps_plus`, `fedwire`), each finding citing its source | **free** |\n| `send_feedback`       | Report incorrect data or claim an x402 refund — the only tool that writes                 | free     |\n\nThe two free tools need no key, no wallet and no signup: they are the ones to try first.\n\nFull 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).\n\n---\n\n## For AI agents — pay per call without an API key (x402)\n\nIBANforge is x402-native. Any agent with a wallet on Base L2 can discover, pay, and call:\n\n1. Discovery: `GET https://api.ibanforge.com/.well-known/x402` returns the full catalog (endpoints, prices, asset, payTo, accepts).\n2. Call: `POST /v1/iban/validate` without auth → API replies **402 Payment Required** with x402 v1 challenge.\n3. Pay: client signs a USDC transfer on Base (eip155:8453) and retries.\n4. Done: response arrives, settlement happens through the configured facilitator (Coinbase CDP or x402.org).\n\nNo human in the loop, no sales call, no card. See the [x402 spec](https://x402.org).\n\n---\n\n## SDKs\n\nPick your language:\n\n| Language | Package | Install | Source |\n|---|---|---|---|\n| **TypeScript / JavaScript** | [`@ibanforge/sdk`](https://www.npmjs.com/package/@ibanforge/sdk) | `npm install @ibanforge/sdk` | [`sdks/typescript/`](sdks/typescript/) |\n| **Python** | [`ibanforge`](https://pypi.org/project/ibanforge/) | `pip install ibanforge` | [`sdks/python/`](sdks/python/) |\n| **Java** (17+) | [`com.ibanforge:ibanforge-sdk`](https://central.sonatype.com/artifact/com.ibanforge/ibanforge-sdk) | Maven dependency, see README | [`sdks/java/`](sdks/java/) |\n| **.NET** (net8.0) | [`IBANforge.Sdk`](https://www.nuget.org/packages/IBANforge.Sdk) | `dotnet add package IBANforge.Sdk` | [`sdks/dotnet/`](sdks/dotnet/) |\n| **MCP server** | [`ibanforge-mcp`](https://www.npmjs.com/package/ibanforge-mcp) | `npx -y ibanforge-mcp` | [`mcp/`](mcp/) |\n| Curl / any HTTP client | — | — | [OpenAPI spec](https://api.ibanforge.com/openapi.json) |\n\nThe Python SDK ships with sync + async clients, typed exception classes, and a free-tier quota fallback to x402 baked in:\n\n```python\nfrom ibanforge import IBANforge\n\n# 1-line free key (200 req/month, no signup form)\nkey = IBANforge.generate_api_key(\"you@company.com\")\n\nwith IBANforge(api_key=key[\"api_key\"]) as client:\n    out = client.validate_iban(\"CH1000230000000012345\")\n    print(out[\"country\"][\"code\"])       # CH\n    print(out[\"bic\"][\"bank_name\"])      # UBS Switzerland AG\n    print(out[\"clearing\"][\"sic\"])       # True (Swiss SIC participation)\n\n# Or the free format-only check (mod-97 + structure, no DB hit)\nout = IBANforge().format_iban(\"DE89370400440532013000\")\n```\n\n## For developers — REST API\n\n```bash\n# Validate IBAN — no key needed for the first 10 calls a day per IP.\n# The answer carries a `trial` block with the count left and how to get a key.\ncurl -X POST https://api.ibanforge.com/v1/iban/validate \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"iban\":\"CH10 0023 0000 0000 1234 5\"}'\n\n# Past 10/day, add the free key (200 req/month, one POST, no card)\ncurl -X POST https://api.ibanforge.com/v1/iban/validate \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer ifk_...\" \\\n  -d '{\"iban\":\"CH10 0023 0000 0000 1234 5\"}'\n\n# Lookup BIC\ncurl https://api.ibanforge.com/v1/bic/UBSWCHZH80A\n\n# Free format pre-flight (no auth, mod-97 only)\ncurl 'https://api.ibanforge.com/v1/iban/format?iban=CH1000230000000012345'\n\n# Free demo (no auth)\ncurl https://api.ibanforge.com/v1/demo\n```\n\n| Method | Path                       | Cost          | Description                                                    |\n| ------ | -------------------------- | ------------- | -------------------------------------------------------------- |\n| `POST` | `/v1/iban/validate`        | $0.005        | Single IBAN — BIC + SEPA + issuer + risk + Swiss bc_nummer. First 10/day per IP free, no key |\n| `POST` | `/v1/iban/batch`           | $0.002/IBAN   | Up to 100 IBANs in one call                                    |\n| `GET`  | `/v1/bic/{code}`           | $0.003        | BIC/SWIFT lookup with LEI                                      |\n| `GET`  | `/v1/ch/clearing/{iid}`    | $0.003        | Swiss BC-Nummer / IID — SIC, euroSIC, QR-IID                  |\n| `POST` | `/v1/iban/compliance`      | $0.02         | Sanctions + FATF + SEPA Instant + VoP + risk score 0-100      |\n| `GET`  | `/v1/iban/format`          | **free**      | Pure mod-97 + structure check, no DB hit                       |\n| `GET`  | `/v1/iban/structure[/{country}]` | **free** | IBAN templates per country, no auth                            |\n| `GET\\|POST` | `/v1/reference/validate` | **free**   | RF/ISO 11649, Swiss QRR, Belgian OGM/VCS, Finnish viitenumero  |\n| `POST` | `/v1/address/check`        | **free**      | ISO 20022 address vs `sps` / `hvps_plus` / `fedwire` rules      |\n| `GET`  | `/v1/demo`                 | free          | Example validations, no auth                                   |\n| `GET`  | `/v1/credits/bundles`      | free          | Prepaid credit bundles and their prices                        |\n| `GET`  | `/health`                  | free          | Health + DB status                                             |\n| `POST` | `/v1/keys/generate`        | free          | Generate an `ifk_*` API key (200 req/month) — body: `{email}`  |\n\nFull OpenAPI 3.1: [api.ibanforge.com/openapi.json](https://api.ibanforge.com/openapi.json).\n\n### Why prefer IBANforge over local mod-97 validation?\n\nLocal 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.\n\n## Development\n\n```bash\nnpm run dev          # Dev server (hot reload)\nnpm run test         # Run tests\nnpm run check        # Typecheck + lint + test\nnpm run db:seed      # Rebuild BIC database from GLEIF\n```\n\n## Deployment\n\n### Docker\n\n```bash\ndocker build -t ibanforge .\ndocker run -p 3000:3000 --env-file .env ibanforge\n```\n\n### Railway\n\nPush to `main` — Railway auto-deploys via Dockerfile.\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `PORT` | No | Server port (default: 3000) |\n| `WALLET_ADDRESS` | Yes (prod) | x402 USDC wallet address |\n| `FACILITATOR_URL` | Yes (prod) | x402 facilitator endpoint |\n\n## Data Sources\n\n- **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):\n  - 81,949 from [PeterNotenboom/SwiftCodes](https://github.com/PeterNotenboom/SwiftCodes) (MIT-licensed SWIFT directory aggregate)\n  - 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)\n  - 189 from [EBA Clearing STEP2 SCT](https://www.ebaclearing.eu/services/step2/) (official SEPA Reachable PSPs directory)\n  - 144 from [Deutsche Bundesbank BLZ](https://www.bundesbank.de/en/tasks/payment-systems/services/bank-sort-codes) (official quarterly BLZ→BIC file)\n  - 21 from [NBP EWIB](https://ewib.nbp.pl/) (official Polish bank registry)\n  - 19 from [SIX Group BankMaster](https://www.six-group.com/en/products-services/banking-services/bank-master-data.html) Swiss BICs not covered elsewhere\n- **LEI enrichment** for the GLEIF rows: [GLEIF API](https://api.gleif.org)\n- **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\n- **EMI / vIBAN classification**: Curated set of 85+ known issuer BIC8 prefixes (Wise, Revolut, N26, Mercury, Modulr, etc.)\n- **VoP participants**: EBA RT1 / SCT Inst directories\n- **Country names**: Node.js `Intl.DisplayNames` API\n\n## Resources for AI agents\n\n- [`llms.txt`](https://ibanforge.com/llms.txt) — short summary + recommended starter prompt\n- [`/.well-known/x402`](https://api.ibanforge.com/.well-known/x402) — x402 discovery (machine-readable catalog)\n- [`/.well-known/mcp/server-card.json`](https://api.ibanforge.com/.well-known/mcp/server-card.json) — MCP server card with all 5 tool descriptions\n- [`/.well-known/agents.json`](https://api.ibanforge.com/.well-known/agents.json) — Google A2A agent capabilities\n- [`/openapi.json`](https://api.ibanforge.com/openapi.json) — OpenAPI 3.1 spec\n- [npm `ibanforge-mcp`](https://www.npmjs.com/package/ibanforge-mcp) — stdio MCP server\n- [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=ibanforge) — official listing\n\n## Legal\n\nUse of the hosted API (`api.ibanforge.com`) is governed by the\n[Terms of Service](https://ibanforge.com/legal/terms?src=github-readme). See also the\n[Privacy Policy](https://ibanforge.com/legal/privacy?src=github-readme) and the pre-signed\n[Data Processing Agreement](https://ibanforge.com/legal/dpa?src=github-readme) (art. 28 GDPR)\nfor customers whose calls involve personal data. Validation confirms IBAN\nstructure and registry data — it does not confirm that an account exists or\nbelongs to anyone.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nThis project includes third-party components licensed under the Apache License 2.0\n(notably `@coinbase/x402` and related x402 packages). See [NOTICE](NOTICE) for\nfull attributions and required Apache 2.0 notices.\n",
  "bytes": 13592,
  "sha": "cc572979fccd22b7ac3ae008017f673c6fcfa13dfebb8cec0a840f523cf5fbd0",
  "repo_slug": "cammac-creator/ibanforge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cammac_creator_ibanforge_99a59aa1/readme"
}