bitgen-sdk 1.0.0__py3-none-any.whl

bitgen/__init__.py

@@ -0,0 +1,18 @@
+"""Official Python SDK for the BITGEN API v4.
+
+```python
+from bitgen import BitgenClient, Env
+
+client = BitgenClient(scope="YOUR_SCOPE_UUID", apiKey="YOUR_API_KEY", env=Env.SANDBOX)
+```
+"""
+
+from bitgen.client import BitgenClient
+from bitgen.constants import Asset, Env
+from bitgen.errors import BitgenError, UnexpectedAnswerError
+from bitgen.page import Page
+from bitgen.version import VERSION
+
+__version__ = VERSION
+
+__all__ = ["VERSION", "Asset", "BitgenClient", "BitgenError", "Env", "Page", "UnexpectedAnswerError"]

bitgen/_http/__init__.py

@@ -0,0 +1 @@
+"""The HTTP layer of the SDK — internal."""

bitgen/_http/base_url.py

@@ -0,0 +1,42 @@
+"""The base URL of the API for a configuration: `scheme://host[:port]`, no trailing slash, no version prefix."""
+
+from __future__ import annotations
+
+import re
+
+from bitgen._support import values
+from bitgen.constants import Env
+
+LOCALHOST_PORT = 3002
+
+_HOSTS = {
+    Env.PRODUCTION: "https://api.bitgen.com",
+    Env.SANDBOX: "https://api.sandbox.bitgen.com",
+    Env.STAGING: "https://api.staging.btgn.dev",
+}
+# Letters, digits, dots, hyphens (and underscores of internal DNS names): a scheme, a port, a path, userinfo or a
+# bracketed IPv6 are refused
+_BARE_HOSTNAME = re.compile(r"[A-Za-z0-9._-]+")
+
+
+def resolve(env: object, host: object, port: object, isSsl: object) -> str:
+    """`ValueError` when `env` is unknown, `host` is not a bare hostname or `port` is out of range; `TypeError` on a
+    wrong type. The values of `env` and `host` are never echoed."""
+    environment = values.ensure(env, Env.VALUES, "env")
+    if port is not None:
+        if isinstance(port, bool) or not isinstance(port, int):
+            raise TypeError("port must be an integer between 1 and 65535")
+        if port < 1 or port > 65535:
+            raise ValueError("port must be an integer between 1 and 65535")
+    if not isinstance(isSsl, bool):
+        raise TypeError("isSsl must be a boolean")
+    # Custom host (a container, a tunnel): bare hostname, scheme and port come from isSsl / port
+    if host is not None:
+        if not isinstance(host, str):
+            raise TypeError("host must be a string: a bare hostname (no scheme, port or path)")
+        if not _BARE_HOSTNAME.fullmatch(host):
+            raise ValueError("host must be a bare hostname (no scheme, port or path): use port and isSsl")
+        return f"{'https' if isSsl else 'http'}://{host}:{port if port is not None else 80}"
+    if environment == Env.LOCALHOST:
+        return f"http://localhost:{port if port is not None else LOCALHOST_PORT}"
+    return _HOSTS[environment]

bitgen/_http/client.py

