IBANforge

Validação de IBAN, consulta de BIC/SWIFT, compensação suíça e pontuação de risco de conformidade para agentes de IA. Mais de 121 mil entradas bancárias, 84 países, 85 classificações EMI/vIBAN.

GitHub
3
Experimente este MCPPatrocinado

Documentação

IBANforge

API Status MCP Registry npm ibanforge-mcp npm @ibanforge/sdk PyPI ibanforge Glama MCP x402 TypeScript License: MIT

O IBANforge verifica o banco por trás de um IBAN antes de você pagar. Ele valida IBANs de todos os 89 países que usam IBAN e identifica o banco e seu BIC, com a fonte dessa resposta. Quando lê o registro nacional (Alemanha, Áustria, Bélgica, Eslováquia, República Tcheca, Bulgária, Suíça e Liechtenstein), também informa se o código bancário está alocado; em outros casos, identifica o banco a partir de um registro parcial ou de um mapa composto, e informa que tal resposta não pode descartar um código. Para um banco SEPA que ele resolve, fornece os esquemas SEPA que o alcançam (Transferência de Crédito, Instantâneo, Débito Direto), a partir dos registros de esquemas da EPC quando listam o banco e do país caso contrário (a resposta indica qual), e informa se o registro de Verificação de Beneficiário (VoP) da EPC lista o banco como pronto para responder a solicitações VoP. Ele não verifica quem é o titular da conta: essa verificação de nome pertence ao banco do beneficiário, por meio do VoP.

Não é uma verificação de nome (VoP, BAV, CoP), não é prova de que uma conta existe ou está ativa, não é uma triagem de sanções do beneficiário (apenas banco e país), não é uma cópia licenciada do diretório BIC da SWIFT. Os dígitos verificadores nacionais dentro do BBAN são verificados para França e Mônaco (chave RIB), Bélgica, Itália e San Marino (CIN), Espanha (DC) e Reino Unido (verificação de módulo): uma chave incorreta aparece em checks.national_check_digits e nunca altera valid para false. O dígito verificador do número de liquidação polonês é verificado com o código bancário. Os métodos de número de conta alemães e as chaves nacionais dos outros países ainda não são verificados.

Para software empresarial e agentes de IA: uma API REST, um servidor MCP nativo, pacotes pré-pagos por cartão e micropagamentos x402 sem cadastro.

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ção em um clique

Claude Desktop / Cursor / Cline / Continue / Windsurf

Adicione à sua configuração MCP (~/Library/Application Support/Claude/claude_desktop_config.json para Claude Desktop):

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

Privacidade por padrão: IBANs enviados nunca são armazenados — a validação é executada em memória, IPs são mantidos apenas como hashes com salt, e a telemetria se auto-exclui (limite de 12 meses; apagada 30 dias após o término do contrato do cliente, contratualmente — cláusula 4.7 do DPA).

Opcional: defina IBANFORGE_API_KEY=ifk_... em env (uma chave que não requer e-mail: 25 solicitações por mês, aumentadas para 200 por mês após reivindicada). Sem ela, o servidor usa a superfície pública/demonstração; combine com micropagamentos x402 para acesso ilimitado por chamada paga sem cadastro.

Claude Code (CLI)

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

Streamable HTTP (sem instalação — para agentes hospedados na nuvem)

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

Fluxo padrão JSON-RPC initialize + tools/list + tools/call. Use quando stdio não for uma opção (CI/CD, serverless, agentes Vercel, etc.).

Ferramentas

