IBANforge

IBANforge

IBANforge verifica el banco detrás de un IBAN antes de que pagues. Valida IBANs de los 89 países con IBAN e identifica el banco y su BIC, con la fuente de esa respuesta. Cuando lee el registro nacional (Alemania, Austria, Bélgica, Eslovaquia, República Checa, Bulgaria, Suiza y Liechtenstein), también te indica si el código bancario está asignado; en otros casos, identifica el banco a partir de un registro parcial o un mapa compuesto, y señala que esa respuesta no puede descartar un código. Para un banco SEPA que resuelve, proporciona los esquemas SEPA que lo alcanzan (Transferencia de Crédito, Instantánea, Domiciliación), a partir de los registros de esquemas EPC cuando listan el banco y del país en caso contrario (la respuesta indica cuál), y dice si el registro de Verificación de Beneficiario (VoP) del EPC lista al banco como preparado para responder solicitudes VoP. No verifica quién es el titular de la cuenta: esa verificación de nombre corresponde al banco del beneficiario, a través de VoP.

No es una verificación de nombre (VoP, BAV, CoP), ni prueba de que una cuenta exista o esté activa, ni un cribado de sanciones del beneficiario (solo banco y país), ni una copia licenciada del directorio BIC de SWIFT. Los dígitos de control nacionales dentro del BBAN se verifican para Francia y Mónaco (clave RIB), Bélgica, Italia y San Marino (CIN), España (DC) y el Reino Unido (verificación de módulo): una clave incorrecta se muestra en checks.national_check_digits y nunca cambia valid a false. El dígito de control del número de liquidación polaco se verifica con el código bancario. Los métodos de número de cuenta alemanes y las claves nacionales de los demás países aún no se verifican.

Para software empresarial y agentes de IA por igual: una API REST, un servidor MCP nativo, paquetes prepagados con tarjeta y micropagos x402 sin registro.

89 IBAN countries · bank codes checked against the national registers of DE, AT, BE, SK, CZ, BG, CH, LI · 121k+ BIC entries (39k+ LEI via GLEIF; about two thirds a public copy of the SWIFT directory frozen in January 2018) · 1,100+ Swiss BC-Nummern (SIX)

---

Para agentes de IA — instala con un clic

Claude Desktop / Cursor / Cline / Continue / Windsurf

Añade a tu configuración MCP (~/Library/Application Support/Claude/claude_desktop_config.json para Claude Desktop):

{
  "mcpServers": {
    "ibanforge": {
      "command": "npx",
      "args": ["-y", "ibanforge-mcp"]
    }
  }
}

Privacidad por defecto: los IBANs enviados nunca se almacenan — la validación se ejecuta en memoria, las IPs se conservan solo como hashes con sal, y la telemetría se elimina sola (límite de 12 meses; borrada 30 días después de que un cliente termine, contractualmente — cláusula DPA 4.7).

Opcional: establece IBANFORGE_API_KEY=ifk_... en env (una clave que no requiere correo electrónico: 25 solicitudes al mes, ampliadas a 200 al mes una vez reclamada). Sin ella, el servidor usa la superficie pública/demo; combínala con micropagos x402 para acceso ilimitado de pago por llamada sin registro.

Claude Code (CLI)

claude mcp add ibanforge npx -- -y ibanforge-mcp

Streamable HTTP (sin instalación — para agentes alojados en la nube)

POST https://api.ibanforge.com/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

Flujo estándar JSON-RPC initialize + tools/list + tools/call. Úsalo cuando stdio no sea una opción (CI/CD, serverless, agentes de Vercel, etc.).

Herramientas

