tcbs-api 1.0.0__tar.gz

tcbs_api-1.0.0/.gitignore

@@ -0,0 +1,46 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Installers
+pip-wheel-metadata/
+share/python-wheels/
+
+# Unit test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+# (uv.lock is intentionally committed for reproducible dev environments)
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store

tcbs_api-1.0.0/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-09-19
+
+### Changed
+
+- **Repackaged for distribution.** The project is now a standard, PEP 517/518
+  installable package that works with `uv`, `pip`, and any other standards-compliant
+  installer.
+- **Import package renamed** from the generic top-level `openapi` to `tcbs_api`, so it
+  matches the distribution name `tcbs-api` and no longer risks colliding with another
+  package on `sys.path`. Every public import changes accordingly, for example
+  `import openapi.service.stock_normal.normal` becomes
+  `from tcbs_api.service.stock_normal import normal`.
+- Replaced `setup.py` with a declarative `pyproject.toml` (hatchling build backend) and
+  a single-sourced `__version__` in `tcbs_api/__init__.py`.
+- Trimmed `install_requires` from a 65-entry `pip freeze` dump down to the three
+  packages actually imported: `requests`, `dacite`, and `dataclasses-json`.
+- Moved the commented-out usage demo out of the installed package and into the README.
+- Package metadata now credits **nghialuffy** as the author and points at the GitHub
+  repository: `Homepage`, `Repository`, `Issues`, and `Changelog` URLs were added, and the
+  TCBS documentation site moved to the `Documentation` URL. The MIT `LICENSE` copyright
+  holder was updated to match.
+- The 28 doc-comment links in the service modules were repointed at the current
+  `https://developers.tcbs.com.vn/docs/v1.0.0/…` documentation. The Redoc-style
+  `#tag/…/operation/…` anchors they pointed at no longer exist.
+- License metadata now uses the PEP 639 SPDX form — `license = "MIT"` plus
+  `license-files = ["LICENSE"]`, which publishes `License-Expression: MIT` — and the
+  `License :: OSI Approved :: MIT License` classifier was dropped, because PEP 639 forbids
+  combining a license classifier with a `License-Expression`.
+
+### Fixed
+
+- **`from .money import *` shadowed the money service module.** Because
+  `tcbs_api/service/money/money.py` imports the DTO module as `money`, the wildcard
+  re-export in its `__init__.py` rebound the `money` attribute to the DTO module. As a
+  result both `from tcbs_api.service.money import money` and
+  `import tcbs_api.service.money.money as money_service` — the form the old README
+  documented — resolved to `tcbs_api.dto.money.money`, so
+  `money_service.transfer_between_subaccounts(...)` raised `AttributeError`.
+  `tcbs_api/service/money/__init__.py` is the one package that now lists its three
+  functions explicitly. Every other package keeps its wildcard re-export, so those
+  packages continue to leak their imports (`requests`, `Config`, `constant`, …) into
+  their namespaces.
+- **`get_command_match_information` called the wrong endpoint.** It requested
+  `/aion/v1/accounts/{accountNo}/orders` — the same URL as `get_orders`, decoding a
+  different response DTO. The documented `get order matching information` operation is
+  `GET /aion/v1/accounts/{accountNo}/matching-details`, whose response fields
+  (`orderId`, `side`, `symbol`, `quoteQtty`, `quotePrice`, `tradeId`, `qtty`, `price`,
+  `timeExec`) match `CommandMatchInformationDetailResponse` exactly.
+- **Four DTO classes could not be instantiated.** `OrderConditionDerivativeResponseDTO`,
+  `EditOrderNormalDerivativeResponseDTO`, `EditOrderConditionDerivativeResponseDTO`, and
+  `CancelOrderNormalDerivativeResponseDTO` had `@dataclass` above `@dataclass_json`
+  instead of below it. That order leaves `__init__` set to `object.__init__`, so the
+  classes raised `TypeError: takes no arguments` on construction and on `from_json()`.
+  The decorator order now matches the other DTOs in the module.
+
+### Removed
+
+- Committed build artifacts: `open_api_tcbs.egg-info/`, `PKG-INFO`, `setup.cfg`,
+  `SOURCES.txt`, `requires.txt`, and `top_level.txt`.
+- The shadowed duplicate `OrderConditionDerivativeRequestDTO` definition in
+  `tcbs_api/dto/derivative_dto/derivative_dto.py` (the first had `str` fields and was
+  overwritten by the second, which is the signature the documented call site uses).
+- Unused `Optional`/`field` imports in `tcbs_api/dto/money/money.py`.
+- **All `print()` calls in the service layer.** A stray `print(response)` in
+  `get_token()` wrote a raw `requests.Response` to stdout on every call, and 11
+  `print(response.json())` calls ran on the error path. The latter executed *before*
+  `raise_for_status()`, so a non-JSON error body (a proxy 502, an HTML error page) raised
+  `JSONDecodeError` from `json()` and masked the `requests.HTTPError` the README
+  documents; they also wrote response payloads to stdout. Errors now surface solely as
+  `requests.HTTPError`, whose `response` attribute carries the body.
+
+### Added
+
+- `LICENSE` (MIT), this changelog, and a `.gitignore`.
+- `tcbs_api/py.typed` (PEP 561) so type checkers use the inline DTO annotations.
+- `ruff` and `mypy` configuration in `pyproject.toml`.
+- Type annotations across the public service and utility API.
+- `.github/workflows/publish.yml`, which publishes to PyPI via OIDC trusted publishing
+  (no API token in the repo), gated on `twine check --strict` and a tag/version match,
+  plus a "Releasing" section in the README covering the one-time PyPI setup.

