ibanforge

# IBANforge

[![API Status](https://img.shields.io/badge/API-live-brightgreen)](https://api.ibanforge.com/health)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-1.7.0-purple)](https://registry.modelcontextprotocol.io/v0/servers?search=ibanforge)
[![npm ibanforge-mcp](https://img.shields.io/npm/v/ibanforge-mcp?label=ibanforge-mcp)](https://www.npmjs.com/package/ibanforge-mcp)
[![npm @ibanforge/sdk](https://img.shields.io/npm/v/@ibanforge/sdk?label=@ibanforge/sdk)](https://www.npmjs.com/package/@ibanforge/sdk)
[![PyPI ibanforge](https://img.shields.io/pypi/v/ibanforge?label=pypi%20ibanforge)](https://pypi.org/project/ibanforge/)
[![Glama MCP](https://glama.ai/mcp/servers/cammac-creator/ibanforge/badges/score.svg)](https://glama.ai/mcp/servers/cammac-creator/ibanforge)
[![x402](https://img.shields.io/badge/x402-USDC_on_Base-blueviolet)](https://api.ibanforge.com/.well-known/x402)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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** |
| `check_swiss_qr_bill` | A Swiss QR-bill payload — header, QR-IBAN and reference pairing, structured (S) versus combined (K) addresses ahead of 14.11.2026 | **free** |
| `send_feedback`       | Report incorrect data or claim an x402 refund                                             | free     |
| `request_api_key`     | You hit the daily limit, or need a durable key — a human approves in a browser, no e-mail  | free     |
| `poll_api_key`        | Collect that key once it is approved, handed over exactly once                             | free     |

The free tools need no key, no wallet and no signup: they are the ones to try first. The
last two are the way out of the daily limit without anyone typing an address — they keep
answering after the limit is reached.

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.