tcbs-api 0.0.1__py3-none-any.whl

tcbs_api/__init__.py

@@ -0,0 +1,8 @@
+"""Python client library for the TCBS Open API.
+
+See the official API documentation at https://developers.tcbs.com.vn/.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.0.1"

tcbs_api/dto/__init__.py

@@ -0,0 +1,18 @@
+"""Request and response models, grouped by API domain.
+
+Every model is a plain ``dataclass`` whose field names match the JSON keys TCBS sends and
+expects, keeping their original camelCase — ``OrderInfo.orderID`` and
+``TotalCashDerivativeResponse.cashavaiwithdraw`` are spelled the way the API spells them
+rather than the way Python normally would. That keeps the mapping between code and API
+payloads obvious, and is why responses can be decoded straight onto these classes.
+
+Sub-packages:
+
+* :mod:`tcbs_api.dto.account` — profile information for a sub-account
+* :mod:`tcbs_api.dto.auth` — the JWT token response
+* :mod:`tcbs_api.dto.money` — cash transfers, margin deposit and withdrawal
+* :mod:`tcbs_api.dto.stock_normal` — stock orders, purchasing power, assets and cash
+* :mod:`tcbs_api.dto.derivative_dto` — derivatives cash, positions, orders and market data
+"""
+
+from __future__ import annotations

tcbs_api/dto/account/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+from .account_information_response import *

tcbs_api/dto/account/account_information_response.py

@@ -0,0 +1,79 @@
+"""Profile information for a sub-account, as returned by ``get_subaccount_info``.
+
+``BasicInfo``, ``PersonalInfo``, ``BankAccount`` and ``BankSubAccount`` are only populated
+when they are named in the endpoint's ``fields`` query parameter; the others come back as
+``None``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class BasicInfo:
+    tcbsId: str | None = None
+    code105C: str | None = None
+    status: str | None = None
+    type: str | None = None
+    depository: bool | None = None
+
+
+@dataclass
+class PersonalInfo:
+    fullName: str | None = None
+    fullNameNoAccent: str | None = None
+    firstName: str | None = None
+    lastName: str | None = None
+    email: str | None = None
+    phoneNumber: str | None = None
+    gender: str | None = None
+    birthday: str | None = None
+    contactAddress: str | None = None
+    permanentAddress: str | None = None
+    nationality: str | None = None
+    nationalityName: str | None = None
+    taxIdNumber: str | None = None
+    acronym: str | None = None
+    createdDate: str | None = None
+    updatedDate: str | None = None
+    flowOpenAccount: str | None = None
+    avatarUrl: str | None = None
+    businessType: str | None = None
+    ppBusinessType: str | None = None
+    ppBusinessField: str | None = None
+    ppBusinessTypeName: str | None = None
+    ppBusinessFieldName: str | None = None
+    identityCard: dict | None = None
+
+
+@dataclass
+class BankAccount:
+    accountNo: str | None = None
+    accountName: str | None = None
+    accountNameNoAccent: str | None = None
+    bankCode: str | None = None
+    bankName: str | None = None
+    branchCode: str | None = None
+    bankType: str | None = None
+    bankSys: str | None = None
+    authorized: bool | None = None
+    bankAccountType: str | None = None
+
+
+@dataclass
+class BankSubAccount:
+    accountNo: str | None = None
+    accountName: str | None = None
+    accountType: str | None = None
+    accountTypeName: str | None = None
+    status: str | None = None
+    isDefault: str | None = None
+
+
+@dataclass
+class AccountInformationResponse:
+    basicInfo: BasicInfo | None = None
+    personalInfo: PersonalInfo | None = None
+    bankAccounts: list[BankAccount] | None = field(default_factory=list)
+    bankSubAccounts: list[BankSubAccount] | None = field(default_factory=list)

tcbs_api/dto/auth/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+from .token_response_dto import *

tcbs_api/dto/auth/token_response_dto.py