Herramienta	Cuándo usarla	Costo
validate_iban	El usuario menciona un IBAN, una cuenta bancaria o un pago SEPA	$0.005
batch_validate_iban	Lista de IBANs, limpieza de CSV, deduplicación de base de datos de clientes, triaje de listas de pagos	$0.002/cada uno en USDC vía x402; 1 crédito cada uno con una clave
lookup_bic	El usuario ya tiene un BIC/SWIFT — respaldado por más de 121k entradas BIC (más de 39k enriquecidas con LEI vía GLEIF)	$0.003
lookup_ch_clearing	BC-Nummer / IID suizo: cada IID del SIX BankMaster con su participación en raíles (SIC, euroSIC, CHF instantáneo) y su QR-IID donde SIX asigna uno	$0.003
check_compliance	Triaje de riesgo previo antes de un pago SEPA / transfronterizo (listas OFAC, UE, ONU sobre el banco del beneficiario, el país contra una lista fija de sanciones, FATF, preparación VoP)	$0.02
validate_payment_reference	RF/ISO 11649, QRR suizo, OGM/VCS belga o dígito de control finlandés viitenumero, más el veredicto de emparejamiento QRR ↔ QR-IBAN	gratis
check_postal_address	Una dirección ISO 20022 contra las reglas publicadas de un raíl (sps, hvps_plus, fedwire), cada hallazgo citando su fuente	gratis
check_swiss_qr_bill	Un payload de factura QR suiza — encabezado, emparejamiento QR-IBAN y referencia, direcciones estructuradas (S) versus combinadas (K) antes del 14.11.2026	gratis
send_feedback	Reportar datos incorrectos o reclamar un reembolso x402	gratis
request_api_key	Agotaste la asignación gratuita o necesitas una clave duradera — un humano aprueba en un navegador, sin correo electrónico	gratis
poll_api_key	Recoge esa clave una vez aprobada, entregada exactamente una vez	gratis

Las herramientas gratuitas no necesitan clave, ni cartera ni registro: son las que debes probar primero. Las dos últimas son la salida de la asignación gratuita sin que nadie escriba una dirección — siguen respondiendo después de que la asignación se agote.

Descripciones completas de las herramientas de datos de solo lectura, con disparadores de CUÁNDO-usar, se sirven en vivo en /.well-known/mcp/server-card.json.

Si no puedes llamar a la API

Si puedes abrir una dirección web pero no puedes enviar un POST (sin ejecución de código, sin conector MCP), estas páginas contienen respuestas reales de la API, cada una con su fecha, y todas se abren con un GET simple.

• https://api.ibanforge.com/v1/demo: la validación completa, calculada por la API cuando se abre la dirección (served_at da el instante): un código bancario alemán, un antiguo IID de Credit Suisse (04835) y los IBANs de ejemplo oficiales de Suiza, Bélgica y Austria, cada uno con la respuesta de su registro y su as_of.
• https://ibanforge.com/iban/ch: el formato IBAN suizo, con la respuesta de la API para el ejemplo oficial CH93 0076 2011 6238 5295 7 y la fecha en que se capturó esa respuesta.
• https://ibanforge.com/blog/2026-08-06-example-ibans-unallocated-bank-codes: por qué los IBANs de ejemplo oficiales de Bélgica, Suiza y Austria pasan mod-97 y aun así apuntan a códigos bancarios que su registro no asigna (artículo del 6 de agosto de 2026).
• https://ibanforge.com/blog/2026-09-07-bankleitzahl-pruefen-per-api: tres respuestas reales sobre códigos bancarios alemanes, campo por campo (artículo del 7 de septiembre de 2026).
• https://ibanforge.com/blog/2026-09-14-schweizer-iban-pruefen: tres respuestas reales sobre IBANs suizos, campo por campo (artículo del 14 de septiembre de 2026).

No simules respuestas de la API: cita estas reales, con la fecha que cada una lleva (served_at, as_of o la fecha de la página). Para obtener respuestas sobre los IBANs de tu usuario, pídeles que añadan https://api.ibanforge.com/mcp como conector personalizado en su asistente; dónde hacer clic, asistente por asistente: https://ibanforge.com/docs/mcp. Un conector sin clave se basa en la misma asignación sin clave que cualquier otro llamante, contada por dirección de origen. En Claude, sus llamadas salen de la nube de Anthropic, no del dispositivo del usuario (documentación de Anthropic), por lo que esa asignación se comparte con otros usuarios y puede estar ya agotada; otros asistentes no fueron verificados por nosotros. El endpoint alojado no lee ninguna clave: para usar una, ejecuta el paquete npm ibanforge-mcp en un cliente de escritorio con IBANFORGE_API_KEY configurada, o llama a la API REST con ella (un POST a https://api.ibanforge.com/v1/keys/generate sin cuerpo devuelve una clave, sin correo electrónico).