@@ -0,0 +1,131 @@
+"""The HTTP layer of the SDK: URL and query building, headers, JSON bodies, and the mapping of every answer to a decoded
+value or a `BitgenError`. The wire itself is the Transport."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import quote
+
+from bitgen._http.transport import Response, Transport, TransportError
+from bitgen.errors import BitgenError
+
+_REDACTABLE_KEY = 8
+"""Shortest key that is redacted from an error — a real key is far longer, a shorter one is a placeholder"""
+
+Query = Mapping[str, str | int | float | bool | None]
+"""Query string entries — `None` entries are skipped, booleans travel as `true` / `false`"""
+
+
+class HttpClient:
+    """`scope` is the organization uuid of the key — resources use it where the API expects the organization."""
+
+    def __init__(
+        self, transport: Transport, scope: str, apiKey: str, baseUrl: str, timeout: float, userAgent: str
+    ) -> None:
+        self._transport = transport
+        self.scope = scope
+        self._apiKey = apiKey
+        self._baseUrl = baseUrl
+        self._timeout = timeout
+        self._headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": userAgent,
+            "BITGEN-Scope": scope,
+            "Api-key": apiKey,
+        }
+
+    def get(self, path: str, query: Query | None = None) -> Any:
+        return self.request("GET", path, query)
+
+    def post(self, path: str, body: object = None) -> Any:
+        return self.request("POST", path, None, body)
+
+    def put(self, path: str, body: object = None) -> Any:
+        return self.request("PUT", path, None, body)
+
+    def patch(self, path: str, body: object = None) -> Any:
+        return self.request("PATCH", path, None, body)
+
+    def delete(self, path: str, body: object = None) -> Any:
+        return self.request("DELETE", path, None, body)
+
+    def request(self, method: str, path: str, query: Query | None = None, body: object = None) -> Any:
+        """Sends the request and returns the decoded JSON answer — `None` on `204` or an empty body.
+        Anything outside 2xx, a 2xx that is not JSON, or no HTTP answer at all → `BitgenError`."""
+        url = self._baseUrl + path + _query_string(query)
+        encoded = None if body is None else _encode(body)
+        try:
+            response = self._transport.send(method, url, self._headers, encoded, self._timeout)
+        except TransportError as error:
+            raise BitgenError(0, error.code) from error
+
+        status = response.status
+        text = "" if status == 204 else response.body.decode("utf-8", errors="replace")
+        # v4 sends the real HTTP status: anything outside 2xx is an error, a redirect included
+        if status < 200 or status > 299:
+            code = _error_code(text)
+            raise BitgenError(status, self._redact(code if code is not None else _raw_body(text, response)))
+        if text.strip() == "":
+            return None
+        try:
+            return _decode(text)
+        except ValueError as error:
+            # A 2xx that is not JSON is not an answer of the API (proxy page…): report it as an error
+            raise BitgenError(status, self._redact(_raw_body(text, response))) from error
+
+    def _redact(self, code: str) -> str:
+        """A raw body that echoes the request (a debugging proxy page…) must not put the key in the error. A key shorter
+        than a credential can be (a placeholder of a test) is left alone: replacing its every occurrence would garble
+        the codes of the API (`unknown_asset` with the key `k`)."""
+        return code.replace(self._apiKey, "[redacted]") if len(self._apiKey) >= _REDACTABLE_KEY else code
+
+
+def _query_string(query: Query | None) -> str:
+    if not query:
+        return ""
+    pairs: list[str] = []
+    for key, value in query.items():
+        if value is None:
+            continue
+        text = ("true" if value else "false") if isinstance(value, bool) else str(value)
+        pairs.append(f"{quote(key, safe='')}={quote(text, safe='')}")
+    return "?" + "&".join(pairs) if pairs else ""
+
+
+def _encode(body: object) -> bytes:
+    """Compact JSON, unicode and slashes kept as they are; `NaN` / `Infinity` are not JSON and are refused"""
+    return json.dumps(body, ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode("utf-8")
+
+
+def _decode(text: str) -> Any:
+    """Strict JSON: `NaN` / `Infinity`, which Python would accept, are not JSON"""
+    return json.loads(text, parse_constant=_not_json)
+
+
+def _not_json(constant: str) -> Any:
+    raise ValueError(f"{constant} is not JSON")
+
+
+def _error_code(text: str) -> str | None:
+    """The stable `message` of an API error body `{ error, message, code }`, or `None` when the body is not one"""
+    try:
+        decoded = _decode(text)
+    except ValueError:
+        return None
+    if not isinstance(decoded, dict):
+        return None
+    message = decoded.get("message")
+    if not isinstance(message, str) or message == "":
+        return None
+    return message
+
+
+def _raw_body(text: str, response: Response) -> str:
+    """Raw body, or the reason phrase, or the status as text — never empty"""
+    trimmed = text.strip()
+    if trimmed != "":
+        return trimmed
+    return response.reason if response.reason != "" else str(response.status)

bitgen/_http/timeout.py

@@ -0,0 +1,21 @@
+"""The request timeout: seconds in the configuration, validated once."""
+
+from __future__ import annotations
+
+import math
+
+DEFAULT = 30
+"""Default, in seconds"""
+MAX = 2_147_483
+"""Largest value, in seconds — the same bound as the other BITGEN SDKs (a 32-bit number of milliseconds)"""
+
+_MESSAGE = f"timeout must be a number of seconds between 0 (no timeout) and {MAX}"
+
+
+def resolve(seconds: object) -> float:
+    """`0` = no timeout. `ValueError` when not a finite number between 0 and 2147483, `TypeError` when not a number."""
+    if isinstance(seconds, bool) or not isinstance(seconds, int | float):
+        raise TypeError(_MESSAGE)
+    if not math.isfinite(seconds) or seconds < 0 or seconds > MAX:
+        raise ValueError(_MESSAGE)
+    return float(seconds)

bitgen/_http/transport.py

@@ -0,0 +1,113 @@
+"""The wire: one HTTP request, one raw response. TLS verified, redirects never followed, one deadline for the whole
+request."""
+
+from __future__ import annotations
+
+import contextlib
+import http.client
+import socket
+import ssl
+import threading
+from dataclasses import dataclass
+from typing import Any, Protocol
+from urllib.parse import urlsplit
+
+
+@dataclass(frozen=True, slots=True)
+class Response:
+    """What a Transport got back: the status, the reason phrase of the status line (may be empty) and the raw body."""
+
+    status: int
+    reason: str
+    body: bytes
+
+
+class TransportError(Exception):
+    """No HTTP response at all. `code` is `request_timeout` or `network_error`; the message is the operating system's
+    words for an OSError (DNS, refused, TLS, timed out), the class name alone for an http.client exception — never
+    anything the server sent, never the API key (which only travels in headers)."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+    def __reduce__(self) -> tuple[type[TransportError], tuple[str, str], dict[str, Any]]:
+        return (type(self), (self.code, str(self)), self.__dict__)
+
+
+class Transport(Protocol):
+    """Sends one HTTP request and returns the raw response. Never follows redirects."""
+
+    def send(self, method: str, url: str, headers: dict[str, str], body: bytes | None, timeout: float) -> Response:
+        """`body` is already serialized — `None` sends no body. `timeout` bounds the whole request, in seconds,
+        `0` = none. Raises `TransportError` when no HTTP response was received (timeout, DNS, connection, TLS…)."""
+        ...
+
+
+class HttpTransport:
+    """The transport of the SDK: `http.client` from the standard library, TLS verified against the certificates of the
+    system, redirects never followed (a 3xx is answered as it is), and one deadline for the whole request — connection,
+    request, headers and body — not one per network operation: a timer shuts the socket down when it passes."""
+
+    def __init__(self) -> None:
+        self._context = ssl.create_default_context()
+
+    def send(self, method: str, url: str, headers: dict[str, str], body: bytes | None, timeout: float) -> Response:
+        parts = urlsplit(url)
+        host = parts.hostname or ""
+        target = parts.path + (f"?{parts.query}" if parts.query else "")
+        connection: http.client.HTTPConnection
+        if parts.scheme == "https":
+            connection = http.client.HTTPSConnection(host, parts.port, timeout=timeout or None, context=self._context)
+        else:
+            connection = http.client.HTTPConnection(host, parts.port, timeout=timeout or None)
+        # A body-less POST / PUT / PATCH / DELETE still announces `Content-Length: 0`, as the other SDKs do
+        payload = body if body is not None or method in ("GET", "HEAD") else b""
+        # The deadline of the whole request: when it passes, the timer shuts the socket down and whatever blocking
+        # read is in progress fails; `expired` tells such a failure from a genuine network error
+        expired = threading.Event()
+        timer = threading.Timer(timeout, _shutdown, (connection, expired)) if timeout > 0 else None
+        failure: TransportError
+        try:
+            if timer is not None:
+                timer.daemon = True
+                timer.start()
+            try:
+                connection.request(method, target, body=payload, headers=headers)
+                response = connection.getresponse()
+                data = response.read()
+                if expired.is_set():
+                    raise TimeoutError("the request deadline has passed")
+                return Response(response.status, response.reason, data)
+            except (OSError, http.client.HTTPException) as error:
+                # a socket timeout is a TimeoutError (an OSError); the timer's shutdown ends in an OSError or an
+                # incomplete answer (an HTTPException)
+                code = "request_timeout" if isinstance(error, TimeoutError) or expired.is_set() else "network_error"
+                failure = _translate(code, error)
+        finally:
+            if timer is not None:
+                timer.cancel()
+            connection.close()
+        # raised outside the `except`: an http.client exception is neither the cause nor the context of the failure
+        raise failure
+
+
+def _translate(code: str, error: Exception) -> TransportError:
+    """The transport error to raise. An OSError (DNS, refused, TLS, timed out) is kept as the cause, with the operating
+    system's words; an http.client exception is dropped and only named — a `BadStatusLine` carries the first line the
+    server sent, and a server that reflects the request would put the key in it"""
+    if isinstance(error, http.client.HTTPException):
+        return TransportError(code, type(error).__name__)
+    failure = TransportError(code, f"{type(error).__name__}: {error}")
+    failure.__cause__ = error
+    return failure
+
+
+def _shutdown(connection: http.client.HTTPConnection, expired: threading.Event) -> None:
+    """The deadline has passed: wake whatever blocking read is in progress on the socket"""
+    expired.set()
+    sock = connection.sock
+    if sock is None:
+        return
+    with contextlib.suppress(OSError):
+        sock.shutdown(socket.SHUT_RDWR)

