ibanforge 1.1.0__tar.gz

ibanforge-1.1.0/.gitignore

@@ -0,0 +1,18 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store
+data/*.sqlite-wal
+data/*.sqlite-shm
+coverage/
+*.tsbuildinfo
+.superpowers/
+# Append to .gitignore
+mcp/node_modules/
+mcp/dist/
+
+# Secret tokens generated by mcp-publisher login
+.mcpregistry_*_token
+mcp/.mcpregistry_*_token
+.vercel

ibanforge-1.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: ibanforge
+Version: 1.1.0
+Summary: Official Python SDK for the IBANforge API — IBAN validation, BIC/SWIFT lookup, Swiss BC-Nummer, sanctions/SEPA/VoP compliance triage.
+Project-URL: Homepage, https://ibanforge.com
+Project-URL: Documentation, https://ibanforge.com/docs
+Project-URL: Agent Guide, https://ibanforge.com/agents
+Project-URL: OpenAPI Reference, https://ibanforge.com/openapi
+Project-URL: Repository, https://github.com/cammac-creator/ibanforge
+Project-URL: Issue Tracker, https://github.com/cammac-creator/ibanforge/issues
+Project-URL: Changelog, https://github.com/cammac-creator/ibanforge/blob/main/CHANGELOG.md
+Author-email: IBANforge <support@ibanforge.com>
+License-Expression: MIT
+Keywords: ai-agent,api,banking,bic,compliance,fintech,iban,sanctions,sepa,swift,swiss,validation,vop,x402
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: respx>=0.20; extra == 'test'
+Description-Content-Type: text/markdown
+
+# IBANforge Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/ibanforge.svg)](https://pypi.org/project/ibanforge/)
+[![Python](https://img.shields.io/pypi/pyversions/ibanforge.svg)](https://pypi.org/project/ibanforge/)
+[![License](https://img.shields.io/pypi/l/ibanforge.svg)](https://pypi.org/project/ibanforge/)
+
+Official Python SDK for the [IBANforge API](https://ibanforge.com) — 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.
+
+## Install
+
+```bash
+pip install ibanforge
+```
+
+## Get a free API key (1 line, no signup form)
+
+```python
+from ibanforge import IBANforge
+
+key = IBANforge.generate_api_key("you@example.com")
+print(key["api_key"])  # ifk_… — store it, it's shown only once
+print(key["monthly_limit"])  # 200 free requests/month
+```
+
+When the monthly quota is exhausted, the API automatically falls back to advertising x402 payment requirements (no dead-end). Your key resumes working at the start of the next month.
+
+## Quick start (sync)
+
+```python
+from ibanforge import IBANforge
+
+with IBANforge(api_key="ifk_...") as client:
+    out = client.validate_iban("CH9300762011623852957")
+
+    print(out["valid"])                  # True
+    print(out["country"])                # {"code": "CH", "name": "Switzerland"}
+    print(out["bic"]["bankName"])        # "UBS Switzerland AG"
+    print(out["bic"]["lei"])             # "BFM8T61CT2L1QCEMIK50"
+    print(out["sepa"])                   # {"reachable": True, "instant": True}
+    print(out["vop"]["participant"])     # True
+    print(out["ch_clearing"]["bc_nummer"])  # "762"
+    print(out["risk_score"])             # 5
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+from ibanforge import AsyncIBANforge
+
+async def main():
+    async with AsyncIBANforge(api_key="ifk_...") as ibanforge:
+        # Fan out 100 validations concurrently
+        results = await asyncio.gather(*[
+            ibanforge.validate_iban(iban) for iban in ibans
+        ])
+        valid = sum(1 for r in results if r["valid"])
+        print(f"{valid}/{len(results)} valid")
+
+asyncio.run(main())
+```
+
+## All endpoints
+
+| Method | Cost | What it does |
+|---|---|---|
+| `format_iban(iban)` | **free** | Pure mod-97 + structure check. Use to pre-filter malformed IBANs before paying. |
+| `validate_iban(iban)` | $0.005 | Full enrichment — BIC, country, EMI/vIBAN flag, SEPA + VoP, risk score, 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 | Resolve BIC/SWIFT into bank name, country, city, LEI, address. 121,197 GLEIF entries. |
+| `lookup_ch_clearing(iid)` | $0.003 | Resolve a Swiss BC-Nummer / IID. The only API with this data. |
+| `check_compliance(iban)` | $0.02 | Pre-flight risk triage: sanctions (OFAC/EU/UN), FATF, SEPA Instant, VoP, risk score 0-100, recommended_action ∈ {allow, review, block} |
+| `usage()` | free | Current month quota usage for your key |
+| `health()` | free | API version, BIC count, uptime |
+
+## Free format check (no key needed)
+
+Save money by pre-filtering bad IBANs before paying for enrichment:
+
+```python
+from ibanforge import IBANforge
+
+with IBANforge() as client:  # no api_key required
+    out = client.format_iban("CH9300762011623852957")
+    if not out["valid"]:
+        print("Skip:", out["error"])      # e.g. "checksum_failed"
+    else:
+        print(out["bban"]["bank_code"])   # "00762"
+```
+
+## Compliance triage (the killer feature)
+
+```python
+out = client.check_compliance("RU1234567890123456789012345678")  # made-up RU
+print(out["risk_score"])             # high (Russia + FATF flag)
+print(out["recommended_action"])     # "block" | "review" | "allow"
+print(out["sanctions"]["lists"])     # ["OFAC", "EU"] etc.
+print(out["fatf"]["list"])           # "grey" | "black" | "none"
+print(out["sepa"]["reachable"])
+```
+
+## Error handling
+
+The SDK raises typed exceptions — catch the specific class you care about, or the base `IBANforgeError`:
+
+```python
+from ibanforge import (
+    IBANforge,
+    AuthError, PaymentRequiredError, QuotaExhaustedError,
+    RateLimitError, InvalidInputError, APIError, IBANforgeError,
+)
+
+with IBANforge(api_key="ifk_...") as client:
+    try:
+        out = client.validate_iban("not-an-iban")
+    except InvalidInputError as e:
+        print(e.body["error"])  # "invalid_format"
+    except AuthError:
+        print("Bad or revoked API key")
+    except PaymentRequiredError as e:
+        # Your quota is exhausted — switch to x402 to keep going
+        print(e.body["accepts"])  # x402 payment requirements
+    except RateLimitError:
+        print("Slow down")
+    except APIError as e:
+        print(f"Server error {e.status} — retry with backoff")
+    except IBANforgeError as e:
+        print(f"Other: {e}")
+```
+
+## 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](https://ibanforge.com/agents). For Python-first agents, the SDK above is usually enough.
+
+## Configuration
+
+```python
+client = IBANforge(
+    api_key="ifk_...",
+    base_url="https://api.ibanforge.com",  # default
+    timeout=30.0,                          # seconds, default
+    user_agent="my-app/1.2",               # custom UA
+)
+```
+
+## Links
+
+- API documentation: <https://ibanforge.com/docs>
+- Interactive OpenAPI: <https://ibanforge.com/openapi>
+- Agent guide: <https://ibanforge.com/agents>
+- TypeScript SDK: [`@ibanforge/sdk`](https://www.npmjs.com/package/@ibanforge/sdk)
+- MCP server: [`ibanforge-mcp`](https://www.npmjs.com/package/ibanforge-mcp)
+- Source: <https://github.com/cammac-creator/ibanforge>
+
+## License
+
+MIT.

ibanforge-1.1.0/README.md

@@ -0,0 +1,159 @@
+# IBANforge Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/ibanforge.svg)](https://pypi.org/project/ibanforge/)
+[![Python](https://img.shields.io/pypi/pyversions/ibanforge.svg)](https://pypi.org/project/ibanforge/)
+[![License](https://img.shields.io/pypi/l/ibanforge.svg)](https://pypi.org/project/ibanforge/)
+
+Official Python SDK for the [IBANforge API](https://ibanforge.com) — 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.
+
+## Install
+
+```bash
+pip install ibanforge
+```
+
+## Get a free API key (1 line, no signup form)
+
+```python
+from ibanforge import IBANforge
+
+key = IBANforge.generate_api_key("you@example.com")
+print(key["api_key"])  # ifk_… — store it, it's shown only once
+print(key["monthly_limit"])  # 200 free requests/month
+```
+
+When the monthly quota is exhausted, the API automatically falls back to advertising x402 payment requirements (no dead-end). Your key resumes working at the start of the next month.
+
+## Quick start (sync)
+
+```python
+from ibanforge import IBANforge
+
+with IBANforge(api_key="ifk_...") as client:
+    out = client.validate_iban("CH9300762011623852957")
+
+    print(out["valid"])                  # True
+    print(out["country"])                # {"code": "CH", "name": "Switzerland"}
+    print(out["bic"]["bankName"])        # "UBS Switzerland AG"
+    print(out["bic"]["lei"])             # "BFM8T61CT2L1QCEMIK50"
+    print(out["sepa"])                   # {"reachable": True, "instant": True}
+    print(out["vop"]["participant"])     # True
+    print(out["ch_clearing"]["bc_nummer"])  # "762"
+    print(out["risk_score"])             # 5
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+from ibanforge import AsyncIBANforge
+
+async def main():
+    async with AsyncIBANforge(api_key="ifk_...") as ibanforge:
+        # Fan out 100 validations concurrently
+        results = await asyncio.gather(*[
+            ibanforge.validate_iban(iban) for iban in ibans
+        ])
+        valid = sum(1 for r in results if r["valid"])
+        print(f"{valid}/{len(results)} valid")
+
+asyncio.run(main())
+```
+
+## All endpoints
+
+| Method | Cost | What it does |
+|---|---|---|
+| `format_iban(iban)` | **free** | Pure mod-97 + structure check. Use to pre-filter malformed IBANs before paying. |
+| `validate_iban(iban)` | $0.005 | Full enrichment — BIC, country, EMI/vIBAN flag, SEPA + VoP, risk score, 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 | Resolve BIC/SWIFT into bank name, country, city, LEI, address. 121,197 GLEIF entries. |
+| `lookup_ch_clearing(iid)` | $0.003 | Resolve a Swiss BC-Nummer / IID. The only API with this data. |
+| `check_compliance(iban)` | $0.02 | Pre-flight risk triage: sanctions (OFAC/EU/UN), FATF, SEPA Instant, VoP, risk score 0-100, recommended_action ∈ {allow, review, block} |
+| `usage()` | free | Current month quota usage for your key |
+| `health()` | free | API version, BIC count, uptime |
+
+## Free format check (no key needed)
+
+Save money by pre-filtering bad IBANs before paying for enrichment:
+
+```python
+from ibanforge import IBANforge
+
+with IBANforge() as client:  # no api_key required
+    out = client.format_iban("CH9300762011623852957")
+    if not out["valid"]:
+        print("Skip:", out["error"])      # e.g. "checksum_failed"
+    else:
+        print(out["bban"]["bank_code"])   # "00762"
+```
+
+## Compliance triage (the killer feature)
+
+```python
+out = client.check_compliance("RU1234567890123456789012345678")  # made-up RU
+print(out["risk_score"])             # high (Russia + FATF flag)
+print(out["recommended_action"])     # "block" | "review" | "allow"
+print(out["sanctions"]["lists"])     # ["OFAC", "EU"] etc.
+print(out["fatf"]["list"])           # "grey" | "black" | "none"
+print(out["sepa"]["reachable"])
+```
+
+## Error handling
+
+The SDK raises typed exceptions — catch the specific class you care about, or the base `IBANforgeError`:
+
+```python
+from ibanforge import (
+    IBANforge,
+    AuthError, PaymentRequiredError, QuotaExhaustedError,
+    RateLimitError, InvalidInputError, APIError, IBANforgeError,
+)
+
+with IBANforge(api_key="ifk_...") as client:
+    try:
+        out = client.validate_iban("not-an-iban")
+    except InvalidInputError as e:
+        print(e.body["error"])  # "invalid_format"
+    except AuthError:
+        print("Bad or revoked API key")
+    except PaymentRequiredError as e:
+        # Your quota is exhausted — switch to x402 to keep going
+        print(e.body["accepts"])  # x402 payment requirements
+    except RateLimitError:
+        print("Slow down")
+    except APIError as e:
+        print(f"Server error {e.status} — retry with backoff")
+    except IBANforgeError as e:
+        print(f"Other: {e}")
+```
+
+## 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](https://ibanforge.com/agents). For Python-first agents, the SDK above is usually enough.
+
+## Configuration
+
+```python
+client = IBANforge(
+    api_key="ifk_...",
+    base_url="https://api.ibanforge.com",  # default
+    timeout=30.0,                          # seconds, default
+    user_agent="my-app/1.2",               # custom UA
+)
+```
+
+## Links
+
+- API documentation: <https://ibanforge.com/docs>
+- Interactive OpenAPI: <https://ibanforge.com/openapi>
+- Agent guide: <https://ibanforge.com/agents>
+- TypeScript SDK: [`@ibanforge/sdk`](https://www.npmjs.com/package/@ibanforge/sdk)
+- MCP server: [`ibanforge-mcp`](https://www.npmjs.com/package/ibanforge-mcp)
+- Source: <https://github.com/cammac-creator/ibanforge>
+
+## License
+
+MIT.

ibanforge-1.1.0/ibanforge/__init__.py

@@ -0,0 +1,46 @@
+"""IBANforge Python SDK.
+
+Official client for the IBANforge REST API — IBAN validation, BIC/SWIFT
+lookup, Swiss BC-Nummer, compliance triage. Made for AI finance agents and
+fintech developers.
+
+Quick start:
+
+    pip install ibanforge
+
+    from ibanforge import IBANforge
+    client = IBANforge(api_key="ifk_...")
+    out = client.validate_iban("CH9300762011623852957")
+    print(out["valid"], out.get("bic", {}).get("bankName"))
+
+For asyncio (FastAPI, langchain async, fan-out concurrency):
+
+    from ibanforge import AsyncIBANforge
+    async with AsyncIBANforge(api_key="ifk_...") as client:
+        out = await client.validate_iban("...")
+"""
+
+from .async_client import AsyncIBANforge
+from .client import IBANforge
+from .exceptions import (
+    APIError,
+    AuthError,
+    IBANforgeError,
+    InvalidInputError,
+    PaymentRequiredError,
+    QuotaExhaustedError,
+    RateLimitError,
+)
+
+__all__ = [
+    "IBANforge",
+    "AsyncIBANforge",
+    "IBANforgeError",
+    "AuthError",
+    "PaymentRequiredError",
+    "QuotaExhaustedError",
+    "RateLimitError",
+    "InvalidInputError",
+    "APIError",
+]
+__version__ = "1.1.0"

ibanforge-1.1.0/ibanforge/async_client.py

@@ -0,0 +1,174 @@
+"""Asynchronous IBANforge API client (asyncio-friendly).
+
+Mirrors the sync `IBANforge` API one-for-one but returns awaitables and uses
+`httpx.AsyncClient` under the hood — pick this when you're calling the API
+from inside an async framework (FastAPI, aiohttp, langchain async tools, etc.)
+or when you need to fan-out 100s of validations concurrently.
+
+Usage:
+
+    import asyncio
+    from ibanforge import AsyncIBANforge
+
+    async def main():
+        async with AsyncIBANforge(api_key="ifk_...") as ibanforge:
+            out = await ibanforge.validate_iban("CH9300762011623852957")
+            print(out["valid"])
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional, Union
+
+import httpx
+
+from .exceptions import (
+    APIError,
+    AuthError,
+    IBANforgeError,
+    InvalidInputError,
+    PaymentRequiredError,
+    QuotaExhaustedError,
+    RateLimitError,
+)
+from .types import (
+    APIKey,
+    APIKeyUsage,
+    BICLookupResult,
+    CHClearingResult,
+    ComplianceResult,
+    HealthInfo,
+    IBANBatchResult,
+    IBANFormatResult,
+    IBANValidationResult,
+)
+
+DEFAULT_BASE_URL = "https://api.ibanforge.com"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "ibanforge-python/1.1.0"
+
+
+def _raise_for_status(res: httpx.Response) -> None:
+    if res.is_success:
+        return
+    body: Any
+    try:
+        body = res.json()
+    except Exception:
+        body = res.text
+    msg_obj = body if isinstance(body, dict) else {}
+    msg = (
+        msg_obj.get("message")
+        or msg_obj.get("error_detail")
+        or msg_obj.get("error")
+        or res.reason_phrase
+        or "Unknown error"
+    )
+    if res.status_code == 401:
+        raise AuthError(msg, status=401, body=body)
+    if res.status_code == 402:
+        raise PaymentRequiredError(msg, status=402, body=body)
+    if res.status_code == 403:
+        raise AuthError(msg, status=403, body=body)
+    if res.status_code == 429:
+        if msg_obj.get("error") == "quota_exceeded":
+            raise QuotaExhaustedError(msg, status=429, body=body)
+        raise RateLimitError(msg, status=429, body=body)
+    if 400 <= res.status_code < 500:
+        raise InvalidInputError(msg, status=res.status_code, body=body)
+    if res.status_code >= 500:
+        raise APIError(msg, status=res.status_code, body=body)
+    raise IBANforgeError(msg, status=res.status_code, body=body)
+
+
+class AsyncIBANforge:
+    """Async client for the IBANforge REST API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        user_agent: str = USER_AGENT,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        headers = {"User-Agent": user_agent}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url, timeout=timeout, headers=headers
+        )
+
+    async def __aenter__(self) -> "AsyncIBANforge":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def format_iban(self, iban: str) -> IBANFormatResult:
+        res = await self._client.get("/v1/iban/format", params={"iban": iban})
+        _raise_for_status(res)
+        return res.json()
+
+    async def validate_iban(self, iban: str) -> IBANValidationResult:
+        res = await self._client.post("/v1/iban/validate", json={"iban": iban})
+        _raise_for_status(res)
+        return res.json()
+
+    async def validate_batch(self, ibans: Iterable[str]) -> IBANBatchResult:
+        ibans_list = list(ibans)
+        if not ibans_list:
+            raise InvalidInputError("ibans must contain at least one IBAN")
+        if len(ibans_list) > 100:
+            raise InvalidInputError(
+                "ibans must be at most 100 entries (got {})".format(len(ibans_list))
+            )
+        res = await self._client.post("/v1/iban/batch", json={"ibans": ibans_list})
+        _raise_for_status(res)
+        return res.json()
+
+    async def check_compliance(self, iban: str) -> ComplianceResult:
+        res = await self._client.post("/v1/iban/compliance", json={"iban": iban})
+        _raise_for_status(res)
+        return res.json()
+
+    async def lookup_bic(self, code: str) -> BICLookupResult:
+        res = await self._client.get(f"/v1/bic/{code}")
+        _raise_for_status(res)
+        return res.json()
+
+    async def lookup_ch_clearing(self, iid: Union[str, int]) -> CHClearingResult:
+        res = await self._client.get(f"/v1/ch/clearing/{iid}")
+        _raise_for_status(res)
+        return res.json()
+
+    @staticmethod
+    async def generate_api_key(
+        email: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> APIKey:
+        async with httpx.AsyncClient(base_url=base_url.rstrip("/"), timeout=timeout) as cl:
+            res = await cl.post("/v1/keys/generate", json={"email": email})
+            _raise_for_status(res)
+            return res.json()
+
+    async def usage(self) -> APIKeyUsage:
+        if not self.api_key:
+            raise AuthError("usage() requires an API key — pass api_key='ifk_...' to the constructor")
+        res = await self._client.get("/v1/keys/usage")
+        _raise_for_status(res)
+        return res.json()
+
+    async def health(self) -> HealthInfo:
+        res = await self._client.get("/health")
+        _raise_for_status(res)
+        return res.json()

ibanforge-1.1.0/ibanforge/client.py

@@ -0,0 +1,228 @@
+"""Synchronous IBANforge API client.
+
+Usage:
+
+    from ibanforge import IBANforge
+
+    # Free format check (no key needed)
+    client = IBANforge()
+    out = client.format_iban("CH9300762011623852957")
+
+    # Authenticated calls (required for paid endpoints unless you go x402)
+    client = IBANforge(api_key="ifk_...")
+    out = client.validate_iban("CH9300762011623852957")
+
+    # Generate a free key in 1 line
+    key = IBANforge.generate_api_key("you@example.com")
+    client = IBANforge(api_key=key["api_key"])
+
+The client raises typed exceptions from `ibanforge.exceptions` — catch the
+specific class you care about (PaymentRequiredError, QuotaExhaustedError,
+InvalidInputError, AuthError, RateLimitError, APIError) or the base
+IBANforgeError to catch them all.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional, Union
+
+import httpx
+
+from .exceptions import (
+    APIError,
+    AuthError,
+    IBANforgeError,
+    InvalidInputError,
+    PaymentRequiredError,
+    QuotaExhaustedError,
+    RateLimitError,
+)
+from .types import (
+    APIKey,
+    APIKeyUsage,
+    BICLookupResult,
+    CHClearingResult,
+    ComplianceResult,
+    HealthInfo,
+    IBANBatchResult,
+    IBANFormatResult,
+    IBANValidationResult,
+)
+
+DEFAULT_BASE_URL = "https://api.ibanforge.com"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "ibanforge-python/1.1.0"
+
+
+def _raise_for_status(res: httpx.Response) -> None:
+    """Map HTTP status codes to typed exceptions."""
+    if res.is_success:
+        return
+
+    body: Any
+    try:
+        body = res.json()
+    except Exception:
+        body = res.text
+
+    msg_obj = body if isinstance(body, dict) else {}
+    msg = (
+        msg_obj.get("message")
+        or msg_obj.get("error_detail")
+        or msg_obj.get("error")
+        or res.reason_phrase
+        or "Unknown error"
+    )
+
+    if res.status_code == 401:
+        raise AuthError(msg, status=401, body=body)
+    if res.status_code == 402:
+        raise PaymentRequiredError(msg, status=402, body=body)
+    if res.status_code == 403:
+        raise AuthError(msg, status=403, body=body)
+    if res.status_code == 429:
+        # IBANforge usually falls through to 402 instead of 429 when an api-key's
+        # quota is exhausted, but we still distinguish here.
+        if msg_obj.get("error") == "quota_exceeded":
+            raise QuotaExhaustedError(msg, status=429, body=body)
+        raise RateLimitError(msg, status=429, body=body)
+    if 400 <= res.status_code < 500:
+        raise InvalidInputError(msg, status=res.status_code, body=body)
+    if res.status_code >= 500:
+        raise APIError(msg, status=res.status_code, body=body)
+    raise IBANforgeError(msg, status=res.status_code, body=body)
+
+
+class IBANforge:
+    """Synchronous client for the IBANforge REST API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        user_agent: str = USER_AGENT,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        headers = {"User-Agent": user_agent}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._client = httpx.Client(base_url=self.base_url, timeout=timeout, headers=headers)
+
+    # ---- context manager ----
+
+    def __enter__(self) -> "IBANforge":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ---- IBAN ----
+
+    def format_iban(self, iban: str) -> IBANFormatResult:
+        """FREE pre-flight check (mod-97 + structure). No API key required.
+
+        Use this to filter malformed IBANs before paying for full enrichment.
+        Returns valid/invalid + error code + bban breakdown only — no BIC,
+        no SEPA, no compliance data.
+        """
+        res = self._client.get("/v1/iban/format", params={"iban": iban})
+        _raise_for_status(res)
+        return res.json()
+
+    def validate_iban(self, iban: str) -> IBANValidationResult:
+        """Validate one IBAN with full enrichment ($0.005 / call with API key).
+
+        Returns BIC, country, EMI/vIBAN classification, SEPA + VoP flags,
+        risk score, Swiss BC-Nummer for CH/LI accounts.
+        """
+        res = self._client.post("/v1/iban/validate", json={"iban": iban})
+        _raise_for_status(res)
+        return res.json()
+
+    def validate_batch(self, ibans: Iterable[str]) -> IBANBatchResult:
+        """Validate up to 100 IBANs in one call ($0.002 / IBAN with API key)."""
+        ibans_list = list(ibans)
+        if not ibans_list:
+            raise InvalidInputError("ibans must contain at least one IBAN")
+        if len(ibans_list) > 100:
+            raise InvalidInputError(
+                "ibans must be at most 100 entries (got {})".format(len(ibans_list))
+            )
+        res = self._client.post("/v1/iban/batch", json={"ibans": ibans_list})
+        _raise_for_status(res)
+        return res.json()
+
+    def check_compliance(self, iban: str) -> ComplianceResult:
+        """Pre-flight compliance triage on an IBAN ($0.02 / call with API key).
+
+        Returns sanctions screening (OFAC/EU/UN), FATF jurisdiction flag,
+        SEPA Instant reachability, VoP participant status, risk score 0-100,
+        and a recommended_action of "allow" | "review" | "block".
+
+        Informational, not a regulated AML/CFT product.
+        """
+        res = self._client.post("/v1/iban/compliance", json={"iban": iban})
+        _raise_for_status(res)
+        return res.json()
+
+    # ---- BIC / SWIFT ----
+
+    def lookup_bic(self, code: str) -> BICLookupResult:
+        """Resolve a BIC/SWIFT code into bank, country, city, LEI ($0.003 / call)."""
+        res = self._client.get(f"/v1/bic/{code}")
+        _raise_for_status(res)
+        return res.json()
+
+    # ---- Swiss clearing ----
+
+    def lookup_ch_clearing(self, iid: Union[str, int]) -> CHClearingResult:
+        """Resolve a Swiss BC-Nummer / IID into institution data ($0.003 / call).
+
+        Backed by 1,190 SIX BankMaster entries — the only public API exposing
+        this data.
+        """
+        res = self._client.get(f"/v1/ch/clearing/{iid}")
+        _raise_for_status(res)
+        return res.json()
+
+    # ---- API keys ----
+
+    @staticmethod
+    def generate_api_key(
+        email: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> APIKey:
+        """Create a free API key (200 requests/month).
+
+        The key is shown ONCE — store it securely. After the monthly quota the
+        IBANforge API falls back to advertising x402 payment requirements; the
+        same key continues to work next month.
+        """
+        with httpx.Client(base_url=base_url.rstrip("/"), timeout=timeout) as cl:
+            res = cl.post("/v1/keys/generate", json={"email": email})
+            _raise_for_status(res)
+            return res.json()
+
+    def usage(self) -> APIKeyUsage:
+        """Get the current month's quota usage for the configured API key."""
+        if not self.api_key:
+            raise AuthError("usage() requires an API key — pass api_key='ifk_...' to the constructor")
+        res = self._client.get("/v1/keys/usage")
+        _raise_for_status(res)
+        return res.json()
+
+    # ---- Misc ----
+
+    def health(self) -> HealthInfo:
+        """Public health endpoint — version, BIC count, uptime, basic stats."""
+        res = self._client.get("/health")
+        _raise_for_status(res)
+        return res.json()

ibanforge-1.1.0/ibanforge/exceptions.py

@@ -0,0 +1,51 @@
+"""Custom exception classes for the IBANforge SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class IBANforgeError(Exception):
+    """Base class for all IBANforge SDK errors."""
+
+    def __init__(self, message: str, *, status: int | None = None, body: Any | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class AuthError(IBANforgeError):
+    """API key is missing, invalid, or revoked."""
+
+
+class PaymentRequiredError(IBANforgeError):
+    """402 returned by the API. The agent must either authenticate with an API key
+    (Authorization: Bearer ifk_...) or pay per call via the x402 protocol on Base.
+
+    The 402 body is in `self.body` and includes `accepts` (payment requirements),
+    `free_tier` (instructions to obtain a free key), and `x402` (protocol pointers).
+    """
+
+
+class QuotaExhaustedError(IBANforgeError):
+    """The API key's monthly quota is exhausted.
+
+    Note: by default the IBANforge API will fall back to advertising x402 payment
+    requirements (HTTP 402) instead of returning 429 — agents that scale beyond
+    their quota can keep calling and pay per request. This exception is only
+    raised if the server explicitly returns 429.
+    """
+
+
+class RateLimitError(IBANforgeError):
+    """Global rate limit exceeded (per-IP)."""
+
+
+class InvalidInputError(IBANforgeError):
+    """4xx returned for an obviously malformed request — bad IBAN length, bad BIC
+    format, missing query param, etc. Carries the server's `error_detail` if any.
+    """
+
+
+class APIError(IBANforgeError):
+    """5xx — server-side failure. Retry with backoff."""

ibanforge-1.1.0/ibanforge/types.py

@@ -0,0 +1,149 @@
+"""Typed dicts mirroring the IBANforge REST API response shapes.
+
+These are duck-typed (TypedDict, not dataclass) so they accept the raw JSON
+returned by the API without an extra parsing step. If you want strict
+validation, wrap them in pydantic models on your end.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, TypedDict
+
+
+class Country(TypedDict, total=False):
+    code: str
+    name: str
+
+
+class BBAN(TypedDict, total=False):
+    bank_code: str
+    branch_code: str
+    account_number: str
+
+
+class BIC(TypedDict, total=False):
+    bic: str
+    bankName: str
+    city: str
+    lei: str
+
+
+class Issuer(TypedDict, total=False):
+    type: str  # "bank" | "emi" | "viban" | "neobank" | "unknown"
+    name: str
+
+
+class SEPA(TypedDict, total=False):
+    reachable: bool
+    instant: bool
+
+
+class VoP(TypedDict, total=False):
+    participant: bool
+
+
+class CHClearing(TypedDict, total=False):
+    bc_nummer: str
+    sic: bool
+    qr_iid: bool
+
+
+class IBANValidationResult(TypedDict, total=False):
+    iban: str
+    formatted: str
+    valid: bool
+    country: Country
+    check_digits: str
+    bban: BBAN
+    bic: BIC
+    issuer: Issuer
+    sepa: SEPA
+    vop: VoP
+    ch_clearing: CHClearing
+    risk_score: float
+    cost_usdc: float
+    processing_ms: int
+    error: str
+    error_detail: str
+
+
+class IBANFormatResult(TypedDict, total=False):
+    """Free /v1/iban/format response — pure mod-97 + structure check, no DB lookups."""
+
+    iban: str
+    formatted: str
+    valid: bool
+    country: Country
+    check_digits: str
+    bban: BBAN
+    error: str
+    error_detail: str
+    upgrade_to_full_validation: str
+
+
+class IBANBatchResult(TypedDict, total=False):
+    results: List[IBANValidationResult]
+    summary: Any
+    cost_usdc: float
+
+
+class BICLookupResult(TypedDict, total=False):
+    bic: str
+    bic8: str
+    bic11: str
+    found: bool
+    valid_format: bool
+    institution: str
+    country: Country
+    city: str
+    lei: str
+    address: str
+    cost_usdc: float
+
+
+class CHClearingResult(TypedDict, total=False):
+    iid: str
+    found: bool
+    institution: Any
+    participation: Any
+    bic: str
+    cost_usdc: float
+
+
+class ComplianceResult(TypedDict, total=False):
+    iban: str
+    valid: bool
+    risk_score: float
+    recommended_action: str  # "allow" | "review" | "block"
+    sanctions: Any
+    fatf: Any
+    sepa: SEPA
+    vop: VoP
+    flags: Any
+    cost_usdc: float
+
+
+class APIKey(TypedDict, total=False):
+    api_key: str
+    key_prefix: str
+    email: str
+    monthly_limit: int
+    message: str
+
+
+class APIKeyUsage(TypedDict, total=False):
+    key_prefix: str
+    email: str
+    monthly_limit: int
+    used_this_month: int
+    remaining: int
+    month: str
+
+
+class HealthInfo(TypedDict, total=False):
+    status: str
+    version: str
+    uptime_seconds: float
+    bic_database_entries: int
+    ch_clearing_entries: int
+    stats: Any

ibanforge-1.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ibanforge"
+version = "1.1.0"
+description = "Official Python SDK for the IBANforge API — IBAN validation, BIC/SWIFT lookup, Swiss BC-Nummer, sanctions/SEPA/VoP compliance triage."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "IBANforge", email = "support@ibanforge.com" }]
+dependencies = ["httpx>=0.24.0"]
+keywords = [
+    "iban",
+    "bic",
+    "swift",
+    "validation",
+    "banking",
+    "api",
+    "sepa",
+    "vop",
+    "fintech",
+    "ai-agent",
+    "x402",
+    "compliance",
+    "sanctions",
+    "swiss",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-asyncio>=0.21", "respx>=0.20"]
+
+[project.urls]
+Homepage = "https://ibanforge.com"
+Documentation = "https://ibanforge.com/docs"
+"Agent Guide" = "https://ibanforge.com/agents"
+"OpenAPI Reference" = "https://ibanforge.com/openapi"
+Repository = "https://github.com/cammac-creator/ibanforge"
+"Issue Tracker" = "https://github.com/cammac-creator/ibanforge/issues"
+Changelog = "https://github.com/cammac-creator/ibanforge/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ibanforge"]

ibanforge-1.1.0/tests/test_client.py

@@ -0,0 +1,190 @@
+"""Unit tests for the sync IBANforge client.
+
+Uses respx to mock httpx — no real network calls.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+import respx
+
+from ibanforge import (
+    APIError,
+    AsyncIBANforge,
+    AuthError,
+    IBANforge,
+    InvalidInputError,
+    PaymentRequiredError,
+    QuotaExhaustedError,
+    RateLimitError,
+)
+
+BASE = "https://api.ibanforge.com"
+SAMPLE_IBAN = "CH9300762011623852957"
+
+
+@pytest.fixture
+def client() -> IBANforge:
+    return IBANforge(api_key="ifk_test_key")
+
+
+@respx.mock
+def test_format_iban_no_key_required():
+    cl = IBANforge()  # no api_key
+    respx.get(f"{BASE}/v1/iban/format").mock(
+        return_value=httpx.Response(200, json={"iban": SAMPLE_IBAN, "valid": True})
+    )
+    out = cl.format_iban(SAMPLE_IBAN)
+    assert out["valid"] is True
+    cl.close()
+
+
+@respx.mock
+def test_validate_iban_authorization_header(client: IBANforge):
+    route = respx.post(f"{BASE}/v1/iban/validate").mock(
+        return_value=httpx.Response(200, json={"iban": SAMPLE_IBAN, "valid": True})
+    )
+    out = client.validate_iban(SAMPLE_IBAN)
+    assert out["valid"] is True
+    sent = route.calls.last.request
+    assert sent.headers.get("authorization") == "Bearer ifk_test_key"
+
+
+@respx.mock
+def test_validate_batch_too_many_raises_local(client: IBANforge):
+    too_many = [SAMPLE_IBAN] * 101
+    with pytest.raises(InvalidInputError):
+        client.validate_batch(too_many)
+
+
+@respx.mock
+def test_lookup_bic(client: IBANforge):
+    respx.get(f"{BASE}/v1/bic/UBSWCHZH80A").mock(
+        return_value=httpx.Response(200, json={"bic": "UBSWCHZH80A", "found": True})
+    )
+    out = client.lookup_bic("UBSWCHZH80A")
+    assert out["found"] is True
+
+
+@respx.mock
+def test_lookup_ch_clearing(client: IBANforge):
+    respx.get(f"{BASE}/v1/ch/clearing/762").mock(
+        return_value=httpx.Response(200, json={"iid": "00762", "found": True})
+    )
+    out = client.lookup_ch_clearing(762)
+    assert out["found"] is True
+
+
+@respx.mock
+def test_compliance(client: IBANforge):
+    respx.post(f"{BASE}/v1/iban/compliance").mock(
+        return_value=httpx.Response(
+            200, json={"iban": SAMPLE_IBAN, "valid": True, "risk_score": 5, "recommended_action": "allow"}
+        )
+    )
+    out = client.check_compliance(SAMPLE_IBAN)
+    assert out["recommended_action"] == "allow"
+
+
+@respx.mock
+def test_402_raises_payment_required(client: IBANforge):
+    respx.post(f"{BASE}/v1/iban/validate").mock(
+        return_value=httpx.Response(
+            402,
+            json={
+                "x402Version": 1,
+                "error": "payment_required",
+                "message": "Pay or use a key",
+                "accepts": [{"scheme": "exact", "network": "base"}],
+            },
+        )
+    )
+    with pytest.raises(PaymentRequiredError) as exc:
+        client.validate_iban(SAMPLE_IBAN)
+    assert exc.value.status == 402
+    assert exc.value.body["accepts"][0]["network"] == "base"
+
+
+@respx.mock
+def test_401_raises_auth_error(client: IBANforge):
+    respx.post(f"{BASE}/v1/iban/validate").mock(
+        return_value=httpx.Response(401, json={"error": "invalid_api_key"})
+    )
+    with pytest.raises(AuthError):
+        client.validate_iban(SAMPLE_IBAN)
+
+
+@respx.mock
+def test_429_quota_exceeded_distinct_from_rate_limit(client: IBANforge):
+    respx.post(f"{BASE}/v1/iban/validate").mock(
+        return_value=httpx.Response(429, json={"error": "quota_exceeded", "limit": 200, "used": 200})
+    )
+    with pytest.raises(QuotaExhaustedError):
+        client.validate_iban(SAMPLE_IBAN)
+
+
+@respx.mock
+def test_429_generic_rate_limit(client: IBANforge):
+    respx.post(f"{BASE}/v1/iban/validate").mock(
+        return_value=httpx.Response(429, json={"error": "rate_limited"})
+    )
+    with pytest.raises(RateLimitError):
+        client.validate_iban(SAMPLE_IBAN)
+
+
+@respx.mock
+def test_400_raises_invalid_input(client: IBANforge):
+    respx.post(f"{BASE}/v1/iban/validate").mock(
+        return_value=httpx.Response(400, json={"error": "invalid_iban", "error_detail": "too short"})
+    )
+    with pytest.raises(InvalidInputError) as exc:
+        client.validate_iban("CH")
+    assert "too short" in str(exc.value)
+
+
+@respx.mock
+def test_500_raises_api_error(client: IBANforge):
+    respx.post(f"{BASE}/v1/iban/validate").mock(return_value=httpx.Response(500, text="boom"))
+    with pytest.raises(APIError):
+        client.validate_iban(SAMPLE_IBAN)
+
+
+@respx.mock
+def test_generate_api_key_static_method():
+    respx.post(f"{BASE}/v1/keys/generate").mock(
+        return_value=httpx.Response(
+            200, json={"api_key": "ifk_xxx", "monthly_limit": 200, "email": "a@b.c"}
+        )
+    )
+    out = IBANforge.generate_api_key("a@b.c")
+    assert out["api_key"].startswith("ifk_")
+
+
+def test_usage_without_key_raises():
+    cl = IBANforge()  # no api_key
+    with pytest.raises(AuthError):
+        cl.usage()
+    cl.close()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_validate_iban():
+    respx.post(f"{BASE}/v1/iban/validate").mock(
+        return_value=httpx.Response(200, json={"iban": SAMPLE_IBAN, "valid": True})
+    )
+    async with AsyncIBANforge(api_key="ifk_test_key") as cl:
+        out = await cl.validate_iban(SAMPLE_IBAN)
+    assert out["valid"] is True
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_402():
+    respx.post(f"{BASE}/v1/iban/validate").mock(
+        return_value=httpx.Response(402, json={"error": "payment_required", "accepts": []})
+    )
+    async with AsyncIBANforge() as cl:
+        with pytest.raises(PaymentRequiredError):
+            await cl.validate_iban(SAMPLE_IBAN)