What does IBANforge validate?

IBANforge validates IBAN structure (ISO 13616 mod-97 check digits + country-specific BBAN), resolves the associated BIC/SWIFT against 121,000+ BIC entries from public sources (GLEIF, SWIFT directory, Bundesbank, SIX, NBP, EBA Step2 SCT) with LEI enrichment for ~38K rows sourced from GLEIF, looks up Swiss BC-Nummer / IID against ~1,200 SIX BankMaster entries, classifies the issuer (bank, EMI, vIBAN provider, neobank), and flags SEPA Instant + VoP (Verification of Payee, EU 2024/886) reachability.

How much does IBANforge cost?

Pay-per-call in USDC via x402: 0.005 USDC for IBAN validation, 0.003 USDC for BIC lookup, 0.003 USDC for Swiss BC-Nummer lookup, 0.002 USDC per IBAN in batch mode, 0.02 USDC for full compliance check. Or use an API key for 200 free requests per month.

Does IBANforge support MCP (Model Context Protocol)?

Yes. IBANforge ships an official MCP server (com.ibanforge/mcp) with 5 tools: validate_iban, batch_validate_iban, lookup_bic, lookup_ch_clearing, check_compliance. Install in Claude Desktop, Cursor, Cline or any MCP-compatible client via npx or streamable-HTTP at https://api.ibanforge.com/mcp.

Does IBANforge support x402 for autonomous AI agents?

Yes. Every paid endpoint accepts x402 micropayments in USDC on Base L2. Agents discover pricing via /.well-known/x402, pay autonomously and call the API without human onboarding. Listed on Coinbase Bazaar discovery.

How many countries does IBANforge cover?

All 84 countries with a standardized IBAN format, including the full SEPA zone, the UK, Switzerland, and most of MENA and Latin America with IBAN coverage.

What is vIBAN detection and why does it matter?

A virtual IBAN (vIBAN) is an IBAN issued by an EMI or fintech (e.g., Wise, Revolut, Mercury, Modulr) that maps to an underlying account at a partner bank. Detecting vIBANs matters for compliance: VoP often fails on vIBANs and EMI exposure changes the risk profile. IBANforge classifies 30+ known issuer prefixes.

Where does the BIC and Swiss clearing data come from?

BIC/SWIFT data: 121,000+ entries from public sources — GLEIF (Global Legal Entity Identifier Foundation, ~38K rows with LEI enrichment), the SWIFT directory, the Deutsche Bundesbank, SIX, the NBP, and EBA Clearing STEP2 SCT. Swiss data: ~1,200 BC-Nummern from the official SIX BankMaster CSV — the canonical source used by the Swiss banking industry.

Does IBANforge replace a regulated AML/sanctions screening provider?

No. The /v1/iban/compliance endpoint runs OFAC/EU/UN list checks and produces a risk score (0-100) — useful for triage and pre-flight screening. For regulated AML/CFT obligations use a regulated vendor like Refinitiv World-Check, Acuris or ComplyAdvantage.

How fast is IBANforge?

p99 latency under 50ms for /v1/iban/validate (single IBAN). All databases are SQLite WAL with in-process reads — no external lookups. Batch endpoint scales linearly to 100 IBANs per request.

Is IBANforge open-source?

The MCP server (ibanforge-mcp), the SDK (@ibanforge/sdk) and the OpenAPI spec are open-source on GitHub at github.com/cammac-creator/ibanforge. The hosted API and proprietary issuer classification dataset are commercial.

Error Reference

IBANforge uses standard HTTP status codes and returns structured error responses in JSON. This page covers every error you might encounter.

HTTP status codes

Status	Meaning	When it happens
`200`	OK	Request succeeded (note: invalid IBANs still return 200 with `valid: false`)
`400`	Bad Request	Malformed request body, missing fields, or invalid parameters
`402`	Payment Required	No payment header or insufficient/invalid payment
`404`	Not Found	BIC code not found in the database, or unknown endpoint
`500`	Internal Server Error	Unexpected server error (please report these)

Validation error codes

These appear in the response body when an IBAN is invalid. The HTTP status is still 200 — the request itself succeeded, but the IBAN did not pass validation.

Code	Description	Example cause
`invalid_format`	IBAN contains invalid characters or is empty	Special characters, too short, empty string
`unsupported_country`	Country code is not in our registry	`XX12345678` — "XX" is not a valid country
`wrong_length`	IBAN length does not match expected length for the country	Swiss IBAN should be 21 chars, but 19 were provided
`checksum_failed`	MOD-97 checksum verification failed	A digit was changed or transposed

Example: validation error

{
  "valid": false,
  "error": {
    "code": "wrong_length",
    "message": "Expected 21 characters for CH (Switzerland), got 19"
  }
}

Request error codes

These return non-200 HTTP status codes.

400 Bad Request

Code	Description
`invalid_body`	Request body is not valid JSON
`missing_iban`	The `iban` field is missing from the request body
`missing_ibans`	The `ibans` field is missing from the batch request body
`empty_array`	The `ibans` array is empty
`too_many_ibans`	More than 10 IBANs in a batch request
`invalid_bic_format`	BIC code is not 8 or 11 characters

Example: bad request

{
  "error": {
    "code": "too_many_ibans",
    "message": "Maximum 10 IBANs per batch request, got 15"
  }
}

402 Payment Required

Returned when the X-PAYMENT header is missing, expired, or invalid. The response includes payment instructions:

{
  "error": "Payment Required",
  "accepts": {
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "2000",
    "resource": "https://api.ibanforge.com/v1/iban/validate",
    "payTo": "0x...",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  }
}

See x402 Payments for how to handle this.

404 Not Found

Code	Description
`bic_not_found`	No institution found matching the provided BIC code
`not_found`	The requested endpoint does not exist

500 Internal Server Error

If you receive a 500 error, something unexpected happened on our side. The response will contain:

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}

Troubleshooting

"Payment Required" on every request

Make sure you have USDC on the Base network (not Ethereum mainnet)
Check that your wallet private key is correctly set in the WALLET_PRIVATE_KEY environment variable
Verify you are using a compatible x402 client SDK

"Invalid IBAN format" but the IBAN looks correct

Remove any leading/trailing whitespace
Make sure there are no non-ASCII characters (curly quotes, em-dashes, etc.)
The IBAN should only contain letters A-Z and digits 0-9 (spaces are stripped automatically)

"Unsupported country" for a valid country

IBANforge supports 89 countries. Some territories and microstates may not be included yet
Double-check the two-letter country code at the start of the IBAN

"BIC not found" but the code is real

The BIC database contains 121,000+ BIC entries from public sources (GLEIF, SWIFT directory, Bundesbank, SIX, NBP, EBA Step2 SCT) but may not cover every branch
Try the 8-character version (without branch code) — e.g., UBSWCHZH instead of UBSWCHZH80A
Some financial institutions use BIC codes that are not registered with SWIFT/GLEIF

Batch request returns fewer results than expected

Check that your ibans array does not exceed 10 items
Ensure each item is a string — numbers and objects are rejected
The results array always matches the order and count of the input array

Timeout or no response

The API has a 30-second timeout. If you are sending complex batch requests, they should complete well within this limit
Check your network connection and firewall rules
Try the /health endpoint to verify the service is running