bitgen/_support/__init__.py

@@ -0,0 +1 @@
+"""Argument validation, shared by the client and the resources — internal."""

bitgen/_support/amount.py

@@ -0,0 +1,42 @@
+"""Amounts always reach the API as strings: a string is sent as is (trimmed), an int, a finite float or a `Decimal` ≥ 0
+in its plain decimal form. Nothing is ever rounded or reformatted — send crypto amounts (up to 18 decimals) as
+strings."""
+
+from __future__ import annotations
+
+import math
+from decimal import Decimal
+
+_MESSAGE = "amount must be a non-empty string or a finite number >= 0"
+
+
+def normalize(value: object) -> str:
+    """`ValueError` on an empty string, a negative or non-finite number, or a float that Python would write in exponent
+    notation (`1e-08`, `1e+21`: pass it as a decimal string); `TypeError` on anything that is not a string, an int, a
+    float or a `Decimal` (a bool included)."""
+    if isinstance(value, str):
+        trimmed = value.strip()
+        if trimmed == "":
+            raise ValueError(_MESSAGE)
+        return trimmed
+    if isinstance(value, bool) or not isinstance(value, int | float | Decimal):
+        raise TypeError(_MESSAGE)
+    if isinstance(value, int):
+        if value < 0:
+            raise ValueError(_MESSAGE)
+        return str(int(value))
+    if isinstance(value, Decimal):
+        if not value.is_finite() or value < 0:
+            raise ValueError(_MESSAGE)
+        # plain notation, never `1E-8`; the sign of a negative zero is dropped
+        return "0" if value == 0 else format(value, "f")
+    if not math.isfinite(value) or value < 0:
+        raise ValueError(_MESSAGE)
+    if value == 0:
+        return "0"
+    # shortest round-trip representation, as `repr` writes it (exponent notation below 1e-4 and from 1e16);
+    # `float(value)` so that a subclass (`numpy.float64`) does not write its own name
+    text = repr(float(value))
+    if "e" in text or "E" in text:
+        raise ValueError(f"amount {text} would be sent in exponent notation: pass it as a decimal string")
+    return text.removesuffix(".0")

