Skip to main content

IBANforge Python SDK

PyPI Python License

Official Python SDK for the IBANforge API — IBAN validation, BIC/SWIFT lookup, Swiss BC-Nummer, and sanctions/SEPA/VoP compliance triage.

Built for AI finance agents and fintech developers. Sync + async clients, full type hints, typed exceptions.

The examples below use recorded API responses. CI executes the Python blocks and checks the annotated output against those recordings. Bank records, source dates, coverage, quotas and prices can change: these assertions do not prove the current live answer. Use the response you receive, including its source and date, for your integration.

Install

pip install ibanforge

Free format check (no key needed)

Save money by pre-filtering bad IBANs before paying for enrichment — and note that a malformed IBAN is a 200 with valid: False, not an exception:

from ibanforge import IBANforge

with IBANforge() as client:                         # no api_key required
    out = client.format_iban("CH93007620116238529XX")
    print(out["valid"])                             # False
    print(out["error"])                             # 'checksum_failed'

    ok = client.format_iban("CH1000230000000012345")
    print(ok["valid"])                              # True
    print(ok["bban"]["bank_code"])                  # '00230'

Quick start with a reusable key

Create a key once and replace ifk_... below, or omit api_key to use your server's IBANFORGE_API_KEY. Keep the key in secret configuration and out of source files and logs. The earlier format check needs no key. The SDK sends the submitted IBAN to the API; it is not an offline validator.

from ibanforge import IBANforge

with IBANforge(api_key="ifk_...") as client:
    out = client.validate_iban("CH1000230000000012345")

    print(out["valid"])                            # True
    print((out.get("country") or {}).get("code"))                    # 'CH'
    print((out.get("bic") or {}).get("bank_name"))                   # 'UBS Switzerland AG'
    print((out.get("bic") or {}).get("code"))                        # 'UBSWCHZH'
    print((out.get("sepa") or {}).get("member"))                     # True
    print((out.get("sepa") or {}).get("schemes"))                    # ['SCT', 'SDD']
    print((out.get("clearing") or {}).get("iid"))                    # '00230'
    print((out.get("clearing") or {}).get("sic"))                    # True
    print((out.get("clearing") or {}).get("qr_iid"))                 # '30005'
    print((out.get("bank_code_check") or {}).get("status"))          # 'verified'
    print((out.get("risk_indicators") or {}).get("country_risk"))    # 'standard'

api_key and base_url fall back to the IBANFORGE_API_KEY and IBANFORGE_API_BASE environment variables — the same names the MCP server reads, so one setting configures both.

Read the bank-code result separately from the checksum

A valid checksum does not establish that the bank code is allocated. bank_code_check describes the evidence available for that code, independently of valid:

from ibanforge import IBANforge

with IBANforge(api_key="ifk_...") as client:
    # Réponse enregistrée : format valide, code banque absent du registre utilisé.
    ghost = client.validate_iban("CH9300762011623852957")

    print(ghost["valid"])                            # True
    print(ghost["bank_code_check"]["status"])        # 'not_in_register'
    print(ghost["bank_code_check"]["authoritative"]) # True
    print(ghost["bic"])                              # None
    print(ghost["clearing"])                         # None
    print(ghost["next_steps"][0]["code"])            # 'bank_code_not_allocated'

valid and bank_code_check answer different questions. In the recorded example, not_in_register with authoritative: true reports a code absent from the exhaustive register used, at its reference date. A partial source cannot prove absence. An unavailable source is not a negative result, and a verified code can also carry retirement information. Preserve register, its dates, reason, and any retirement or successor fields in your review record.

A missing BIC stays unknown; do not invent one or silently replace supplied banking details. These checks do not establish account existence, account ownership, or authorization to pay. SEPA and VoP fields describe country or participant coverage, not a beneficiary-name match. See the validation response guide.

For a fixture or demo, request a synthetic test IBAN and inspect the proof returned. It does not identify a usable payment account:

from ibanforge import IBANforge

with IBANforge() as client:                         # free, no key
    t = client.test_iban(country="CH")
    proof = t["test_ibans"][0]["proof"]["bank_code_check"]
    print(proof["status"])                          # 'verified'
    print(proof["authoritative"])                   # True

Get a reusable key without e-mail

from ibanforge import IBANforge

key = IBANforge.generate_api_key()
print(key["monthly_limit"])                         # 25
# key["api_key"] is shown ONCE — store it now.

No address, card or confirmation is needed. Store the key in your secret configuration, reuse it for subsequent calls, and read usage() for its actual allowance. Normally this key provides 25 REST requests per month; temporary creation protection can lower that allowance, so read monthly_limit from the response. Do not create a key per request.

