内容
# 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)
> **适用于 AI 代理的合规 API。** IBAN 验证、BIC/SWIFT 查询、瑞士清算（BC-编号 / QR-IID / SIX BankMaster）、EMI/vIBAN 分类、SEPA Instant + VoP 可达性以及风险评分 — 原生暴露在 **MCP** 和 **x402 微支付** 上，无需 API 密钥注册。
```
121,399 条 BIC 记录（38K LEI via GLEIF）· 1,190 条瑞士 BC-编号（SIX）· 89 个 IBAN 国家 · <50ms p99
```
---
## 适用于 AI 代理 - 一键安装
### Claude Desktop / Cursor / Cline / Continue / Windsurf
将以下内容添加到您的 MCP 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json` for Claude Desktop）：
```json
{
"mcpServers": {
"ibanforge": {
"command": "npx",
"args": ["-y", "ibanforge-mcp"]
}
}
}
```
可选：设置 `IBANFORGE_API_KEY=ifk_...` 在 `env` 中用于免费层级（200 次请求/月）。如果没有它，服务器将使用公共/演示界面；与 **x402 微支付** 结合使用，实现无限按次付费访问，无需注册。
### Claude Code（CLI）
```bash
claude mcp add ibanforge npx -- -y ibanforge-mcp
```
### 可流式 HTTP（无需安装 - 适用于云托管代理）
```
POST https://api.ibanforge.com/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
```
标准 JSON-RPC `initialize` + `tools/list` + `tools/call` 流程。在 stdio 不是选项时使用（CI/CD、serverless、Vercel 代理等）。
### 5 个 MCP 工具
| 工具 | 何时使用 | 成本 |
| --- | --- | --- |
| `validate_iban` | 用户提及 IBAN、银行账户或 SEPA 支付 | $0.005 |
| `batch_validate_iban` | IBAN 列表、CSV 清理、客户数据库去重、付款列表分类 | $0.002/each |
| `lookup_bic` | 用户已经拥有 BIC/SWIFT - 支持 121,399 条 BIC 记录（38,761 条 LEI via GLEIF） | $0.003 |
| `lookup_ch_clearing` | 瑞士 BC-编号 / IID - **唯一具有此数据的 API** （1,190 条 SIX BankMaster 记录） | $0.003 |
| `check_compliance` | SEPA / 跨境支付前的风险分类（制裁 + FATF + VoP） | $0.02 |
完整的描述和何时使用的触发器在 [`/.well-known/mcp/server-card.json`](https://api.ibanforge.com/.well-known/mcp/server-card.json) 中实时提供。
---
## 适用于 AI 代理 - 无需 API 密钥即可按次付费（x402）
IBANforge 是 x402 原生的。任何具有 Base L2 钱包的代理都可以发现、支付和调用：
1. 发现：`GET https://api.ibanforge.com/.well-known/x402` 返回完整的目录（端点、价格、资产、payTo、接受）。
2. 调用：`POST /v1/iban/validate` 无需身份验证 → API 回复 **402 Payment Required** 带有 x402 v1 挑战。
3. 支付：客户端在 Base 上签名 USDC 转账（eip155:8453）并重试。
4. 完成：响应到达，通过配置的促进者（Coinbase CDP 或 x402.org）进行结算。
无需人工介入，无需销售电话，无需信用卡。参见 [x402 规范](https://x402.org)。
---
## 软件开发工具包（SDK）
选择您的语言：
| 语言 | 软件包 | 安装 | 源代码 |
| --- | --- | --- | --- |
| **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/) |
| **MCP 服务器** | [`ibanforge-mcp`](https://www.npmjs.com/package/ibanforge-mcp) | `npx -y ibanforge-mcp` | [`mcp/`](mcp/) |
| Curl / 任何 HTTP 客户端 | — | — | [OpenAPI 规范](https://api.ibanforge.com/openapi.json) |
Python SDK 附带同步 + 异步客户端、类型化异常类和免费层级配额回退到 x402：
```python
from ibanforge import IBANforge
# 1 行免费密钥（200 次请求/月，无需注册表单）
key = IBANforge.generate_api_key("you@example.com")
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
# 或免费格式检查（mod-97 + 结构，无数据库命中）
out = IBANforge().format_iban("DE89370400440532013000")
```
## 适用于开发者 - REST API
```bash
# 验证 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"}'
# 查询 BIC
curl https://api.ibanforge.com/v1/bic/UBSWCHZH80A
# 免费格式预检查（无身份验证，仅 mod-97）
curl 'https://api.ibanforge.com/v1/iban/format?iban=CH9300762011623852957'
# 免费演示（无身份验证）
curl https://api.ibanforge.com/v1/demo
```
| 方法 | 路径 | 成本 | 描述 |
| --- | --- | --- | --- |
| `POST` | `/v1/iban/validate` | $0.005 | 单个 IBAN - BIC + SEPA + issuer + 风险 + 瑞士 bc_nummer |
| `POST` | `/v1/iban/batch` | $0.002/IBAN | 最多 100 个 IBAN |
| `GET` | `/v1/bic/{code}` | $0.003 | BIC/SWIFT 查询，附带 LEI |
| `GET` | `/v1/ch/clearing/{iid}` | $0.003 | 瑞士 BC-编号 / IID - SIC, euroSIC, QR-IID |
| `POST` | `/v1/iban/compliance` | $0.02 | 制裁 + FATF + SEPA Instant + VoP + 风险评分 0-100 |
| `GET` | `/v1/iban/format` | **免费** | 纯 mod-97 + 结构检查，无数据库命中 |
| `GET` | `/v1/demo` | 免费 | 示例验证，无身份验证 |
| `GET` | `/health` | 免费 | 健康 + 数据库状态 |
| `POST` | `/v1/keys/generate` | 免费 | 生成 `ifk_*` API 密钥（200 次请求/月）- 正文：`{email}` |
完整的 OpenAPI 3.1：[api.ibanforge.com/openapi.json](https://api.ibanforge.com/openapi.json)。
### 为什么选择 IBANforge 而不是本地 mod-97 验证？
本地 mod-97 可以捕获输入错误。它 **不** 解析 BIC/SWIFT，分类 EMI（Wise / Revolut / Mercury / Modulr - 真实的合规信号），检查 SEPA 可达性，返回瑞士 BC-编号/QR-IID，或运行制裁筛查。IBANforge 可以在单个调用中完成这些操作。
## 开发
```bash
npm run dev # 开发服务器（热重载）
npm run test # 运行测试
npm run check # 类型检查 + lint + 测试
npm run db:seed # 从 GLEIF 重建 BIC 数据库
```
## 部署
### Docker
```bash
docker build -t ibanforge .
docker run -p 3000:3000 --env-file .env ibanforge
```
### Railway
推送到 `main` - Railway 通过 Dockerfile 自动部署。
## 环境变量
| 变量 | 是否必需 | 描述 |
| --- | --- | --- |
| `PORT` | 否 | 服务器端口（默认：3000） |
| `WALLET_ADDRESS` | 是（生产环境） | x402 USDC 钱包地址 |
| `FACILITATOR_URL` | 是（生产环境） | x402 促进者端点 |
## 数据源
- **121,399 条 BIC/SWIFT 记录** 来自公共来源，每月刷新：
- 38,761 条来自 [GLEIF BIC-LEI 映射](https://www.gleif.org/en/lei-data/lei-mapping/download-bic-to-lei-relationship-files) （唯一带有 LEI 的行）
- 81,642 条来自 [PeterNotenboom/SwiftCodes](https://github.com/PeterNotenboom/SwiftCodes) （MIT 许可的 SWIFT 目录聚合）
- 142 条来自 [Deutsche Bundesbank BLZ](https://www.bundesbank.de/en/tasks/payment-systems/services/bank-sort-codes) （官方季度 BLZ→BIC 文件）
- 633 条来自 [SIX Group BankMaster](https://www.six-group.com/en/products-services/banking-services/bank-master-data.html) 瑞士 BIC
- 201 条来自 [EBA Clearing STEP2 SCT](https://www.ebaclearing.eu/services/step2/) （官方 SEPA 可达 PSP 目录）
- 19 条来自 [NBP EWIB](https://ewib.nbp.pl/) （官方波兰银行注册）
- **LEI 丰富** 适用于 38,761 个 GLEIF 记录：[GLEIF API](https://api.gleif.org)
- **1,190 条瑞士 BC-编号 / IIDs**：官方 [SIX BankMaster](https://www.six-group.com/en/products-services/banking-services/bank-master-data.html) CSV
- **EMI / vIBAN 分类**：精选的 85+ 个已知发行人 BIC8 前缀（Wise, Revolut, N26, Mercury, Modulr 等）
- **VoP 参与者**：EBA RT1 / SCT Inst 目录
- **国家名称**：Node.js `Intl.DisplayNames` API
## AI 代理资源
- [`llms.txt`](https://ibanforge.com/llms.txt) - 简要摘要 + 推荐的启动提示
- [`/.well-known/x402`](https://api.ibanforge.com/.well-known/x402) - x402 发现（机器可读目录）
- [`/.well-known/mcp/server-card.json`](https://api.ibanforge.com/.well-known/mcp/server-card.json) - MCP 服务器卡，包含所有 5 个工具描述
- [`/.well-known/agents.json`](https://api.ibanforge.com/.well-known/agents.json) - Google A2A 代理功能
- [`/openapi.json`](https://api.ibanforge.com/openapi.json) - OpenAPI 3.1 规范
- [npm `ibanforge-mcp`](https://www.npmjs.com/package/ibanforge-mcp) - stdio MCP 服务器
- [MCP 注册表](https://registry.modelcontextprotocol.io/v0/servers?search=ibanforge) - 官方列表
## 许可证
MIT - 参见 [LICENSE](LICENSE)。
该项目包含第三方组件，许可证为 Apache License 2.0
（尤其是 `@coinbase/x402` 和相关的 x402 软件包）。参见 [NOTICE](NOTICE) 以获取完整的归属和所需的 Apache 2.0 通知。