bitgen/_support/asset_id.py

@@ -0,0 +1,18 @@
+"""An asset, as accepted by every method expecting one: its uuid or ISO code as a string (`Asset.ETH`, `"eth"`, a uuid —
+any case, the API normalizes it), or an `Asset` / `AssetRef` model — the SDK then sends its uuid."""
+
+from __future__ import annotations
+
+from bitgen.models.asset import Asset, AssetRef
+
+
+def resolve(asset: object) -> str:
+    """`ValueError` on a model without a non-empty `uuid`, `TypeError` on anything that is not a string, an `Asset` or
+    an `AssetRef` — both before any request."""
+    if isinstance(asset, str):
+        return asset
+    if not isinstance(asset, Asset | AssetRef) or not isinstance(asset.uuid, str):
+        raise TypeError("asset must be a uuid or an ISO code string, or an Asset / AssetRef model")
+    if asset.uuid.strip() == "":
+        raise ValueError("asset must be a uuid or an ISO code, or a model with a non-empty uuid")
+    return asset.uuid

bitgen/_support/constants.py

@@ -0,0 +1,19 @@
+"""The metaclass of the constant classes of the SDK (`Env`, `Asset`, `Locale`…): frozen and never instantiated."""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+
+class ConstantsMeta(type):
+    """A class of string constants: `Env.SANDBOX` is `"sandbox"`, `Env.VALUES` lists every value in the order of the
+    API contract. The class is frozen (no value can be replaced or removed) and is not instantiated."""
+
+    def __setattr__(cls, name: str, value: object) -> None:
+        raise AttributeError(f"{cls.__name__} is a constant class: its values cannot be changed")
+
+    def __delattr__(cls, name: str) -> None:
+        raise AttributeError(f"{cls.__name__} is a constant class: its values cannot be removed")
+
+    def __call__(cls, *args: object, **kwargs: object) -> NoReturn:
+        raise TypeError(f"{cls.__name__} is a constant class: it is not instantiated")

