bitgen-sdk 1.0.0__tar.gz

bitgen_sdk-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

bitgen_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+## [1.0.0] - 2026-09-19
+
+### Added
+- `BitgenClient` with keyword-only arguments (`scope`, `apiKey`, `env`, `host`, `port`, `isSsl`, `timeout`); `env` is one of the `bitgen.Env` constants
+- `Env` (`PRODUCTION`, `SANDBOX`) and `Asset` (`BTC`, `ETH`, `USDC`, `XRP`, `SOL` — provisional list) string constants: every enumerated value is a constant on a frozen class listing its `VALUES`
+- `BitgenError` with `status` (the HTTP status) and `code` (the stable error code of the API); `str(error)` is `"<code> (HTTP <status>)"`
+- `request_timeout` / `network_error` errors (`status` `0`, transport error in `__cause__`)
+- `timeout` option, in seconds (default `30`, `0` disables), bounding the whole request
+- Invalid arguments raise a `ValueError` (or a `TypeError` on a wrong type) before any request
+- `User-Agent: bitgen-sdk-python/<version>` header on every request
+- `Page[T]` for paginated lists (`count`, `items`); `UnexpectedAnswerError` for a 2xx answer that is not the shape the API promises
+- `customer` resource (`create` with the `needActivation` / `notify` options, `list`, `get`, `update`) and its models — `Identity` as `KycIdentity` / `KybIdentity`; `UserRef` (`str | Created | Customer | Account | UserSummary | OrderUser`) wherever a customer is expected
+- `bank` resource (`get`, `operations`, `withdraw`, `credit`) and its models — amounts as `str`, `int`, `float` or `Decimal`
+- `custody` resource (`wallets`, `wallet`, `portfolio`, `withdraw` with `TravelRulePerson` / `TravelRulePlatform`) and its models
+- `trading` resource (`buy`, `sell`, `get`, `list`) and its models
+- `transaction` resource (`list`, `get`) and its models
+- `staking` resource (`providers`, `stake`, `list`, `movements`, `get`, `rewards`, `unstake`, `operations`, `portfolio`) and its models
+- `core` resource (`list`, `get`) and its models
+- `webhooks` resource (`activate`, `updateEndpoint`, `regenerate`, `list`, `subscribe`, `archive`, `reactivate`, `logs`, `catalog`, `catalogItem`) and its models, with `verify()` to check a received delivery (HMAC signature, freshness, envelope) — the headers as any `dict`, WSGI `environ`, framework `headers` object or list of `(name, value)` pairs
+- `apikeys` resource (`list`, `get`, `logs`) and its models
+- Every method that expects the uuid of an object the SDK returns also takes the model itself (`Order`, `StakingMovement`, `StakingPosition`, `Core`, `Transaction`, `Subscriber`, `WebhookType`, `Apikey`)
+- `asset` resource (`list`, `get`, `tickers`, `ticker`) and its models under `bitgen.models` (`Asset`, `AssetTicker`, `AssetFees`, `AssetNetwork`…, the `AssetState` constants, the shared `History`); every method that expects an asset also takes an `Asset` / `AssetRef` model
+- No dependency beyond the standard library; Python 3.11 or later; fully typed (`py.typed`)

bitgen_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: bitgen-sdk
+Version: 1.0.0
+Summary: Official Python SDK for the BITGEN API v4
+Project-URL: Homepage, https://github.com/bitgenplatform/sdk-python
+Project-URL: Repository, https://github.com/bitgenplatform/sdk-python
+Project-URL: Changelog, https://github.com/bitgenplatform/sdk-python/blob/main/CHANGELOG.md
+Author: BITGEN
+License-Expression: LicenseRef-Proprietary
+Keywords: bitgen,crypto,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.6; extra == 'dev'
+Requires-Dist: mypy<1.21,>=1.20; extra == 'dev'
+Requires-Dist: pytest<9,>=8.4; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
+Requires-Dist: twine<8,>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bitgen-sdk — v1.0.0
+
+Official Python SDK for the BITGEN API v4 — server-side, Python 3.11+, no dependency beyond the standard library.
+Install it with `pip install bitgen-sdk`.
+
+```python
+from bitgen import BitgenClient, Env
+
+client = BitgenClient(
+    scope="YOUR_SCOPE_UUID",  # uuid of the organization that owns the key
+    apiKey="YOUR_API_KEY",
+    env=Env.SANDBOX,  # Env.PRODUCTION by default
+)
+```
+
+- [Installation](readme/installation.md) — Python 3.11+, pip, what to import
+- [Quick start](readme/quick-start.md) — a customer, their EUR account, a wallet, a purchase
+- [Configuration](readme/configuration.md) — credentials, environments, custom host, timeout
+- [Concepts](readme/concepts.md) — user references, amounts, pagination, assets, activation, the flows of a purchase, a sale, a deposit and a withdrawal
+- [Errors](readme/errors.md) — `BitgenError`, error codes, invalid arguments
+
+Resources, in the order of an integration:
+
+- [Customers](readme/resource/customer.md) — `client.customer`
+- [Bank accounts](readme/resource/bank.md) — `client.bank`
+- [Custody wallets](readme/resource/custody.md) — `client.custody`
+- [Trading](readme/resource/trading.md) — `client.trading`
+- [Transactions](readme/resource/transaction.md) — `client.transaction`
+- [Staking](readme/resource/staking.md) — `client.staking`
+- [Connectors](readme/resource/core.md) — `client.core`
+- [Webhooks](readme/resource/webhooks.md) — `client.webhooks`
+- [API keys](readme/resource/apikeys.md) — `client.apikeys`
+- [Assets](readme/resource/asset.md) — `client.asset`
+
+## License
+
+Private — © BITGEN