@@ -0,0 +1,10 @@
+"""The JWT token response returned by ``get_token``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TokenResponseDto:
+    token: str | None = None

tcbs_api/dto/derivative_dto/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+from .derivative_dto import *

tcbs_api/dto/derivative_dto/derivative_dto.py

@@ -0,0 +1,378 @@
+"""Derivatives models, including the envelope that every derivative endpoint returns.
+
+``DerivativeResponse[T]`` is that envelope — ``{cmd, rc, rs, oID, data}``. The response
+models used as its ``T`` carry ``@dataclass_json`` so they can be decoded with
+``from_json()``; the remaining classes are request bodies, plus two market-information
+models that are decoded with ``dacite`` like the rest of the library.
+
+Beware that a field annotated ``Optional[...]`` is not optional at decode time unless it
+also has a ``= None`` default — ``from_dict``/``from_json`` raise ``KeyError`` for a field
+the API omits. See the README's known limitations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from dataclasses_json import dataclass_json
+
+T = TypeVar("T")
+
+
+@dataclass_json
+@dataclass
+class DerivativeResponse(Generic[T]):
+    """The ``{cmd, rc, rs, oID, data}`` envelope every derivative endpoint returns.
+
+    ``T`` is the response model for the endpoint. It is not applied at runtime — see this
+    module's docstring and the README's known limitations.
+    """
+
+    cmd: str
+    rc: str
+    rs: str
+    oID: str
+    data: T
+
+
+@dataclass_json
+@dataclass
+class TotalCashDerivativeResponse:
+    """Derivatives cash, margin and collateral summary."""
+
+    cash: float | None
+    stock: float | None
+    collateral: float | None
+    type: str | None
+    net: float | None
+    tyle: float | None
+    im: float | None
+    vm: float | None
+    dm: float | None
+    mr: float | None
+    avaiCash: float | None
+    avaiColla: float | None
+    vmunpay: float | None
+    info: str | None
+    color: str | None
+    vm_eod: float | None
+    others: float | None
+    tax: float | None
+    feeCTCK: float | None
+    feeHNX: float | None
+    cashWithdraw: float | None
+    tienbosung: float | None
+    cashavaiwithdraw: float | None
+    assets: float | None
+    nav: float | None
+    cashOut: float | None
+    unrelizeVM: float | None
+    feePos: float | None
+    feeMan: float | None
+    product: str | None
+    status: str | None
+    debt: float | None
+    w1: float | None
+    w2: float | None
+    limit: float | None
+    package: str | None
+
+
+@dataclass_json
+@dataclass
+class AssetPositionCloseDerivativeResponse:
+    symbol: str
+    side: str
+    openPrice: float
+    closePrice: float
+    closePosition: str
+    fee: float
+    tax: float
+    closeVM: float
+    unrealize: float
+    closePC: float
+    time: str
+
+
+@dataclass_json
+@dataclass
+class AssetPositionOpenDerivativeResponse:
+    symbol: str
+    im: str
+    deliver: str
+    receive: str
+    net: int
+    side: str
+    account: str
+    wasp: float
+    wapb: float
+    lastPrice: float
+    imValue: float
+    vmValue: float
+    mrValue: float
+    duedate: str
+    netoffvol: int
+    avg_remain: float
+    vm_remain: float
+    pc_remain: str
+    stoploss: str | None
+    takeprofit: str | None
+
+
+@dataclass_json
+@dataclass
+class ListOrderNormalDerivativeResponse:
+    orderNo: str
+    pk_orderNo: str
+    orderTime: str
+    accountCode: str
+    side: str
+    symbol: str
+    volume: int
+    showPrice: float
+    matchVolume: int
+    matchPriceBQ: float
+    status: str
+    orderStatus: str
+    channel: str
+    group: str
+    cancelTime: str | None
+    isCancel: bool
+    isAmend: bool
+    info: str | None
+    maxPrice: float | None
+    matchValue: float | None
+    quote: str | None
+    autoType: str | None
+    product: str | None
+    orderType: str | None
+    source: str | None
+
+
+@dataclass_json
+@dataclass
+class ListOrderConditionDerivativeResponse:
+    orderNo: str
+    groupOrder: str
+    pk_orderNo: str
+    accountCode: str
+    side: str
+    symbol: str
+    showPrice: float
+    volume: int
+    condition: str
+    result: str
+    active_time: str
+    send_time: str
+    cancel_time: str | None
+    group: str
+    channel: str
+    maxPrice: float | None
+    soPrice: float
+    orderType: str
+    from_time: str
+    exp_time: str
+    status: str
+    details: str
+    notes: str
+
+
+@dataclass_json
+@dataclass
+class OrderNormalDerivativeResponse:
+    symbol: str
+    status: str
+    msg_type: str
+    showPrice: float
+    orderTime: str
+    type: str
+    accountCode: str
+    orderNo: str
+    matchVolume: float
+    side: str
+    volume: float
+    pk_orderNo: str
+    channel: str
+    group: str
+    quote: str
+    accType: str | None = None
+    shareStatus: str | None = None
+    market: str | None = None
+    refID: str | None = None
+    autoType: str | None = None
+    product: str | None = None
+
+
+@dataclass
+class PlaceOrderDto:
+    accountId: str
+    subAccountId: str
+    side: str
+    symbol: str
+    price: float
+    volume: int
+    refId: str
+    orderType: str
+    advance: int | None = None
+    pin: str | None = None
+
+
+@dataclass
+class OrderConditionDerivativeRequestDTO:
+    subAccountId: str
+    accountId: str
+    side: str
+    symbol: str
+    price: float
+    volume: float
+    orderType: str
+    callbackPoint: float
+    activationPrice: float
+    soPrice: float
+    advance: str | None = None
+    refId: str | None = None
+    pin: str | None = None
+    type: str | None = None
+    cmd: str | None = None
+
+
+@dataclass_json
+@dataclass
+class OrderConditionDerivativeResponseDTO:
+    symbol: str
+    status: str
+    msg_type: str
+    showPrice: float
+    orderTime: str
+    type: str
+    accountCode: str
+    orderNo: int
+    matchVolume: float
+    side: str
+    volume: float
+    pk_orderNo: str
+    channel: str
+    group: str
+    quote: str
+    shareStatus: str | None = None
+    market: str | None = None
+    refID: str | None = None
+    accType: str | None = None
+    autoType: str | None = None
+    product: str | None = None
+
+
+@dataclass
+class EditOrderNormalDerivativeRequestDTO:
+    accountId: str
+    subAccountId: str
+    orderNo: str
+    refId: str
+    nvol: float
+    nprice: float
+
+
+@dataclass_json
+@dataclass
+class EditOrderNormalDerivativeResponseDTO:
+    orderNo: str
+    msg_type: str
+    status: str
+    pk_orderNo: str
+    volume: float
+    showPrice: float
+
+
+@dataclass
+class EditOrderConditionDerivativeRequestDTO:
+    accountId: str
+    pkOrderNo: str
+    type: str
+    refId: str
+    soPrice: float
+    cmd: str | None = None
+
+
+@dataclass_json
+@dataclass
+class EditOrderConditionDerivativeResponseDTO:
+    showPrice: str
+    price: str
+    volume: str
+    pkOrderNo: str
+    notes: str
+
+
+@dataclass
+class CancelOrderNormalDerivativeRequestDTO:
+    accountId: str
+    orderNo: str
+    cmd: str | None = None
+    pin: str | None = None
+    refId: str | None = None
+
+
+@dataclass_json
+@dataclass
+class CancelOrderNormalDerivativeResponseDTO:
+    orderNo: str
+    msg_type: str | None = None
+    status: str | None = None
+    pk_orderNo: str | None = None
+    cancelTime: str | None = None
+
+
+@dataclass
+class CancelOrderConditionDerivativeRequestDTO:
+    accountId: str
+    orderNo: str
+    subAccountId: str | None = None
+
+
+@dataclass_json
+@dataclass
+class CancelOrderConditionDerivativeResponseDTO:
+    """Intentionally empty: for this operation TCBS reports only the surrounding envelope."""
+
+    pass
+
+
+@dataclass
+class MarketInformationDerivativeResponseDTO:
+    symbol: str | None = None
+    ceilPrice: float | None = None
+    floorPrice: float | None = None
+    refPrice: float | None = None
+    bidPrice01: float | None = None
+    bidPrice02: float | None = None
+    bidPrice03: float | None = None
+    bidQtty01: float | None = None
+    bidQtty02: float | None = None
+    bidQtty03: float | None = None
+    offerPrice01: float | None = None
+    offerPrice02: float | None = None
+    offerPrice03: float | None = None
+    offerQtty01: float | None = None
+    offerQtty02: float | None = None
+    offerQtty03: float | None = None
+    matchPrice: float | None = None
+    matchQtty: float | None = None
+    change: float | None = None
+    changePercent: float | None = None
+    open: float | None = None
+    high: float | None = None
+    low: float | None = None
+    totalVol: float | None = None
+    openVol: float | None = None
+    buyForeignQtty: float | None = None
+    sellForeignQtty: float | None = None
+    expiryDate: str | None = None
+    avg: float | None = None
+
+
+@dataclass
+class MarketInformationResponseDTO:
+    """Price board for every derivatives symbol."""
+
+    data: list[MarketInformationDerivativeResponseDTO]