bitgen/_support/path.py

@@ -0,0 +1,17 @@
+"""Path segments (`/asset/{asset}`, `/account/{user}`…): validated and encoded before they reach a URL."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+
+def segment(value: object, name: str) -> str:
+    """`ValueError` on an empty value or on `.` / `..` (which the URL would normalize away), `TypeError` on a
+    non-string."""
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string")
+    if value.strip() == "":
+        raise ValueError(f"{name} must be a non-empty string")
+    if value in (".", ".."):
+        raise ValueError(f'{name} must not be "." or ".."')
+    return quote(value, safe="")

bitgen/_support/reference.py

@@ -0,0 +1,19 @@
+"""A reference to an object the SDK returns — an order, a movement, a position, a connector… — given as its uuid or as
+the model itself: the SDK then sends the model's uuid."""
+
+from __future__ import annotations
+
+
+def resolve(value: object, model: type | tuple[type, ...], name: str) -> str:
+    """The uuid to send. A string is sent as is; a model of the expected class is its `uuid`. An empty string, or a
+    model without a non-empty `uuid`, is a `ValueError`; any other object a `TypeError` — both before any request."""
+    if isinstance(value, str):
+        uuid = value
+    elif isinstance(value, model) and isinstance(getattr(value, "uuid", None), str):
+        uuid = getattr(value, "uuid")  # noqa: B009 - the model is checked above, its attribute is not typed here
+    else:
+        names = " / ".join(cls.__name__ for cls in (model if isinstance(model, tuple) else (model,)))
+        raise TypeError(f"{name} must be a uuid string, or a {names} model")
+    if uuid.strip() == "":
+        raise ValueError(f"{name} must be a non-empty uuid, or a model with a non-empty uuid")
+    return uuid

bitgen/_support/user_id.py