bitgen_sdk-1.0.0/README.md

@@ -0,0 +1,37 @@
+# bitgen-sdk — v1.0.0
+
+Official Python SDK for the BITGEN API v4 — server-side, Python 3.11+, no dependency beyond the standard library.
+Install it with `pip install bitgen-sdk`.
+
+```python
+from bitgen import BitgenClient, Env
+
+client = BitgenClient(
+    scope="YOUR_SCOPE_UUID",  # uuid of the organization that owns the key
+    apiKey="YOUR_API_KEY",
+    env=Env.SANDBOX,  # Env.PRODUCTION by default
+)
+```
+
+- [Installation](readme/installation.md) — Python 3.11+, pip, what to import
+- [Quick start](readme/quick-start.md) — a customer, their EUR account, a wallet, a purchase
+- [Configuration](readme/configuration.md) — credentials, environments, custom host, timeout
+- [Concepts](readme/concepts.md) — user references, amounts, pagination, assets, activation, the flows of a purchase, a sale, a deposit and a withdrawal
+- [Errors](readme/errors.md) — `BitgenError`, error codes, invalid arguments
+
+Resources, in the order of an integration:
+
+- [Customers](readme/resource/customer.md) — `client.customer`
+- [Bank accounts](readme/resource/bank.md) — `client.bank`
+- [Custody wallets](readme/resource/custody.md) — `client.custody`
+- [Trading](readme/resource/trading.md) — `client.trading`
+- [Transactions](readme/resource/transaction.md) — `client.transaction`
+- [Staking](readme/resource/staking.md) — `client.staking`
+- [Connectors](readme/resource/core.md) — `client.core`
+- [Webhooks](readme/resource/webhooks.md) — `client.webhooks`
+- [API keys](readme/resource/apikeys.md) — `client.apikeys`
+- [Assets](readme/resource/asset.md) — `client.asset`
+
+## License
+
+Private — © BITGEN

bitgen_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+# hatchling 1.27 brings PEP 639 (the license expression); 1.32 starts emitting Metadata 2.5 — 2.4 until PyPI is known to take it
+requires = ["hatchling>=1.27,<1.32"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bitgen-sdk"
+dynamic = ["version"]
+description = "Official Python SDK for the BITGEN API v4"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "BITGEN" }]
+keywords = ["bitgen", "crypto", "sdk"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/bitgenplatform/sdk-python"
+Repository = "https://github.com/bitgenplatform/sdk-python"
+Changelog = "https://github.com/bitgenplatform/sdk-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.4,<9",
+    "mypy>=1.20,<1.21",
+    "ruff>=0.16,<0.17",
+    "build>=1.6,<2",
+    "twine>=7.0,<8",
+]
+
+[tool.hatch.version]
+path = "src/bitgen/version.py"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/bitgen", "readme", "README.md", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bitgen"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["error"]
+
+[tool.mypy]
+files = ["src", "tests"]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF", "PL", "PERF", "RET", "T20", "S"]
+ignore = ["PLR2004", "PLR0913", "PLR0917"]
+
+[tool.ruff.lint.per-file-ignores]
+# tests: assert is the point, subprocess runs the doc examples and openssl with our own arguments, pickle our own
+# errors, the webhook secrets are fixtures
+"tests/**" = ["T20", "S101", "S603", "S301", "S105"]

bitgen_sdk-1.0.0/readme/concepts.md