tcbs_api-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 nghialuffy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tcbs_api-1.0.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.5
+Name: tcbs-api
+Version: 1.0.0
+Summary: Python client library for the TCBS Open API.
+Project-URL: Homepage, https://github.com/nghialuffy/tcbs-api
+Project-URL: Repository, https://github.com/nghialuffy/tcbs-api
+Project-URL: Issues, https://github.com/nghialuffy/tcbs-api/issues
+Project-URL: Changelog, https://github.com/nghialuffy/tcbs-api/releases
+Project-URL: Documentation, https://developers.tcbs.com.vn/
+Author: nghialuffy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: derivative,open-api,stock,tcbs,tcbs-api,trading,vietnam
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: dacite>=1.8
+Requires-Dist: dataclasses-json>=0.6
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tcbs-api
+
+Python client library for the [TCBS Open API](https://developers.tcbs.com.vn/).
+
+Thin, dependency-light wrapper over the TCBS REST endpoints: authentication, account
+information, cash transfers, stock (normal) trading, and derivatives trading. Responses
+are parsed into typed `dataclass` DTOs with `dacite`, so you get autocompletion instead
+of hand-written `dict` poking.
+
+The one exception is the derivative endpoints, whose response envelope is typed but whose
+`data` payload is left as a raw `dict` — see [Known limitations](#known-limitations).
+
+- Distribution name: `tcbs-api`
+- Import package: `tcbs_api`
+- Source code: <https://github.com/nghialuffy/tcbs-api>
+- Issue tracker: <https://github.com/nghialuffy/tcbs-api/issues>
+- Official API docs: <https://developers.tcbs.com.vn/>
+
+## Requirements
+
+- Python 3.8 or newer
+- A TCBS Open API key (obtain it from the [TCBS developer portal](https://developers.tcbs.com.vn/))
+
+## Installation
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add tcbs-api
+```
+
+With pip:
+
+```bash
+pip install tcbs-api
+```
+
+From a source checkout (either tool):
+
+```bash
+uv add git+https://github.com/nghialuffy/tcbs-api
+pip install git+https://github.com/nghialuffy/tcbs-api
+```
+
+For development, install the lint/type-check extras:
+
+```bash
+uv sync --extra dev    # or: pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from tcbs_api.dto import money as money_dto
+from tcbs_api.service.account import account as account_service
+from tcbs_api.service.authen import token as token_service
+from tcbs_api.service.money import money as money_service
+
+API_KEY = "your-api-key"
+OTP = "your-otp"
+
+# 2.1.1. Exchange the API key for a JWT token.
+# NOTE: this endpoint is rate limited to 10 requests/day — persist the token
+# and reuse it instead of calling this on every request.
+token = token_service.get_token(API_KEY, OTP).token
+
+# 3.1.1. Account information.
+custody_code = "0001201435"
+info = account_service.get_subaccount_info(
+    custody_code,
+    "basicInfo,personalInfo,bankSubAccounts,bankAccounts",
+    token,
+)
+print(info.personalInfo.fullName)
+
+# 4.1.1. Transfer money between sub-accounts.
+request_dto = money_dto.TransferBetweenSubaccountRequestDTO(
+    sourceAccountNumber="105C336655A",
+    destinationAccountNumber="0001201435",
+    amount=10_000,
+    description="CHUYEN TIEN PHAI SINH",
+)
+result = money_service.transfer_between_subaccounts(request_dto, token)
+print(result.code, result.message)
+```
+
+## Placing an order
+
+```python
+from tcbs_api.dto.stock_normal import stock_normal_dto
+from tcbs_api.service.stock_normal import normal as stock_service
+
+request_dto = stock_normal_dto.PlaceOrderExternalDto(
+    execType="NS",
+    price=1000,
+    priceType="LO",
+    quantity=100,
+    symbol="FPT",
+)
+response = stock_service.place_order(request_dto, account_no="0001201435", token=token)
+print(response.orderId)
+```
+
+## API reference
+
+The public API mirrors the numbering used in the TCBS documentation. Every function takes
+the JWT `token` as its last positional argument, and each carries a comment naming the
+section it implements.
+
+| Module | Covers |
+| --- | --- |
+| `tcbs_api.service.authen` | Exchange an API key for a JWT token (2.1.1) |
+| `tcbs_api.service.account` | Account information (3.1.1) |
+| `tcbs_api.service.money` | Internal transfers, margin deposit and withdrawal (4.x) |
+| `tcbs_api.service.stock_normal` | Stock order lifecycle, purchasing power, assets (5.x) |
+| `tcbs_api.service.derivative` | Derivatives cash, positions, orders, market data (6.x) |
+
+Request and response models live under `tcbs_api.dto`, grouped by the same domains.
+
+## Error handling
+
+Non-2xx responses call `requests.Response.raise_for_status()`, so HTTP failures surface
+as `requests.HTTPError`:
+
+```python
+import requests
+
+from tcbs_api.service.stock_normal import normal as stock_service
+
+try:
+    response = stock_service.get_orders(account_no="0001201435", token=token)
+except requests.HTTPError as exc:
+    print(exc.response.status_code, exc.response.json())
+```
+
+## Development
+
+```bash
+git clone https://github.com/nghialuffy/tcbs-api
+cd tcbs-api
+
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy tcbs_api
+uv build
+```
+
+## Releasing
+
+Publishing is automated by
+[`.github/workflows/publish.yml`](https://github.com/nghialuffy/tcbs-api/blob/main/.github/workflows/publish.yml)
+using PyPI [trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC), so no
+API token is stored in this repository.
+
+### One-time setup
+
+On PyPI, go to **Account → Publishing → Add a pending publisher** and fill in:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `tcbs-api` |
+| Owner | `nghialuffy` |
+| Repository name | `tcbs-api` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+The environment name must match the `environment:` key in the publish job.
+
+### Cutting a release
+
+`tcbs_api/__init__.py` is the single source of truth for the version — `pyproject.toml`
+reads it dynamically, so there is nothing to keep in sync.
+
+1. Bump `__version__` in `tcbs_api/__init__.py` and add a matching `CHANGELOG.md` entry.
+2. Commit, then tag and push:
+   ```bash
+   git commit -am "release: vX.Y.Z"
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   git push origin main --follow-tags
+   ```
+3. Publish a GitHub Release for that tag. The workflow builds the sdist and wheel, runs
+   `twine check --strict`, verifies the built version matches the tag, and uploads to
+   PyPI.
+
+Because `tcbs-api` does not exist on PyPI yet, the first release needs a **pending**
+publisher as shown above. Once the project exists, the same entry is managed from the
+project's own settings instead.
+
+### Rehearsing on TestPyPI
+
+Run the same commands against TestPyPI before a real release:
+
+```bash
+uv build
+uv publish --publish-url https://test.pypi.org/legacy/ --token pypi-<testpypi-token>
+```
+
+### Notes
+
+- A published version can **never** be re-uploaded, so bump `__version__` for every
+  attempt — including failed ones. The tag/version guard in the workflow catches the
+  common slip of tagging a version you forgot to bump.
+- Keep the tag (with a `v` prefix) in sync with `__version__` (no `v`); the workflow
+  strips the prefix before comparing.
+
+## Known limitations
+
+### Derivative payloads are not typed
+
+The derivative endpoints return a `DerivativeResponse` envelope, but its generic `data`
+field stays a raw `dict`. `dataclasses_json` cannot resolve the `Generic[T]` parameter —
+it warns `Unknown type ~T at DerivativeResponse.data` — so the declared element type is
+never applied:
+
+```python
+from tcbs_api.dto.derivative_dto import TotalCashDerivativeResponse
+from tcbs_api.service.derivative import derivative as derivative_service
+
+envelope = derivative_service.get_total_cash_derivative(account_id, sub_account_id, "0", token)
+type(envelope)        # <class 'tcbs_api.dto.derivative_dto.derivative_dto.DerivativeResponse'>
+type(envelope.data)   # <class 'dict'>
+
+# Decode the payload yourself to get the typed object:
+cash = TotalCashDerivativeResponse.from_dict(envelope.data, infer_missing=True)
+```
+
+### `Optional[...]` fields have no defaults
+
+Many DTO fields are annotated `Optional[...]` but are not given a `= None` default, so
+`dataclasses_json`'s `from_dict`/`from_json` raise `KeyError` when a field is missing from
+the payload. Pass `infer_missing=True` (as above) to tolerate missing keys. Decoding in
+the library itself is unaffected, because the non-derivative endpoints use `dacite` with
+`Config(strict=False)`.
+
+### Operational notes
+
+- The token endpoint is limited to **10 requests per day** by TCBS; cache the token.
+- The library performs no retries, rate limiting, or token refresh — callers own that
+  policy.
+- Requests are issued synchronously with `requests`. There is no async client.
+
+## License
+
+MIT — see [LICENSE](https://github.com/nghialuffy/tcbs-api/blob/main/LICENSE).

tcbs_api-1.0.0/README.md

@@ -0,0 +1,245 @@
+# tcbs-api
+
+Python client library for the [TCBS Open API](https://developers.tcbs.com.vn/).
+
+Thin, dependency-light wrapper over the TCBS REST endpoints: authentication, account
+information, cash transfers, stock (normal) trading, and derivatives trading. Responses
+are parsed into typed `dataclass` DTOs with `dacite`, so you get autocompletion instead
+of hand-written `dict` poking.
+
+The one exception is the derivative endpoints, whose response envelope is typed but whose
+`data` payload is left as a raw `dict` — see [Known limitations](#known-limitations).
+
+- Distribution name: `tcbs-api`
+- Import package: `tcbs_api`
+- Source code: <https://github.com/nghialuffy/tcbs-api>
+- Issue tracker: <https://github.com/nghialuffy/tcbs-api/issues>
+- Official API docs: <https://developers.tcbs.com.vn/>
+
+## Requirements
+
+- Python 3.8 or newer
+- A TCBS Open API key (obtain it from the [TCBS developer portal](https://developers.tcbs.com.vn/))
+
+## Installation
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add tcbs-api
+```
+
+With pip:
+
+```bash
+pip install tcbs-api
+```
+
+From a source checkout (either tool):
+
+```bash
+uv add git+https://github.com/nghialuffy/tcbs-api
+pip install git+https://github.com/nghialuffy/tcbs-api
+```
+
+For development, install the lint/type-check extras:
+
+```bash
+uv sync --extra dev    # or: pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from tcbs_api.dto import money as money_dto
+from tcbs_api.service.account import account as account_service
+from tcbs_api.service.authen import token as token_service
+from tcbs_api.service.money import money as money_service
+
+API_KEY = "your-api-key"
+OTP = "your-otp"
+
+# 2.1.1. Exchange the API key for a JWT token.
+# NOTE: this endpoint is rate limited to 10 requests/day — persist the token
+# and reuse it instead of calling this on every request.
+token = token_service.get_token(API_KEY, OTP).token
+
+# 3.1.1. Account information.
+custody_code = "0001201435"
+info = account_service.get_subaccount_info(
+    custody_code,
+    "basicInfo,personalInfo,bankSubAccounts,bankAccounts",
+    token,
+)
+print(info.personalInfo.fullName)
+
+# 4.1.1. Transfer money between sub-accounts.
+request_dto = money_dto.TransferBetweenSubaccountRequestDTO(
+    sourceAccountNumber="105C336655A",
+    destinationAccountNumber="0001201435",
+    amount=10_000,
+    description="CHUYEN TIEN PHAI SINH",
+)
+result = money_service.transfer_between_subaccounts(request_dto, token)
+print(result.code, result.message)
+```
+
+## Placing an order
+
+```python
+from tcbs_api.dto.stock_normal import stock_normal_dto
+from tcbs_api.service.stock_normal import normal as stock_service
+
+request_dto = stock_normal_dto.PlaceOrderExternalDto(
+    execType="NS",
+    price=1000,
+    priceType="LO",
+    quantity=100,
+    symbol="FPT",
+)
+response = stock_service.place_order(request_dto, account_no="0001201435", token=token)
+print(response.orderId)
+```
+
+## API reference
+
+The public API mirrors the numbering used in the TCBS documentation. Every function takes
+the JWT `token` as its last positional argument, and each carries a comment naming the
+section it implements.
+
+| Module | Covers |
+| --- | --- |
+| `tcbs_api.service.authen` | Exchange an API key for a JWT token (2.1.1) |
+| `tcbs_api.service.account` | Account information (3.1.1) |
+| `tcbs_api.service.money` | Internal transfers, margin deposit and withdrawal (4.x) |
+| `tcbs_api.service.stock_normal` | Stock order lifecycle, purchasing power, assets (5.x) |
+| `tcbs_api.service.derivative` | Derivatives cash, positions, orders, market data (6.x) |
+
+Request and response models live under `tcbs_api.dto`, grouped by the same domains.
+
+## Error handling
+
+Non-2xx responses call `requests.Response.raise_for_status()`, so HTTP failures surface
+as `requests.HTTPError`:
+
+```python
+import requests
+
+from tcbs_api.service.stock_normal import normal as stock_service
+
+try:
+    response = stock_service.get_orders(account_no="0001201435", token=token)
+except requests.HTTPError as exc:
+    print(exc.response.status_code, exc.response.json())
+```
+
+## Development
+
+```bash
+git clone https://github.com/nghialuffy/tcbs-api
+cd tcbs-api
+
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy tcbs_api
+uv build
+```
+
+## Releasing
+
+Publishing is automated by
+[`.github/workflows/publish.yml`](https://github.com/nghialuffy/tcbs-api/blob/main/.github/workflows/publish.yml)
+using PyPI [trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC), so no
+API token is stored in this repository.
+
+### One-time setup
+
+On PyPI, go to **Account → Publishing → Add a pending publisher** and fill in:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `tcbs-api` |
+| Owner | `nghialuffy` |
+| Repository name | `tcbs-api` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+The environment name must match the `environment:` key in the publish job.
+
+### Cutting a release
+
+`tcbs_api/__init__.py` is the single source of truth for the version — `pyproject.toml`
+reads it dynamically, so there is nothing to keep in sync.
+
+1. Bump `__version__` in `tcbs_api/__init__.py` and add a matching `CHANGELOG.md` entry.
+2. Commit, then tag and push:
+   ```bash
+   git commit -am "release: vX.Y.Z"
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   git push origin main --follow-tags
+   ```
+3. Publish a GitHub Release for that tag. The workflow builds the sdist and wheel, runs
+   `twine check --strict`, verifies the built version matches the tag, and uploads to
+   PyPI.
+
+Because `tcbs-api` does not exist on PyPI yet, the first release needs a **pending**
+publisher as shown above. Once the project exists, the same entry is managed from the
+project's own settings instead.
+
+### Rehearsing on TestPyPI
+
+Run the same commands against TestPyPI before a real release:
+
+```bash
+uv build
+uv publish --publish-url https://test.pypi.org/legacy/ --token pypi-<testpypi-token>
+```
+
+### Notes
+
+- A published version can **never** be re-uploaded, so bump `__version__` for every
+  attempt — including failed ones. The tag/version guard in the workflow catches the
+  common slip of tagging a version you forgot to bump.
+- Keep the tag (with a `v` prefix) in sync with `__version__` (no `v`); the workflow
+  strips the prefix before comparing.
+
+## Known limitations
+
+### Derivative payloads are not typed
+
+The derivative endpoints return a `DerivativeResponse` envelope, but its generic `data`
+field stays a raw `dict`. `dataclasses_json` cannot resolve the `Generic[T]` parameter —
+it warns `Unknown type ~T at DerivativeResponse.data` — so the declared element type is
+never applied:
+
+```python
+from tcbs_api.dto.derivative_dto import TotalCashDerivativeResponse
+from tcbs_api.service.derivative import derivative as derivative_service
+
+envelope = derivative_service.get_total_cash_derivative(account_id, sub_account_id, "0", token)
+type(envelope)        # <class 'tcbs_api.dto.derivative_dto.derivative_dto.DerivativeResponse'>
+type(envelope.data)   # <class 'dict'>
+
+# Decode the payload yourself to get the typed object:
+cash = TotalCashDerivativeResponse.from_dict(envelope.data, infer_missing=True)
+```
+
+### `Optional[...]` fields have no defaults
+
+Many DTO fields are annotated `Optional[...]` but are not given a `= None` default, so
+`dataclasses_json`'s `from_dict`/`from_json` raise `KeyError` when a field is missing from
+the payload. Pass `infer_missing=True` (as above) to tolerate missing keys. Decoding in
+the library itself is unaffected, because the non-derivative endpoints use `dacite` with
+`Config(strict=False)`.
+
+### Operational notes
+
+- The token endpoint is limited to **10 requests per day** by TCBS; cache the token.
+- The library performs no retries, rate limiting, or token refresh — callers own that
+  policy.
+- Requests are issued synchronously with `requests`. There is no async client.
+
+## License
+
+MIT — see [LICENSE](https://github.com/nghialuffy/tcbs-api/blob/main/LICENSE).