@@ -0,0 +1,26 @@
+"""A customer, as accepted by every method expecting one: their uuid (or an email, where the API resolves it), or one of
+the models that carry a customer's uuid — the `Created` of `client.customer.create()`, a `Customer`, an `Account`, the
+`user` of an `Order`, the `owner` of a `Transaction` or of a `StakingMovement`."""
+
+from __future__ import annotations
+
+from bitgen.models.customer import Account, Created, Customer, OrderUser, UserSummary
+
+_MODELS = (Created, Customer, Account, UserSummary, OrderUser)
+
+
+def resolve(user: object) -> str:
+    """The uuid (or email) to send. A string is sent as is; a model is its `uuid`. An empty string, or a model without
+    a non-empty `uuid`, is a `ValueError`; any other object — a `Wallet`, a plain object with a `uuid` — a `TypeError`:
+    both before any request."""
+    if isinstance(user, str):
+        value = user
+    elif isinstance(user, _MODELS) and isinstance(user.uuid, str):
+        value = user.uuid
+    else:
+        raise TypeError(
+            "user must be a uuid or email string, or a Created / Customer / Account / UserSummary / OrderUser model"
+        )
+    if value.strip() == "":
+        raise ValueError("user must be a non-empty uuid or email, or a model with a non-empty uuid")
+    return value

bitgen/_support/values.py