@@ -0,0 +1,128 @@
+# Concepts
+
+The conventions shared by every resource of the SDK: how a customer is designated, how amounts, pages, booleans, assets and dates travel, and which customers the financial resources accept. Examples use `client`, a configured `BitgenClient` ([Configuration](configuration.md)), and `customer`, the `Created` returned by `client.customer.create()`.
+
+## User references
+
+Wherever a method expects a customer, its signature says `UserRef` — a type alias of `bitgen.models`: `str | Created | Customer | Account | UserSummary | OrderUser`. A string is the customer's **uuid**; a model is one that carries it. The SDK sends the uuid of the model: the `Created` returned by `client.customer.create()`, a `Customer` of `client.customer.list()`, an `Account` of `client.customer.get()`, the `user` of an `Order`, the `owner` of a `Transaction` or of a `StakingMovement`.
+
+```python
+account = client.bank.get("CUSTOMER_UUID")
+account = client.bank.get(customer)  # the Created returned by client.customer.create()
+```
+
+Any other object — a `Wallet`, an `Order`, a dict with a `uuid` — is a `TypeError` at the call, before any request. An email works too where the API resolves it (`customer`, `bank`, `custody`, `staking` — not `trading`, nor the `user` filter of the lists), but the uuid is cheaper for the API — prefer it.
+
+The same goes for the other objects the SDK returns: wherever a method expects the uuid of an order, a movement, a position, a connector, a transaction, a subscription, an event of the catalogue or a key, it also takes the model itself (`client.staking.rewards(movement.staking)`, `client.trading.get(order)`), and sends its uuid.
+
+## Amounts
+
+The API handles crypto amounts as **strings** (up to 18 decimals): a Python `float` only keeps about 15 significant digits and nothing on the server side restores what it lost. The SDK therefore:
+
+- accepts a `str`, an `int`, a `float` or a `Decimal` and always sends it as a string — a string is sent as is, an `int` or a `float` in its shortest decimal form, a `Decimal` in plain notation;
+- refuses, with a `ValueError` and before any request, an empty string, a negative or non-finite number, and a `float` Python would write in exponent notation — below `0.0001` or from `1e16`: pass those as strings or as `Decimal`;
+- never rounds or reformats a string: `"0.000000000000000001"` reaches the API untouched.
+
+**Prefer strings or `Decimal`**, even for EUR: `0.1 + 0.2` is `0.30000000000000004` as a `float`. In responses, crypto quantities are strings and EUR amounts are `float`s with 2 decimals.
+
+**Minimums.** Purchases, sales, on-chain withdrawals and staking movements have minimums — set by BITGEN per environment, subject to change, never hard-coded in the SDK. The API's answer is the source of truth: `416 invalid_amount` for a purchase or a sale, `416 withdraw_below_minimum` for an on-chain withdrawal, `422 amount_below_minimum` for a staking movement. For staking, the provider's minimums are readable in its configuration (`client.staking.providers()`, [Staking](resource/staking.md#providers)).
+
+## Pagination
+
+Paginated lists take `offset` and `limit` (`limit`: default 10, max 50; the transaction journal accepts up to 100) and return a `bitgen.Page`:
+
+```python
+page = client.asset.list()
+
+page.count  # the total number of items
+page.items  # the items of this page, typed models — Page[models.Asset] here
+```
+
+`Page[T]` is generic: `page.items` is a `list[T]`, and a type checker knows what each item is.
+
+## Query booleans
+
+The boolean filters of the lists (`includeClosed`, `includeRevoked`, `includeArchived`) are sent as `true` / `false`. The API also reads `1` / `0`, treats an absent parameter as `false`, and answers `422 invalid_<param>` for any other value: `invalid_include_closed`, `invalid_include_revoked`, `invalid_include_archived`.
+
+## Assets
+
+Wherever an asset is expected, the SDK accepts its **uuid** or its **ISO code** as a string, in any case (the API normalizes it) — or an `Asset` / `AssetRef` model returned by the SDK, whose uuid is then sent. The `bitgen.Asset` constants are the ISO codes of the main assets; any other code known to the catalogue ([Assets](resource/asset.md)) is passed as a plain string.
+
+```python
+from bitgen import Asset
+
+Asset.BTC  # "btc"
+Asset.ETH  # "eth"
+Asset.USDC  # "usdc"
+Asset.XRP  # "xrp"
+Asset.SOL  # "sol"
+Asset.VALUES  # ("btc", "eth", "usdc", "xrp", "sol")
+
+eth = client.asset.get(Asset.ETH)  # or by uuid
+wallet = client.custody.wallet(customer, eth)  # the model: its uuid is sent
+```
+
+The `iso` the API returns has the case it is stored with (`ETH` today): **compare it case-insensitively**. `bitgen.Asset` holds the ISO codes; the asset returned by `client.asset` is the `bitgen.models.Asset` model.
+
+## Constants
+
+The SDK has no enums: every value the API enumerates is a **string constant** on a small class — `Env.SANDBOX` is `"sandbox"`, `Locale.FR` is `"FR"`, `TradingDirection.BUY` is `"buy"`, `AssetState.AVAILABLE` is `"AVAILABLE"`, `WebhookEventName.CUSTODY_SENT` is `"custody.sent"` — and each class lists its values in `VALUES`, in the order of the API. The classes of the values a model carries live under `bitgen.models`, next to the model.
+
+```python
+from bitgen import Asset
+from bitgen.models import AssetState, Locale
+
+eth = client.asset.get(Asset.ETH)
+if eth.state == AssetState.AVAILABLE:  # outputs are strings: compare them with the constants
+    client.customer.update(customer, locale=Locale.EN)  # inputs take the constant
+print(", ".join(Locale.VALUES))  # FR, EN
+```
+
+An input that is not one of the values (`locale="en"`, `direction="Buy"`) is refused with a `ValueError` before any request: the case matters. An output the SDK does not know yet (a state the API added) is kept as is, as a string. The constants cannot be changed or instantiated.
+
+## Timestamps and histories
+
+Timestamps are **epochs in seconds** (`createdAt`, `updatedAt`, `date`, `expiresAt`…). Time series are a `bitgen.models.History` with five lists of points, `d`, `w`, `m`, `y` and `all`:
+
+```python
+from datetime import UTC, datetime
+
+from bitgen import Asset
+
+btc = client.asset.ticker(Asset.BTC)
+
+for epoch, price in btc.history.d:  # the last 24 hours, one point per hour
+    print(datetime.fromtimestamp(epoch, tz=UTC).strftime("%H:%M"), price)
+```
+
+Each point is a tuple `(epoch seconds, value)`: `d` covers the last 24 hours with one point per hour, `w` and `m` one point per day, `y` and `all` one point per month; the last point is the current value. Histories are the EUR price of an asset (`client.asset`), the EUR balance of a bank account (`client.bank`), the EUR value of a wallet or of a whole custody (`client.custody`), and the capital and revenues of a staking portfolio (`client.staking`).
+
+## Activation and identity
+
+By default, creating a customer sends them an activation email. Until they click it, the account stays `CREATED` and the **financial resources do not see it**: the bank answers `404 unknown_bank`, custody and staking `403 org_forbidden`, trading `403 user_not_in_scope`. Only the customer resource sees it (where the customer appears as `CREATED`). An organization that handles onboarding itself creates its customers with `needActivation=False` — usable right away, no BITGEN email — and `notify=False` for no BITGEN emails at all.
+
+If your organization uses BITGEN's identity verification, the customer's identity (KYC for a person, KYB for a business) must be validated first — `412 owner_identity_not_validated` when reading the EUR account, `403 kyc_not_validated` on custody, trading and staking otherwise. An organization that verifies the identity of its customers by its own means has no such requirement. The verification itself is not part of the SDK; its state is the `state` of the customer's identity.
+
+![Activation and identity: from the creation of a customer to the financial resources](media/activation.svg)
+
+## Following a purchase and a sale
+
+A purchase moves money across four resources. Placing the order reserves the EUR on the customer's bank account — an operation `PURCHASE` ([Bank accounts](resource/bank.md)); the exchange of the platform executes it — `EXECUTING`, then `FILLED` with the price, the fee and the quantity received ([Trading](resource/trading.md)); the quantity is delivered to the customer's custody wallet — `DELIVERING`, then `DONE` ([Custody wallets](resource/custody.md)) — where it appears as a custody transaction `IN` ([Transactions](resource/transaction.md)). Afterwards, the order carries the result, the operations of the bank account show the debit, the journal the delivery, the wallet its new balance, and the event `trading.buy` is sent ([Webhooks](resource/webhooks.md)).
+
+![A purchase: the EUR reserved, the execution at the exchange, the delivery to the custody wallet, and what you read afterwards](media/purchase-flow.svg)
+
+A sale goes the other way. The quantity leaves the customer's custody wallet through an internal transfer to the exchange — a `silent` custody transaction `OUT` in the journal ([Custody wallets](resource/custody.md), [Transactions](resource/transaction.md)); the exchange executes it — `EXECUTING`, then `FILLED` at `executedPrice`, minus `fee` ([Trading](resource/trading.md)); the EUR received are credited on the customer's EUR account — `DONE`, an operation `SELL` and the event `bank.credited` ([Bank accounts](resource/bank.md)); the event `trading.sell` is sent ([Webhooks](resource/webhooks.md)).
+
+![A sale: the crypto moved from the custody wallet to the exchange, the execution, the EUR credited on the ledger, and what your organization reads afterwards](media/sale-flow.svg)
+
+## Following a deposit and a withdrawal
+
+The EUR of a customer are held by the bank provider of your organization, on the organization's account — one IBAN, the same for all your customers, that you give them yourself. BITGEN holds no funds: it keeps the **ledger** of each customer — `balance`, `pending`, `history`, operations ([Bank accounts](resource/bank.md)). The provider receives the wires and pays the withdrawals; you read the ledger and receive the events ([Webhooks](resource/webhooks.md)).
+
+![An EUR deposit: the wire to the organization account at the bank provider, its report, the matching by reference, the compliance analysis, the credit of the ledger](media/deposit-flow.svg)
+
+A deposit: the customer wires EUR to the organization's account with the reference `BTGN` followed by the code of their account (`message`) → the provider reports the wire to BITGEN — with a manual bank, you declare it ([credit](resource/bank.md#credit)) → BITGEN matches the reference and the amount enters `pending.in_` → compliance analysis: a `BANK` `IN` transaction, `bank.transaction` (`PENDING` if an alert holds it — [Transactions](resource/transaction.md)) → `balance` credited, operation `DEPOSIT`, `bank.credited`. The credit is never immediate; without a valid reference the wire is never credited, and the compliance of your organization is notified.
+
+![An EUR withdrawal: the reserve on the ledger, the compliance analysis, the wire from the organization account to the customer IBAN, the debit at confirmation](media/withdrawal-flow.svg)
+
+A withdrawal: you request it ([Withdraw](resource/bank.md#withdraw)) — the amount is reserved in `pending.out`, `balance` untouched, `transaction` identifies the withdrawal → compliance analysis, `bank.transaction` → the provider wires from the organization's account to the customer's IBAN → at confirmation, `balance` debited, operation `WITHDRAWAL`, `bank.debited` with `amount`, `fee` and `net`. If it fails, the reserve is released.

bitgen_sdk-1.0.0/readme/configuration.md

@@ -0,0 +1,74 @@
+# Configuration
+
+A `BitgenClient` is built once per API key and reused — it can be shared between threads: it holds the credentials, the target environment and the request timeout, and nothing else. Its arguments are keyword-only.
+
+```python
+from bitgen import BitgenClient, Env
+
+client = BitgenClient(
+    scope="YOUR_SCOPE_UUID",
+    apiKey="YOUR_API_KEY",
+    env=Env.PRODUCTION,  # default
+    timeout=30,  # seconds, default 30
+)
+```
+
+## Credentials
+
+| Argument | Description |
+|---|---|
+| `scope` | uuid of the organization that owns the key. Sent as the `BITGEN-Scope` header. It is also the organization the SDK uses wherever the API expects yours. |
+| `apiKey` | The raw key, shown once when it is created. Sent as the `Api-key` header. |
+
+A missing key, an unknown, revoked or expired key, or a `scope` that is not the key's organization, is refused with a `401` ([Common errors](errors.md#common-errors)).
+
+## Environments
+
+| `env` | Constant | URL |
+|---|---|---|
+| `production` | `Env.PRODUCTION` (default) | `https://api.bitgen.com` |
+| `sandbox` | `Env.SANDBOX` | `https://api.sandbox.bitgen.com` |
+
+`Env` holds these names as constants (`Env.VALUES` lists them): pass the constant. Anything else is refused before any request ([Validation](#validation)).
+
+## Custom host
+
+To reach the API through another hostname — a container, a tunnel — give `host` instead of `env`:
+
+```python
+from bitgen import BitgenClient
+
+client = BitgenClient(
+    scope="YOUR_SCOPE_UUID",
+    apiKey="YOUR_API_KEY",
+    host="my-hostname",  # bare hostname: no scheme, port or path
+    port=8080,  # default 80
+    isSsl=False,  # default True (https)
+)
+```
+
+`isSsl=False` sends the key unencrypted: only towards a local container or a tunnel, never across a network.
+
+## Timeout
+
+`timeout` is the maximum time, in seconds, the SDK waits for the API to answer — the whole request, from the connection to the last byte of the answer: `30` by default, `0` disables it; an `int` or a `float` (`0.5`). When it expires, the call raises a `BitgenError` with `status` `0` and `code` `request_timeout` ([No HTTP response](errors.md#no-http-response)).
+
+## Requests
+
+Every request carries the headers `BITGEN-Scope`, `Api-key`, `Content-Type: application/json`, `Accept: application/json` and `User-Agent: bitgen-sdk-python/<version>`, where `<version>` is the installed version of the SDK. TLS certificates are verified against the certificates of the system — or against those named by the `SSL_CERT_FILE` / `SSL_CERT_DIR` environment variables of OpenSSL, for a private certificate authority. Redirects are never followed. The SDK connects directly: it does not read the proxy variables of the environment.
+
+## Validation
+
+An invalid configuration raises a `ValueError` from the constructor — or a `TypeError` when an argument has the wrong type — before any request is sent: empty `scope` or `apiKey` (or one that is not printable ASCII), `env` that is not one of `Env.VALUES`, `host` that is not a bare hostname, `port` outside 1–65535, `timeout` that is not a number of seconds between `0` and `2147483`. The values of `scope`, `apiKey`, `env` and `host` never appear in the message. Every other invalid argument is refused the same way, by the method that receives it ([Invalid arguments](errors.md#invalid-arguments)).
+
+## Options
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `scope` | `str` | — | Organization uuid |
+| `apiKey` | `str` | — | API key |
+| `env` | `str` | `Env.PRODUCTION` | Target environment — an `Env` constant |
+| `host` | `str \| None` | `None` | Custom hostname, used instead of `env` |
+| `port` | `int \| None` | `80` | Port, with `host` |
+| `isSsl` | `bool` | `True` | `https` or `http`, with `host` |
+| `timeout` | `int \| float` | `30` | Request timeout in seconds, `0` = none |

bitgen_sdk-1.0.0/readme/errors.md

@@ -0,0 +1,73 @@
+# Errors
+
+The API answers with real HTTP status codes and, on failure, a JSON body `{ error: true, message: '<code>', code: <status> }` where `message` is a stable snake_case code (`invalid_amount`, `unknown_asset`…), never a sentence. The SDK turns every non-2xx answer — and every request that gets no HTTP answer at all — into a `BitgenError`.
+
+## BitgenError
+
+`bitgen.BitgenError` extends `Exception`:
+
+| Member | Type | Description |
+|---|---|---|
+| `status` | `int` | The HTTP status (`416`…), or `0` when no HTTP response was received |
+| `code` | `str` | The stable code of the API (`requested_amount_error`), or the raw response text when the body is not the API's JSON error |
+| `str(error)` | `str` | `"<code> (HTTP <status>)"` |
+| `__cause__` | `BaseException \| None` | The transport error, for `request_timeout` and `network_error` — `None` otherwise |
+
+```python
+from bitgen import BitgenError
+
+try:
+    ...  # any call of the SDK
+except BitgenError as error:
+    error.status  # 416
+    error.code  # "requested_amount_error"
+    str(error)  # "requested_amount_error (HTTP 416)"
+```
+
+Nothing in the exception ever contains your API key: not the message, not the cause — even a raw response that echoes it back has the key redacted.
+
+## No HTTP response
+
+| Status | `code` | Meaning |
+|---|---|---|
+| `0` | `request_timeout` | No response within the configured `timeout` — 30 seconds by default ([Timeout](configuration.md#timeout)) |
+| `0` | `network_error` | The request never got an HTTP answer: DNS, connection refused, TLS… `__cause__` holds the transport error |
+
+## Webhook verification
+
+`client.webhooks.verify()` checks a delivery received by your endpoint locally, without any request: a delivery that fails the verification raises a `BitgenError` with `status` `0` and one of these codes ([Webhooks › verify](resource/webhooks.md#verify)):
+
+| Status | `code` | Meaning |
+|---|---|---|
+| `0` | `missing_signature` | No `X-BITGEN-Signature` header |
+| `0` | `invalid_signature` | The signature does not match the body and the secret |
+| `0` | `missing_timestamp` | No `X-BITGEN-Timestamp` header, or not a number |
+| `0` | `timestamp_expired` | The timestamp of the delivery is more than `tolerance` seconds away from now (300 by default) |
+| `0` | `invalid_payload` | The body is not the JSON envelope `{ delivery_id, timestamp, event, data }` |
+
+## Unexpected answers
+
+When the body is not the API's JSON error payload (proxy error page, unexpected `500`…), `code` holds the raw response text, truncated to 200 characters; the same goes for a 2xx answer that is not JSON. A `500` is not always a failure of the API: it is also its answer to a request it does not recognize — with a custom `host`, check that it reaches the API unchanged. Redirects are never followed: a `3xx` answer is reported as a `BitgenError`, and the key is never replayed to another host. A 2xx answer that is JSON but not the shape the SDK expects (not an object, not a list of objects where the API promises one, a page whose `items` is not a list…) raises a `bitgen.UnexpectedAnswerError`: not an error of the API, a contract violation to report to BITGEN. A value the SDK enumerates (a `state`, a `mode`…) is never checked: the API may add one, the models keep it as a string.
+
+## Invalid arguments
+
+An invalid argument — an empty `scope` or `apiKey`, a `host` with a scheme, a negative `timeout`, a value outside a constant list ([Constants](concepts.md#constants)), an empty asset… — raises a `ValueError` **before any request is sent**, from the constructor or from the method that receives it; an argument of the wrong type (a `port` given as a string) raises a `TypeError` the same way ([Validation](configuration.md#validation)).
+
+## Common errors
+
+The errors any call can answer.
+
+| Status | `code` | Meaning |
+|---|---|---|
+| `401` | `auth_missing` | The `BITGEN-Scope` or `Api-key` header is missing |
+| `401` | `api_key_missmatch` | The key is unknown, revoked or expired, or `scope` is not the key's organization |
+| `403` | `unknown_organization` | The organization of the key is unknown |
+| `403` | `organization_not_enabled` | The organization is not enabled |
+| `403` | `api_disabled` | API access is not enabled for the organization |
+| `403` | `invalid_api_key` | The key is invalid |
+| `403` | `expired_api_key` | The key has expired |
+| `403` | `forbidden_permission` | The key does not carry the permission for this call — contact BITGEN |
+| `400` | `required_index_missing::<field>` | A mandatory field is missing or empty |
+| `404` | `unknown_<resource>` | The target does not exist — `unknown_user`, `unknown_asset`, `unknown_bank`… — or the API does not reveal it |
+| `422` | `invalid_<param>` | A boolean filter (`includeClosed`, `includeRevoked`, `includeArchived`) is not a boolean value |
+| `423` | `blocked_by_alert` | The customer is under an active compliance alert |

bitgen_sdk-1.0.0/readme/installation.md

@@ -0,0 +1,39 @@
+# Installation
+
+`bitgen-sdk` is the official Python SDK for the BITGEN API v4. It runs server-side only: the API accepts browser requests from a fixed list of origins, so the SDK is not meant to be used from a browser.
+
+## Requirements
+
+- Python 3.11 or later
+- No other dependency: the SDK only uses what Python already provides
+
+## Install
+
+```bash
+pip install bitgen-sdk
+```
+
+## Import
+
+The client, its errors and the constants are imported from the `bitgen` package:
+
+```python
+from bitgen import Asset, BitgenClient, BitgenError, Env
+```
+
+The package exposes the client (`BitgenClient`), its exception (`BitgenError`), two constant classes — `Env`, the environments, and `Asset`, the ISO codes of the main assets ([Configuration](configuration.md), [Assets](concepts.md#assets)) — and `Page`, the paginated lists. Under `bitgen.models` live the models the resources return, the constant classes naming their known values ([Constants](concepts.md#constants)), and the few objects a call takes as input (`TravelRulePerson`, `TravelRulePlatform`, the `ReceivedHeaders` shape of `verify`):
+
+```python
+from bitgen.models import AssetState, History
+```
+
+## Typing
+
+The SDK is fully typed and ships its type information (`py.typed`), so a type checker such as mypy or pyright sees every signature: paginated lists are a generic `Page[T]` (`page.count`, `page.items`), and every value the API returns is an immutable object with typed attributes.
+
+## Next steps
+
+- [Quick start](quick-start.md) — create the client and run a first customer journey
+- [Configuration](configuration.md) — credentials, environments, custom host, timeout
+- [Concepts](concepts.md) — user references, amounts, pagination, assets, activation, the flows of a purchase, a sale, a deposit and a withdrawal
+- [Errors](errors.md) — what a failed call raises, and what is checked before any request

bitgen_sdk-1.0.0/readme/media/activation.svg

@@ -0,0 +1,58 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 560" role="img" aria-labelledby="title">
+  <title id="title">Activation and identity: from the creation of a customer to the financial resources</title>
+  <defs>
+    <marker id="m94a3b8" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="8" markerHeight="8" markerUnits="userSpaceOnUse" orient="auto"><path d="M0,0.5 L7,4 L0,7.5 z" fill="#94a3b8"/></marker>
+    <pattern id="grid" width="16" height="16" patternUnits="userSpaceOnUse"><circle cx="8" cy="8" r="1" fill="#e2e8f0"/></pattern>
+    <filter id="shadow" x="-10%" y="-20%" width="120%" height="160%"><feDropShadow dx="0" dy="1" stdDeviation="2" flood-color="#0f172a" flood-opacity="0.10"/></filter>
+  </defs>
+  <rect width="1000" height="560" fill="#ffffff"/>
+  <rect width="1000" height="560" fill="url(#grid)"/>
+  <text x="520.0" y="34.5" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="14" font-weight="600" fill="#0f172a" text-anchor="middle">Activation and identity</text>
+  <rect x="420" y="54" width="200" height="40" rx="10" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+  <text x="520.0" y="78.7" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="13" font-weight="500" fill="#0f172a" text-anchor="middle">Create a customer</text>
+  <path d="M520,95 V116" fill="none" stroke="#94a3b8" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#m94a3b8)"/>
+  <rect x="455" y="118" width="130" height="24" rx="12.0" fill="#0f172a"/>
+  <text x="520.0" y="134.1" font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="11.5" font-weight="500" fill="#ffffff" text-anchor="middle">needActivation?</text>
+  <path d="M520,143 V178" fill="none" stroke="#94a3b8" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#m94a3b8)"/>
+  <rect x="533" y="148" width="66" height="24" rx="12.0" fill="#f1f5f9"/>
+  <text x="566.0" y="164.1" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="500" fill="#475569" text-anchor="middle">default</text>
+  <rect x="360" y="180" width="320" height="56" rx="10" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+  <text x="520.0" y="204.2" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="13" font-weight="400" fill="#0f172a" text-anchor="middle">Activation email sent, account <tspan font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="0.92em" font-weight="600" fill="#4338ca">CREATED</tspan></text>
+  <text x="520.0" y="221.2" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="13" font-weight="400" fill="#0f172a" text-anchor="middle">until the customer clicks it</text>
+  <path d="M520,237 V282" fill="none" stroke="#94a3b8" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#m94a3b8)"/>
+  <rect x="529" y="247" width="54" height="24" rx="12.0" fill="#f1f5f9"/>
+  <text x="556.0" y="263.1" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="500" fill="#475569" text-anchor="middle">click</text>
+  <path d="M590,130 H790 Q800,130 800,140 V306 Q800,316 790,316 H612" fill="none" stroke="#94a3b8" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#m94a3b8)"/>
+  <rect x="713" y="118" width="54" height="24" rx="12.0" fill="#f1f5f9"/>
+  <text x="740.0" y="134.1" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="500" fill="#475569" text-anchor="middle">false</text>
+  <rect x="430" y="296" width="180" height="40" rx="10" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+  <text x="520.0" y="320.7" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="13" font-weight="400" fill="#0f172a" text-anchor="middle">Account <tspan font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="0.92em" font-weight="600" fill="#4338ca">ENABLED</tspan></text>
+  <rect x="40" y="176" width="340" height="106" rx="10" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+  <path d="M50,188 V270" stroke="#dc2626" stroke-width="3" stroke-linecap="round"/>
+  <text x="64.0" y="200.0" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="12" font-weight="600" fill="#0f172a" text-anchor="start">Meanwhile, only the customer resource sees it</text>
+  <text x="64.0" y="220.0" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="400" fill="#475569" text-anchor="start">bank: <tspan font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="0.92em" font-weight="600" fill="#dc2626">404 unknown_bank</tspan></text>
+  <text x="64.0" y="237.0" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="400" fill="#475569" text-anchor="start">custody, staking: <tspan font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="0.92em" font-weight="600" fill="#dc2626">403 org_forbidden</tspan></text>
+  <text x="64.0" y="254.0" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="400" fill="#475569" text-anchor="start">trading: <tspan font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="0.92em" font-weight="600" fill="#dc2626">403 user_not_in_scope</tspan></text>
+  <path d="M380,229 H358" fill="none" stroke="#cbd5e1" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="4 4"/>
+  <path d="M520,337 V358" fill="none" stroke="#94a3b8" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#m94a3b8)"/>
+  <rect x="418" y="360" width="205" height="24" rx="12.0" fill="#0f172a"/>
+  <text x="520.0" y="376.1" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="500" fill="#ffffff" text-anchor="middle">BITGEN identity verification?</text>
+  <path d="M520,385 V420" fill="none" stroke="#94a3b8" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#m94a3b8)"/>
+  <rect x="530" y="390" width="41" height="24" rx="12.0" fill="#f1f5f9"/>
+  <text x="550.0" y="406.1" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="500" fill="#475569" text-anchor="middle">yes</text>
+  <rect x="360" y="422" width="320" height="56" rx="10" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+  <text x="520.0" y="446.2" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="13" font-weight="400" fill="#0f172a" text-anchor="middle">Identity verification, KYC or KYB,</text>
+  <text x="520.0" y="463.2" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="13" font-weight="400" fill="#0f172a" text-anchor="middle">until the identity is <tspan font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="0.92em" font-weight="600" fill="#4338ca">VALIDATED</tspan></text>
+  <path d="M520,479 V510" fill="none" stroke="#94a3b8" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#m94a3b8)"/>
+  <path d="M620,372 H790 Q800,372 800,382 V520 Q800,530 790,530 H672" fill="none" stroke="#94a3b8" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#m94a3b8)"/>
+  <rect x="733" y="360" width="35" height="24" rx="12.0" fill="#f1f5f9"/>
+  <text x="750.0" y="376.1" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="500" fill="#475569" text-anchor="middle">no</text>
+  <rect x="40" y="412" width="340" height="88" rx="10" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+  <path d="M50,424 V488" stroke="#dc2626" stroke-width="3" stroke-linecap="round"/>
+  <text x="64.0" y="436.0" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="12" font-weight="600" fill="#0f172a" text-anchor="start">Before that</text>
+  <text x="64.0" y="456.0" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="400" fill="#475569" text-anchor="start">EUR account: <tspan font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="0.92em" font-weight="600" fill="#dc2626">412 owner_identity_not_validated</tspan></text>
+  <text x="64.0" y="473.0" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="11.5" font-weight="400" fill="#475569" text-anchor="start">custody, trading, staking: <tspan font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="0.92em" font-weight="600" fill="#dc2626">403 kyc_not_validated</tspan></text>
+  <path d="M380,456 H358" fill="none" stroke="#cbd5e1" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="4 4"/>
+  <rect x="370" y="510" width="300" height="40" rx="10" fill="#dcfce7" stroke="#bbf7d0" filter="url(#shadow)"/>
+  <text x="520.0" y="534.7" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="13" font-weight="600" fill="#15803d" text-anchor="middle">Bank account, custody, trading and staking</text>
+</svg>