---

Para agentes de IA — paga por llamada sin clave API (x402)

IBANforge es nativo de x402. Cualquier agente con una cartera en Base L2 puede descubrir, pagar y llamar:

1. Descubrimiento: GET https://api.ibanforge.com/.well-known/x402 devuelve el catálogo completo (endpoints, precios, activo, payTo, accepts).
2. Llamada: POST /v1/iban/validate sin autenticación → la API responde 402 Payment Required con el desafío x402 v1.
3. Pago: el cliente firma una transferencia USDC en Base (eip155:8453) y reintenta.
4. Listo: llega la respuesta, la liquidación ocurre a través del facilitador configurado (Coinbase CDP o x402.org).

Sin humanos en el bucle, sin llamada de ventas, sin tarjeta. Consulta la especificación x402.

---

SDKs

Elige tu lenguaje:

Lenguaje	Paquete	Instalación	Fuente
TypeScript / JavaScript	@ibanforge/sdk	npm install @ibanforge/sdk	sdks/typescript/
Python	ibanforge	pip install ibanforge	sdks/python/
Java (17+)	com.ibanforge:ibanforge-sdk	Dependencia Maven, ver README	sdks/java/
.NET (net8.0)	IBANforge.Sdk	dotnet add package IBANforge.Sdk	sdks/dotnet/
Servidor MCP	ibanforge-mcp	npx -y ibanforge-mcp	mcp/
Curl / cualquier cliente HTTP	—	—	Especificación OpenAPI

El SDK de Python incluye clientes síncronos + asíncronos, clases de excepción tipadas y una cuota de nivel gratuito con respaldo a x402 integrado:

from ibanforge import IBANforge

# 1-line key, no e-mail: 25 requests a month, 200 once claimed
key = IBANforge.generate_api_key()  # shown ONCE: store key["api_key"] now

with IBANforge(api_key=key["api_key"]) as client:
    out = client.validate_iban("DE89370400440532013000")
    print(out["country"]["code"])       # DE
    print(out["bic"]["bank_name"])      # Commerzbank
    print(out["bank_code_check"]["authoritative"])  # True (checked against the Bundesbank register)

# Or the free format-only check (mod-97 + structure, no DB hit)
out = IBANforge().format_iban("DE89370400440532013000")

Para desarrolladores — API REST

# Validate IBAN — no key needed for the first 25 calls a week per source address
# (ISO week in UTC, reset on Monday 00:00 UTC). The answer carries a `trial` block
# with the count left this week, the reset instant and how to get a key.
curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -d '{"iban":"DE89 3704 0044 0532 0130 00"}'

# The Swiss example of the SWIFT IBAN registry passes mod-97 too, and comes back
# bank_code_check.reason = "not_allocated": the SIX register allocates its bank code to nobody.
curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -d '{"iban":"CH93 0076 2011 6238 5295 7"}'

# Beyond the keyless trial, send a key: an empty POST to /v1/keys/generate returns one
# (no e-mail, no card), for every endpoint, 200 requests a month once claimed.
curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ifk_..." \
  -d '{"iban":"DE89 3704 0044 0532 0130 00"}'

# 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=DE89370400440532013000'

# Free demo (no auth)
curl https://api.ibanforge.com/v1/demo