After the key has served a call, POST /v1/keys/claim with Authorization: Bearer ifk_… can raise its allowance: an explicitly supplied mailbox and a six-digit code give 200 requests per month; an x402 payment made on the key gives 200 requests once. An exhausted quota does not authorize sending an address or making a payment on the user's behalf. Follow the API's error details and retry delay.

The existing email argument and code option remain supported for callers who explicitly choose that route. No email is inferred from environment variables or other accounts.

Quick start (async)

This sends two separate validation requests, each metered separately. Keep concurrency bounded in a larger import. A failed request makes gather raise; other requests may already have completed and consumed units. Use validate_batch when a single ordered batch is a better fit, and preserve per-input results and unknown fields.

import asyncio
from ibanforge import AsyncIBANforge

IBANS = ["CH1000230000000012345", "DE89370400440532013000"]

async def main():
    async with AsyncIBANforge(api_key="ifk_...") as client:
        results = await asyncio.gather(*[client.validate_iban(i) for i in IBANS])
        print(len(results))                         # 2
        print(sum(1 for r in results if r["valid"]))  # 2

asyncio.run(main())

All endpoints

The amounts below are per-call x402 prices in USDC, not charges added to an API-key allowance. On a key, each metered call uses one request or credit; a batch uses one per submitted IBAN, including invalid entries. Free reference routes remain free. Read usage() for the key's allowance and pricing for current plans and payment options. This SDK does not buy credits or sign x402 payments automatically.

Method x402 price or free route What it does
format_iban(iban) free Pure mod-97 + structure check. Pre-filter malformed IBANs before paying.
validate_iban(iban) $0.005 Full enrichment — BIC, EMI/vIBAN flag, SEPA + VoP, bank-code register check, Swiss BC-Nummer for CH/LI
validate_batch([iban, ...]) $0.002 / IBAN Up to 100 IBANs in one call. CSV cleanup, payout list triage.
lookup_bic(code) $0.003 BIC/SWIFT → bank name, country, city, LEI, registered address. Fields depend on the source and may be absent.
lookup_ch_clearing(iid) $0.003 Swiss BC-Nummer / IID → SIX rail participation + QR-IID, with the source and dates returned by the API.
check_compliance(iban) $0.02 Sanctions (bank BIC) + FATF + SEPA Instant + VoP + risk score 0–100
validate_reference(reference) free QR-bill (QRR), ISO 11649 (RF/SCOR), Belgian OGM/VCS or Finnish reference, checked against the dated document that publishes the rule
check_address(scheme, address) free A structured ISO 20022 postal address measured against a scheme's rules (sps, hvps_plus, fedwire), each finding citing its guideline
iban_structures() free Every supported country and its IBAN length
iban_structure(country) free One country's BBAN template — offsets, lengths, charsets
test_iban(country=...) free Synthetic test IBANs with the bank-code proof available at generation
credit_bundles() free Prepaid packs and their per-call price
demo() free Worked examples of every endpoint
usage() free This key's quota for the current month
health() free API version, database size
IBANforge.generate_api_key(email=None) free Reusable key without e-mail; read its returned quota

In practice:

from ibanforge import IBANforge

with IBANforge(api_key="ifk_...") as client:
    batch = client.validate_batch(["CH1000230000000012345", "DE89370400440532013000"])
    print(batch["count"])                           # 2
    print(batch["valid_count"])                     # 2

    bic = client.lookup_bic("UBSWCHZH80A")
    print(bic["institution"])                       # 'UBS Switzerland AG'
    print(bic["lei"])                               # '549300WOIFUSNYH0FL22'

    ch = client.lookup_ch_clearing("230")
    print(ch["institution"]["name"])                # 'UBS Switzerland AG'
    print(ch["payment_services"]["sic"])            # True
    print(ch["qr_iid"])                             # '30005'

    structures = client.iban_structures()
    print(structures["total"])                      # 89

    ch_structure = client.iban_structure("CH")
    print(ch_structure["iban_length"])              # 21
    print(ch_structure["bban_pattern"])             # '5!n12!c'

    packs = client.credit_bundles()
    print(packs["bundles"][0]["credits"])           # 1000
    print(packs["bundles"][0]["price_usdc"])        # 5

    d = client.demo()
    print(len(d["iban_examples"]) > 0)              # True

    print(client.usage()["limit"])                  # 200
    print(client.health()["status"])                # 'ok'

Compliance triage

The score is nested under compliance. There is no top-level risk_score, and no recommended_action. The output below is a recorded example, not a current clearance. Read each check's screened state, flags and source dates in meta: an empty match list or a low score does not establish that every source was available.