@@ -0,0 +1,55 @@
+"""The single validation of the constant lists of the SDK (`Env.VALUES`, `Locale.VALUES`…)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+
+def ensure(value: object, values: Sequence[str], name: str) -> str:
+    """Returns `value` when it is one of `values`. A value outside the list is a caller's mistake, refused before any
+    request — the value itself is never echoed: `ValueError("locale must be FR or EN")`; not a string → `TypeError`."""
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string, one of {_join(values)}")
+    if value not in values:
+        raise ValueError(f"{name} must be {_join(values)}")
+    return value
+
+
+def _join(values: Sequence[str]) -> str:
+    """`A, B or C`"""
+    if len(values) <= 1:
+        return "".join(values)
+    return ", ".join(values[:-1]) + " or " + values[-1]
+
+
+def string(value: object, name: str) -> str:
+    """A required string argument"""
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string")
+    return value
+
+
+def optional_string(value: object, name: str) -> str | None:
+    """`None` (not sent) or a string"""
+    if value is not None and not isinstance(value, str):
+        raise TypeError(f"{name} must be a string")
+    return value
+
+
+def optional_int(value: object, name: str) -> int | None:
+    """`None` (not sent) or an integer — a boolean is not one"""
+    if value is not None and (isinstance(value, bool) or not isinstance(value, int)):
+        raise TypeError(f"{name} must be an integer")
+    return value
+
+
+def optional_bool(value: object, name: str) -> bool | None:
+    """`None` (not sent) or a boolean"""
+    if value is not None and not isinstance(value, bool):
+        raise TypeError(f"{name} must be a boolean")
+    return value
+
+
+def optional_choice(value: object, values: Sequence[str], name: str) -> str | None:
+    """`None` (not sent) or one of `values`"""
+    return None if value is None else ensure(value, values, name)

bitgen/client.py

@@ -0,0 +1,109 @@
+"""The entry point of the SDK."""
+
+from __future__ import annotations
+
+import re
+
+from bitgen._http import base_url
+from bitgen._http import timeout as timeout_
+from bitgen._http.client import HttpClient
+from bitgen._http.transport import HttpTransport
+from bitgen.constants import Env
+from bitgen.resources.apikeys import ApikeysResource
+from bitgen.resources.asset import AssetResource
+from bitgen.resources.bank import BankResource
+from bitgen.resources.core import CoreResource
+from bitgen.resources.custody import CustodyResource
+from bitgen.resources.customer import CustomerResource
+from bitgen.resources.staking import StakingResource
+from bitgen.resources.trading import TradingResource
+from bitgen.resources.transaction import TransactionResource
+from bitgen.resources.webhooks import WebhooksResource
+from bitgen.version import VERSION
+
+_PRINTABLE_ASCII = re.compile(r"[\x20-\x7E]+")
+
+
+class BitgenClient:
+    """One instance per API key; the resources hang off it (`client.customer`, `client.bank`, `client.custody`,
+    `client.trading`, `client.transaction`, `client.staking`, `client.core`, `client.webhooks`, `client.apikeys`,
+    `client.asset`). An invalid configuration raises a `ValueError` (or a `TypeError` on a wrong type) here, before
+    any request is sent.
+
+    ```python
+    client = BitgenClient(scope="YOUR_SCOPE_UUID", apiKey="YOUR_API_KEY", env=Env.SANDBOX)
+    ```
+    """
+
+    customer: CustomerResource
+    """The customers of the organization: creation, listing, accounts"""
+    bank: BankResource
+    """The EUR account of each customer"""
+    custody: CustodyResource
+    """The crypto wallets of each customer, per asset: deposit addresses, balances, on-chain withdrawals"""
+    trading: TradingResource
+    """Purchases and sales of crypto for a customer, through the exchange of the platform"""
+    transaction: TransactionResource
+    """The journal of the fiat and crypto movements of the organization, read-only"""
+    staking: StakingResource
+    """Staking positions of the customers: providers, movements, rewards, portfolio"""
+    core: CoreResource
+    """The catalogue of the connectors of the platform, read-only"""
+    webhooks: WebhooksResource
+    """The webhooks of the organization: endpoint and secret, subscriptions, delivery logs, catalogue, `verify`"""
+    apikeys: ApikeysResource
+    """The API keys of the organization and the journal of their calls, read-only"""
+    asset: AssetResource
+    """The catalogue of assets, tickers and EUR price histories"""
+
+    def __init__(
+        self,
+        *,
+        scope: str,
+        apiKey: str,
+        env: str = Env.PRODUCTION,
+        host: str | None = None,
+        port: int | None = None,
+        isSsl: bool = True,
+        timeout: int | float = timeout_.DEFAULT,
+    ) -> None:
+        """
+        :param scope: uuid of the organization that owns the key (`BITGEN-Scope` header)
+        :param apiKey: the raw key (`Api-key` header)
+        :param env: target environment, one of the `Env` constants — `Env.PRODUCTION` by default
+        :param host: custom hostname (bare: no scheme, port or path), used instead of `env`
+        :param port: port — with `host` (default 80) or `Env.LOCALHOST` (default 3002)
+        :param isSsl: `https` (default) or `http`, with `host`
+        :param timeout: request timeout in seconds, `30` by default, `0` = none
+        """
+        _require_header_value(scope, "scope")
+        _require_header_value(apiKey, "apiKey")
+        self._http = HttpClient(
+            HttpTransport(),
+            scope,
+            apiKey,
+            base_url.resolve(env, host, port, isSsl),
+            timeout_.resolve(timeout),
+            f"bitgen-sdk-python/{VERSION}",
+        )
+        self.customer = CustomerResource(self._http)
+        self.bank = BankResource(self._http)
+        self.custody = CustodyResource(self._http)
+        self.trading = TradingResource(self._http)
+        self.transaction = TransactionResource(self._http)
+        core = CoreResource(self._http)  # built first: the staking providers are read from the core catalogue
+        self.staking = StakingResource(self._http, core)
+        self.core = core
+        self.webhooks = WebhooksResource(self._http)
+        self.apikeys = ApikeysResource(self._http)
+        self.asset = AssetResource(self._http)
+
+
+def _require_header_value(value: object, name: str) -> None:
+    """Non-empty printable ASCII (a header value) — the value itself is never echoed"""
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a non-empty string")
+    if value == "":
+        raise ValueError(f"{name} must be a non-empty string")
+    if not _PRINTABLE_ASCII.fullmatch(value):
+        raise ValueError(f"{name} contains invalid characters (printable ASCII expected)")