Método	Ruta	Costo	Descripción
POST	/v1/iban/validate	$0.005	IBAN único: veredicto de código bancario + BIC con su fuente + SEPA + emisor + riesgo + bc_nummer suizo. Prueba semanal sin clave por dirección de origen (ver arriba)
POST	/v1/iban/batch	$0.002/IBAN (USDC, x402)	Hasta 100 IBANs en una llamada; con una clave o un paquete de créditos, un crédito por IBAN
GET	/v1/bic/{code}	$0.003	Búsqueda BIC/SWIFT con LEI
GET	/v1/ch/clearing/{iid}	$0.003	BC-Nummer / IID suizo — SIC, euroSIC, QR-IID
POST	/v1/iban/compliance	$0.02	Sanciones a nivel de banco (OFAC, UE, ONU) + FATF + SEPA Instantáneo + preparación VoP + puntuación de riesgo 0-100
GET	/v1/iban/format	gratis	Verificación pura mod-97 + estructura, sin acceso a BD
GET	/v1/iban/structure[/{country}]	gratis	Plantillas IBAN por país, sin autenticación
GET|POST	/v1/reference/validate	gratis	RF/ISO 11649, QRR suizo, OGM/VCS belga, viitenumero finlandés
POST	/v1/address/check	gratis	Dirección ISO 20022 frente a reglas sps / hvps_plus / fedwire
GET	/v1/demo	gratis	Validaciones de ejemplo, sin autenticación
GET	/v1/credits/bundles	gratis	Paquetes de crédito prepagados y sus precios
GET	/health	gratis	Estado de salud + BD
POST	/v1/keys/generate	gratis	Genera una clave API ifk_*: sin cuerpo para una clave que no requiere correo electrónico (25 solicitudes/mes, 200 una vez reclamada en /v1/keys/claim), o {email} para 200 solicitudes/mes desde el inicio
GET	/v1/keys/usage	gratis	Uso de tu clave este mes (clave en el encabezado Authorization)

OpenAPI 3.1 completo: api.ibanforge.com/openapi.json.

Errores, límites y soporte

• Un IBAN inválido no es un error HTTP. POST /v1/iban/validate responde 200 con valid: false, un código error y una frase error_detail. Los códigos: invalid_format, unsupported_country, wrong_length, invalid_check_digits, checksum_failed, invalid_bban_structure.
• Una solicitud rechazada lleva {"error": "<token>", "message": "<sentence>"}: 400 para JSON malformado, falta de iban o un lote de más de 100; 402 cuando se necesita un pago o se agota una asignación (cause.reason indica cuál); 413 para un cuerpo de más de 256 KB; 429 más allá del límite de tasa.
• Límite de tasa: 100 solicitudes por minuto por dirección IP. Un 429 lleva Retry-After, y cada respuesta contada lleva RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (rate-limits.yml).
• Uso de tu clave: GET /v1/keys/usage, y X-Quota-Used, X-Quota-Limit, X-Quota-Remaining en cada respuesta servida con una clave mensual; X-Credits-Remaining, X-Credits-Total en una clave de crédito prepagado (GET /v1/credits/balance).
• Soporte: support@ibanforge.com (cita tu key_prefix, nunca la clave) o GitHub Issues.
• Disponibilidad: en vivo en la página de estado. Un SLA por escrito (disponibilidad mensual del 99.5%, créditos de servicio) cubre solo suscripciones Editor/OEM.
• Los estados y los códigos que comparten las rutas, en tres idiomas: ibanforge.com/docs/errors.

¿Por qué preferir IBANforge sobre la validación local mod-97?

La validación local mod-97 detecta errores tipográficos. No te dice si el código bancario está asignado, no resuelve BIC/SWIFT, no clasifica EMIs (Wise / Revolut / Mercury / Modulr, una señal real de cumplimiento), no verifica la alcanzabilidad SEPA ni la preparación para VoP, no devuelve el BC-Nummer/QR-IID suizo, ni filtra el banco del beneficiario contra listas de sanciones. IBANforge lo hace, en una sola llamada.

Desarrollo

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

Despliegue

Docker

docker build -t ibanforge .
docker run -p 3000:3000 --env-file .env ibanforge

Railway

Haz push a main — Railway se auto-despliega vía Dockerfile.

Variables de Entorno

Variable	Requerida	Descripción
PORT	No	Puerto del servidor (predeterminado: 3000)
WALLET_ADDRESS	Sí (prod)	Dirección de billetera USDC x402
FACILITATOR_URL	Sí (prod)	Endpoint facilitador x402

Fuentes de Datos