from ibanforge import IBANforge

with IBANforge(api_key="ifk_...") as client:
    out = client.check_compliance("GB29NWBK60161331926819")

    print(type(out["compliance"]["risk_score"]).__name__)   # 'int'
    print(out["compliance"]["risk_level"])                  # 'low'
    print(out["compliance"]["sanctions"]["matched_lists"])  # []
    print(out["compliance"]["sanctions"]["fatf_status"])    # 'member'
    print(out["meta"]["scope"])                             # 'bank_bic_only'

Sanctions screening is at the bank (BIC8) level — it does not screen the beneficiary name and is not a regulated AML/CFT product. risk_level: 'unassessable' means nothing could be screened; it is the absence of a verdict, never a favourable one, and risk_score is then None.

Error handling

HTTP failures raise typed exceptions derived from IBANforgeError, with .status, .code (the API's error slug, when present) and .body. Transport and timeout failures remain httpx.RequestError subclasses; catching only IBANforgeError does not catch them. A response-decoding failure can also occur without an API verdict.

from ibanforge import IBANforge, AuthError, InvalidInputError

with IBANforge(api_key="ifk_wrong") as client:
    try:
        client.usage()
    except AuthError as e:
        print(e.status)                             # 401
        print(e.code)                               # 'invalid_key'

with IBANforge() as client:
    try:
        client.lookup_bic("NOTABIC")
    except InvalidInputError as e:
        print(e.status)                             # 400
        print(e.code)                               # 'invalid_bic_format'
Class HTTP When
AuthError 401 / 403 Read the error code: invalid/revoked key or an access restriction; verification_required specifically requests mailbox verification
PaymentRequiredError 402 No usable allowance or payment proof. The response body may include an x402 challenge; inspect its shape and the current key usage before choosing an authorized next step
QuotaExhaustedError 429 Only HTTP 429 with error: quota_exceeded; exhausted API-key quota can instead return 402
RateLimitError 429 Other HTTP 429 responses; read the reason and retry delay, then use bounded backoff
PayloadTooLargeError 413 The body is over the limit — split it, do not retry the same payload
InvalidInputError other 4xx Malformed request (a malformed IBAN is a 200, see above)
APIError 5xx Server-side failure; keep the result unavailable and retry only under a bounded policy

Keep failed requests separate from invalid input. Neither a network error nor a 402/429/5xx response is a bank-code verdict. Do not loop on key creation or purchase credits automatically. A retry after an uncertain response may consume another unit; stop the workflow or queue it for review when its retry budget is exhausted.

For LLM agents (LangChain, LlamaIndex, CrewAI, AutoGen)

The IBANforge API is also available as a native MCP server (npx -y ibanforge-mcp) and via x402 micropayments — see the agent guide. For Python-first agents, the SDK above is usually enough.

Configuration

from ibanforge import IBANforge

client = IBANforge(
    api_key="ifk_...",     # or the IBANFORGE_API_KEY environment variable
    base_url=None,         # or IBANFORGE_API_BASE; defaults to api.ibanforge.com
    timeout=30.0,          # seconds, default
    user_agent="my-app/1.2",
)
print(client.health()["version"] is not None)       # True
client.close()

License

MIT.

Metadata

Release files for ibanforge 1.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ibanforge 1.10.0
File Size Uploaded Provenance Actions
ibanforge-1.10.0.tar.gz 24.6 kB Without provenance Details for ibanforge-1.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ibanforge 1.10.0
File Interpreter ABI Platform Actions
ibanforge-1.10.0-py3-none-any.whl Python 3 none any Details for ibanforge-1.10.0-py3-none-any.whl

Total release size: 47.3 kB

Release files / ibanforge-1.10.0.tar.gz

Download URL ibanforge-1.10.0.tar.gz
Size 24.6 kB
Tags Source
SHA-256 checksum
How to use checksums
ddb07f8d4b50dce60439eddb90afae9c6d152644ac126a0fac7c57cda4c03c11
BLAKE2b-256 checksum
How to use checksums
e1068dea7cc2ba2c67135b895c02957eb4e728652f616432143850298f1786c8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / ibanforge-1.10.0-py3-none-any.whl

Download URL ibanforge-1.10.0-py3-none-any.whl
Size 22.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4c95059c486bc033355fcb906105eb66c3539fc4dbbe878cacffb66533bf03d2
BLAKE2b-256 checksum
How to use checksums
f7c5786ef85265ee34d099e6f71a31369cabc094e7ca5192303e596b191c8e34
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for ibanforge 1.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page