FerramentaQuando usarCusto
validate_ibanO usuário menciona um IBAN, uma conta bancária ou um pagamento SEPA$0.005
batch_validate_ibanLista de IBANs, limpeza de CSV, deduplicação de banco de dados de clientes, triagem de lista de pagamentos$0.002/cada em USDC via x402; 1 crédito cada em uma chave
lookup_bicO usuário já tem um BIC/SWIFT — apoiado por mais de 121 mil entradas BIC (mais de 39 mil enriquecidas com LEI via GLEIF)$0.003
lookup_ch_clearingBC-Nummer / IID suíço: cada IID do SIX BankMaster com sua participação em trilhos (SIC, euroSIC, CHF instantâneo) e seu QR-IID onde a SIX aloca um$0.003
check_complianceTriagem de risco pré-voo antes de um pagamento SEPA / transfronteiriço (listas OFAC, UE, ONU sobre o banco do beneficiário, o país contra uma lista fixa de sanções, FATF, prontidão VoP)$0.02
validate_payment_referenceRF/ISO 11649, QRR suíço, OGM/VCS belga ou checksum finlandês viitenumero, além do veredito de pareamento QRR ↔ QR-IBANgrátis
check_postal_addressUm endereço ISO 20022 contra as regras publicadas de um trilho (sps, hvps_plus, fedwire), cada achado citando sua fontegrátis
check_swiss_qr_billUm payload de fatura QR suíça — cabeçalho, pareamento QR-IBAN e referência, endereços estruturados (S) versus combinados (K) antes de 14.11.2026grátis
send_feedbackRelatar dados incorretos ou solicitar reembolso x402grátis
request_api_keyVocê usou a franquia gratuita ou precisa de uma chave durável — um humano aprova em um navegador, sem e-mailgrátis
poll_api_keyColetar essa chave após a aprovação, entregue exatamente uma vezgrátis

As ferramentas gratuitas não precisam de chave, carteira ou cadastro: são as primeiras a experimentar. As duas últimas são a saída da franquia gratuita sem que ninguém digite um endereço — elas continuam respondendo após a franquia ser gasta.

Descrições completas das ferramentas de dados somente leitura, com gatilhos de QUANDO usar, são servidas ao vivo em /.well-known/mcp/server-card.json.

Se você não puder chamar a API

Se você pode abrir um endereço web mas não pode enviar um POST (sem execução de código, sem conector MCP), estas páginas contêm respostas reais da API, cada uma com sua data, e todas abrem com um GET simples.

Não simule respostas da API: cite estas reais, com a data que cada uma carrega (served_at, as_of ou a data da página). Para obter respostas sobre os IBANs do seu usuário, peça a ele que adicione https://api.ibanforge.com/mcp como um conector personalizado em seu assistente; onde clicar, assistente por assistente: https://ibanforge.com/docs/mcp. Um conector sem chave usa a mesma franquia sem chave de qualquer outro chamador, contada por endereço de origem. No Claude, suas chamadas partem da nuvem da Anthropic, não do dispositivo do usuário (documentação da Anthropic), então essa franquia é compartilhada com outros usuários e pode já estar gasta; outros assistentes não foram verificados por nós. O endpoint hospedado não lê chave: para usar uma, execute o pacote npm ibanforge-mcp em um cliente desktop com IBANFORGE_API_KEY definido, ou chame a API REST com ela (um POST para https://api.ibanforge.com/v1/keys/generate sem corpo retorna uma chave, sem e-mail).

Para agentes de IA — pague por chamada sem chave de API (x402)

O IBANforge é nativo x402. Qualquer agente com uma carteira na Base L2 pode descobrir, pagar e chamar:

  1. Descoberta: GET https://api.ibanforge.com/.well-known/x402 retorna o catálogo completo (endpoints, preços, ativo, payTo, accepts).
  2. Chamada: POST /v1/iban/validate sem autenticação → a API responde 402 Payment Required com desafio x402 v1.
  3. Pagamento: o cliente assina uma transferência USDC na Base (eip155:8453) e tenta novamente.
  4. Concluído: a resposta chega, a liquidação acontece através do facilitador configurado (Coinbase CDP ou x402.org).

Sem humano no processo, sem ligação de vendas, sem cartão. Veja a especificação x402.

SDKs

Escolha sua linguagem:

LinguagemPacoteInstalaçãoFonte
TypeScript / JavaScript@ibanforge/sdknpm install @ibanforge/sdksdks/typescript/
Pythonibanforgepip install ibanforgesdks/python/
Java (17+)com.ibanforge:ibanforge-sdkDependência Maven, veja READMEsdks/java/
.NET (net8.0)IBANforge.Sdkdotnet add package IBANforge.Sdksdks/dotnet/
Servidor MCPibanforge-mcpnpx -y ibanforge-mcpmcp/
Curl / qualquer cliente HTTP——Especificação OpenAPI