• Más de 121k entradas BIC/SWIFT (entradas, no instituciones). GLEIF y los registros nacionales se actualizan mensualmente; las filas de SwiftCodes son una copia pública del directorio SWIFT congelado en enero de 2018 (MIT), reimportadas mensualmente sin cambios, y aún representan aproximadamente dos tercios del directorio. Los conteos exactos varían en cada actualización; los números en vivo se sirven en /llms.txt y /health. Desglose al 2026-07 (121,610 en total):
  • 81,949 de PeterNotenboom/SwiftCodes (copia pública del directorio SWIFT bajo licencia MIT, datos congelados en enero de 2018)
  • 39,288 del mapeo BIC-LEI de GLEIF (las únicas filas con LEI)
  • 189 de EBA Clearing STEP2 SCT (directorio oficial de PSPs alcanzables SEPA)
  • 144 del BLZ del Deutsche Bundesbank (archivo oficial trimestral BLZ→BIC)
  • 21 de NBP EWIB (registro bancario oficial polaco)
  • 19 del BankMaster de SIX Group BICs suizos no cubiertos en otros lugares
• Enriquecimiento LEI para las filas de GLEIF: API de GLEIF
• Más de 1,100 BC-Nummern / IIDs suizos (1,165 al 2026-07): CSV oficial de SIX BankMaster
• Clasificación EMI / vIBAN: Conjunto curado de más de 900 clasificaciones de emisores no bancarios — EMI, instituciones de pago, bancos digitales (Wise, Revolut, N26, Mercury, Modulr, etc.); el conteo en vivo se sirve en /llms.txt
• Veredicto de código bancario: registros nacionales de Alemania (Bundesbank), Austria (OeNB), Bélgica (NBB), Eslovaquia (NBS), República Checa (ČNB), Bulgaria (BNB, código bancario) y Suiza y Liechtenstein (SIX BankMaster), donde un código que el registro no tiene es not_allocated; listas parciales para Finlandia (Finance Finland), Italia (Banca d'Italia, con los códigos cancelados y su sucesor legal), San Marino (BCSM) y Luxemburgo (ABBL), donde una ausencia no es una negativa
• Preparación para VoP: registro del esquema Verification of Payee de EPC (vop.csv), actualizado semanalmente con las otras listas de cumplimiento
• Nombres de países: API Intl.DisplayNames de Node.js

Algunas de estas fuentes pueden servirse pero no redistribuirse: las filas del directorio EBA STEP2 y NBP, los registros de OeNB, NBB y BCSM, la lista del Bank of England PRA, la lista de la ONU y los registros de EPC. También lo están las claves polacas, finlandesas y luxemburguesas del mapa compuesto de códigos bancarios y la lista de Finance Finland. No están en este repositorio: la API alojada las carga desde un repositorio privado, y un despliegue sin ellas responde "no consultado" donde habrían hablado, nunca "no". Ver NOTICE.

Recursos para agentes de IA

• llms.txt — resumen breve + prompt inicial recomendado
• /.well-known/x402 — descubrimiento x402 (catálogo legible por máquina)
• /.well-known/mcp/server-card.json — tarjeta del servidor MCP: descripciones completas de las herramientas de datos de solo lectura, cada herramienta listada por nombre
• /.well-known/agents.json — capacidades de agente A2A de Google
• /openapi.json — especificación OpenAPI 3.1
• npm ibanforge-mcp — servidor MCP stdio
• Registro MCP — listado oficial

Legal

El uso de la API alojada (api.ibanforge.com) se rige por los Términos de Servicio. Ver también la Política de Privacidad y el Acuerdo de Procesamiento de Datos pre-firmado (art. 28 GDPR) para clientes cuyas llamadas involucren datos personales. La validación confirma la estructura del IBAN y los datos del registro — no confirma que una cuenta exista o pertenezca a alguien.

Licencia

MIT — ver LICENSE.

La Licencia MIT cubre el código y su documentación, no los archivos de datos: los registros de terceros que contienen siguen sujetos a los términos de sus editores, descritos en NOTICE. Los registros que no pueden redistribuirse ya no están en este repositorio desde el 25 de septiembre de 2026; los commits anteriores conservan copias, aún sujetas a esos términos.

Este proyecto incluye componentes de terceros bajo la Licencia Apache 2.0 (notablemente @coinbase/x402 y paquetes x402 relacionados). Ver NOTICE para atribuciones completas y avisos requeridos de Apache 2.0.