tcbs_api/dto/money/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+from .money import *

tcbs_api/dto/money/money.py

@@ -0,0 +1,62 @@
+"""Cash-transfer and margin deposit/withdrawal models.
+
+The ``*RequestDTO`` models are the bodies sent to TCBS, serialized with
+:func:`dataclasses.asdict`; the ``*ResponseDTO`` models are what comes back.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TransferBetweenSubaccountRequestDTO:
+    sourceAccountNumber: str
+    destinationAccountNumber: str
+    amount: float
+    description: str
+
+
+@dataclass
+class TransferBetweenSubaccountResponseDTO:
+    code: str
+    message: str
+
+
+@dataclass
+class WithdrawalDerivativeRequestDTO:
+    accountId: str
+    subAccountId: str
+    amount: float
+    paymentContent: str
+
+
+@dataclass
+class WithdrawalDerivativeResponseDTO:
+    cmd: str
+    rc: str
+    rs: str
+    oID: str
+    data: list
+
+
+@dataclass
+class DepositDerivativeRequestDTO:
+    accountId: str
+    subAccountId: str
+    amount: float
+    paymentContent: str
+
+
+@dataclass
+class DepositDerivativeResponseDTO:
+    transactionId: str
+
+
+@dataclass
+class DepositDerivativeMarginResponseDTO:
+    cmd: str
+    rc: str
+    rs: str
+    oID: str
+    data: list[DepositDerivativeResponseDTO]

tcbs_api/dto/stock_normal/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+from .stock_normal_dto import *