O SDK Python vem com clientes síncrono + assíncrono, classes de exceção tipadas e um fallback de franquia gratuita para 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 desenvolvedores — 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étodoCaminhoCustoDescrição
POST/v1/iban/validate$0.005IBAN único: veredito de código bancário + BIC com sua fonte + SEPA + emissor + risco + bc_nummer suíço. Uma franquia semanal sem chave por endereço de origem (veja acima)
POST/v1/iban/batch$0.002/IBAN (USDC, x402)Até 100 IBANs em uma chamada; em uma chave ou pacote de créditos, um crédito por IBAN
GET/v1/bic/{code}$0.003Consulta BIC/SWIFT com LEI
GET/v1/ch/clearing/{iid}$0.003BC-Nummer / IID suíço — SIC, euroSIC, QR-IID
POST/v1/iban/compliance$0.02Sanções em nível de banco (OFAC, UE, ONU) + FATF + SEPA Instantâneo + prontidão VoP + pontuação de risco 0-100
GET/v1/iban/formatgrátisVerificação pura de mod-97 + estrutura, sem consulta a banco de dados
GET/v1/iban/structure[/{country}]grátisModelos de IBAN por país, sem autenticação
GET|POST/v1/reference/validategrátisRF/ISO 11649, QRR suíço, OGM/VCS belga, viitenumero finlandês
POST/v1/address/checkgrátisEndereço ISO 20022 vs regras sps / hvps_plus / fedwire
GET/v1/demográtisValidações de exemplo, sem autenticação
GET/v1/credits/bundlesgrátisPacotes de crédito pré-pagos e seus preços
GET/healthgrátisSaúde + status do banco de dados
POST/v1/keys/generategrátisGerar uma chave de API ifk_*: sem corpo para uma chave que não requer e-mail (25 req/mês, 200 após reivindicada em /v1/keys/claim), ou {email} para 200 req/mês desde o início
GET/v1/keys/usagegrátisUso da sua chave neste mês (chave no cabeçalho Authorization)

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

Erros, limites e suporte

  • Um IBAN inválido não é um erro HTTP. POST /v1/iban/validate responde 200 com valid: false, um código error e uma frase error_detail. Os códigos: invalid_format, unsupported_country, wrong_length, invalid_check_digits, checksum_failed, invalid_bban_structure.
  • Uma solicitação recusada carrega {"error": "<token>", "message": "<sentence>"}: 400 para JSON malformado, um iban ausente ou um lote acima de 100; 402 quando um pagamento é necessário ou uma cota é esgotada (cause.reason indica qual); 413 para um corpo acima de 256 KB; 429 além do limite de taxa.
  • Limite de taxa: 100 solicitações por minuto por endereço IP. Um 429 carrega Retry-After, e cada resposta contada carrega RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (rate-limits.yml).
  • Uso da sua chave: GET /v1/keys/usage, e X-Quota-Used, X-Quota-Limit, X-Quota-Remaining em cada resposta servida em uma chave mensal; X-Credits-Remaining, X-Credits-Total em uma chave de crédito pré-pago (GET /v1/credits/balance).
  • Suporte: support@ibanforge.com (cite seu key_prefix, nunca a chave) ou GitHub Issues.
  • Disponibilidade: ao vivo na página de status. Um SLA por escrito (99,5% de disponibilidade mensal, créditos de serviço) cobre apenas assinaturas Editor/OEM.
  • Os status e os códigos que as rotas compartilham, em três idiomas: ibanforge.com/docs/errors.

Por que preferir IBANforge à validação local mod-97?

