IBANValidatorAPI

API REST + MCP Server de validation IBAN avec lookup BIC/SWIFT et micropaiements x402 (Base L2).

Features

• Validation IBAN complète (ISO 13616, modulo 97 avec BigInt)
• Décomposition BBAN (bank code, branch code, account number)
• Lookup BIC/SWIFT depuis base SQLite locale (5800+ entrées)
• 75+ pays supportés (tous les pays IBAN/SEPA)
• Micropaiements x402 : $0.002 USDC par validation
• MCP Server pour agents IA autonomes
• Zéro dépendance API externe — tout est calculé localement

Quick Start

npm install
npm run db:seed   # Build SQLite BIC database
npm run dev       # Start dev server on :3000

API Endpoints

POST /v1/validate — $0.002 USDC

# Dev mode (gratuit)
curl -X POST http://localhost:3000/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-Dev-Skip: true" \
  -d '{"iban": "CH56 0483 5012 3456 7800 9"}'

Response:

{
  "iban": "CH5604835012345678009",
  "valid": true,
  "country": { "code": "CH", "name": "Switzerland" },
  "check_digits": "56",
  "bban": { "bank_code": "04835", "account_number": "012345678009" },
  "bic": { "code": "CRESCHZZ80A", "bank_name": "Credit Suisse (Schweiz) AG", "city": "Zurich" },
  "formatted": "CH56 0483 5012 3456 7800 9",
  "cost_usdc": 0.002,
  "processing_ms": 2
}

POST /v1/batch — $0.015 USDC (max 10 IBANs)

curl -X POST http://localhost:3000/v1/batch \
  -H "Content-Type: application/json" \
  -H "X-Dev-Skip: true" \
  -d '{"ibans": ["CH5604835012345678009", "DE89370400440532013000"]}'

GET /health — Gratuit

curl http://localhost:3000/health

x402 Payments

En production, les routes /v1/* requièrent un paiement x402 en USDC sur Base L2.

# Avec paiement x402
curl -X POST https://api.example.com/v1/validate \
  -H "Content-Type: application/json" \
  -H "Payment-Signature: <x402-payment-token>" \
  -d '{"iban": "CH5604835012345678009"}'

Variables d'environnement requises :

WALLET_ADDRESS=0x...   # Wallet USDC on Base

MCP Server (Claude Desktop)

Ajouter dans claude_desktop_config.json :

{
  "mcpServers": {
    "iban-validator": {
      "command": "npx",
      "args": ["tsx", "/path/to/ibanvalidator/src/mcp/server.ts"]
    }
  }
}

Tools disponibles :

• validate_iban — Valider un IBAN unique
• batch_validate_iban — Valider jusqu'à 10 IBANs

Stack

• Runtime : Node.js 20+ TypeScript
• Framework : Hono
• Base de données : SQLite via better-sqlite3
• Paiements : x402 SDK (@x402/hono)
• MCP : @modelcontextprotocol/sdk

Build & Deploy

npm run build          # Compile TS + seed DB
docker build -t iban . # Build Docker image
docker run -p 3000:3000 -e WALLET_ADDRESS=0x... iban

Data Sources

• Algorithme IBAN : Norme ISO 13616 (publique)
• Données BIC : sigalor/iban-to-bic + registres nationaux
• Pays : ISO 3166-1 (domaine public)