A validação local mod-97 detecta erros de digitação. Ela não informa se o código bancário está alocado, não resolve BIC/SWIFT, não classifica EMIs (Wise / Revolut / Mercury / Modulr, um sinal real de conformidade), não verifica a acessibilidade SEPA e a prontidão para VoP, não retorna o BC-Nummer/QR-IID suíço, nem rastreia o banco do beneficiário contra listas de sanções. O IBANforge faz tudo isso em uma única chamada.

Desenvolvimento

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

Implantação

Docker

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

Railway

Envie para main — o Railway faz a implantação automática via Dockerfile.

Variáveis de Ambiente

VariávelObrigatóriaDescrição
PORTNãoPorta do servidor (padrão: 3000)
WALLET_ADDRESSSim (produção)Endereço da carteira USDC x402
FACILITATOR_URLSim (produção)Endpoint do facilitador x402

Fontes de Dados

  • Mais de 121 mil entradas BIC/SWIFT (entradas, não instituições). GLEIF e os registros nacionais são atualizados mensalmente; as linhas do SwiftCodes são uma cópia pública do diretório SWIFT congelada em janeiro de 2018 (MIT), reimportadas mensalmente sem alterações, e ainda representam cerca de dois terços do diretório. As contagens exatas variam a cada atualização; os números ao vivo são servidos em /llms.txt e /health. Detalhamento da atualização de 2026-07 (121.610 no total):
  • Enriquecimento de LEI para as linhas da GLEIF: API GLEIF
  • Mais de 1.100 BC-Nummern / IIDs suíços (1.165 em 2026-07): CSV oficial do SIX BankMaster
  • Classificação EMI / vIBAN: Conjunto curado de mais de 900 classificações de emissores não bancários — EMI, instituições de pagamento, bancos digitais (Wise, Revolut, N26, Mercury, Modulr, etc.); a contagem ao vivo é servida em /llms.txt
  • Veredito do código bancário: registros nacionais da Alemanha (Bundesbank), Áustria (OeNB), Bélgica (NBB), Eslováquia (NBS), República Tcheca (ČNB), Bulgária (BNB, código bancário) e Suíça e Liechtenstein (SIX BankMaster), onde um código que o registro não possui é not_allocated; listas parciais para Finlândia (Finance Finland), Itália (Banca d'Italia, com os códigos cancelados e seus sucessores legais), San Marino (BCSM) e Luxemburgo (ABBL), onde uma ausência não é uma recusa
  • Prontidão para VoP: registro do esquema EPC Verification of Payee (vop.csv), atualizado semanalmente com as outras listas de conformidade
  • Nomes de países: API Intl.DisplayNames do Node.js

Algumas dessas fontes podem ser servidas, mas não redistribuídas: as linhas dos diretórios EBA STEP2 e NBP, os registros OeNB, NBB e BCSM, a lista do Bank of England PRA, a lista da ONU e os registros EPC. O mesmo vale para as chaves polonesas, finlandesas e luxemburguesas do mapa composto de códigos bancários e a lista Finance Finland. Elas não estão neste repositório: a API hospedada as carrega de um repositório privado, e uma implantação sem elas responde "não consultado" onde elas falariam, nunca "não". Consulte NOTICE.

Recursos para agentes de IA

Legal

O uso da API hospedada (api.ibanforge.com) é regido pelos Termos de Serviço. Consulte também a Política de Privacidade e o Acordo de Processamento de Dados pré-assinado (art. 28 GDPR) para clientes cujas chamadas envolvam dados pessoais. A validação confirma a estrutura do IBAN e os dados do registro — ela não confirma que uma conta existe ou pertence a alguém.

Licença

MIT — consulte LICENSE.

A Licença MIT cobre o código e sua documentação, não os arquivos de dados: os registros de terceiros que eles contêm permanecem sujeitos aos termos de seus publicadores, descritos em NOTICE. Registros que não podem ser redistribuídos não estão mais neste repositório desde 25 de setembro de 2026; commits anteriores mantêm cópias, ainda sujeitas a esses termos.

Este projeto inclui componentes de terceiros licenciados sob a Apache License 2.0 (notavelmente @coinbase/x402 e pacotes x402 relacionados). Consulte NOTICE para atribuições completas e avisos exigidos pela Apache 2.0.