unofficial_tabdeal_api¶

A Package to communicate with the Tabdeal platform

copyright:

2025-present MohsenHNSJ

license:

MIT, see LICENSE for more details

Submodules¶

Classes¶

`AuthorizationClass`	This is the class storing methods related to Authorization.
`BaseClass`	This is the base class, stores GET and POST functions.
`MarginClass`	This is the class storing methods related to Margin trading.
`OrderClass`	This is the class storing methods related to Ordering.
`TabdealClient`	a client class to communicate with Tabdeal platform.
`WalletClass`	This is the class storing methods related to account wallet.

Package Contents¶

class unofficial_tabdeal_api.AuthorizationClass(*, user_hash, authorization_key, _is_test=False)¶

Bases: unofficial_tabdeal_api.base.BaseClass

This is the class storing methods related to Authorization.

Parameters:

user_hash (str)
authorization_key (str)
_is_test (bool)

async is_authorization_key_valid()¶

Checks the validity of provided authorization key.

If the key is invalid or expired, return False

If the key is working, return True

Returns:: True or False based on the result
Return type:: bool

class unofficial_tabdeal_api.BaseClass(*, user_hash, authorization_key, _is_test=False)¶

This is the base class, stores GET and POST functions.

Parameters:

user_hash (str)
authorization_key (str)
_is_test (bool)

_client_session: aiohttp.ClientSession¶

_logger: logging.Logger¶

async close()¶

Close the aiohttp client session.

Return type:: None

async __aenter__()¶

Enter the async context manager.

Return type:: Self

async __aexit__(exc_type, exc, tb)¶

Exit the async context manager and close the session.

Parameters:

exc_type (type[BaseException] | None)
exc (BaseException | None)
tb (types.TracebackType | None)

Return type:

None

async _get_data_from_server(*, connection_url, queries=None)¶

Gets data from specified url and returns the parsed json back.

Parameters:

connection_url (str) – Url of the server to get data from
queries (dict[str, Any] | None, optional) – a Dictionary of queries. Defaults to None.

Returns:

a Dictionary or a list of dictionaries

Return type:

dict[str, Any] | list[dict[str, Any]]

async _post_data_to_server(*, connection_url, data)¶

Posts data to specified url and returns the result of request.

Parameters:

connection_url (str) – Url of server to post data to
data (str) – Stringed json data to send to server

Returns:

A Dictionary or a list of dictionaries.

Return type:

dict[str, Any] | list[dict[str, Any]]

async _check_response(response)¶

Check the server response and raise appropriate exception in case of an error.

Parameters:

response (ClientResponse) – Response from server

Raises:

AuthorizationError – Raised when the authorization key is invalid or expired
Error – Raised for all other errors

Return type:

None

_raise_specific_error(status_code, server_response)¶

Raise a specific exception based on the server response content.

Parameters:

status_code (int) – The status code of the response
server_response (str) – The content of the response

Raises:

exc_class – The specific exception class to raise
RequestError – Raised for all other errors

Return type:

None

class unofficial_tabdeal_api.MarginClass(*, user_hash, authorization_key, _is_test=False)¶

Bases: unofficial_tabdeal_api.base.BaseClass

This is the class storing methods related to Margin trading.

Parameters:

user_hash (str)
authorization_key (str)
_is_test (bool)

async get_isolated_symbol_details(isolated_symbol)¶

Gets the full details of an isolated symbol from server and returns it as a dictionary.

Parameters:

isolated_symbol (str) – Isolated symbol of margin asset.
example – BTCUSDT, MANAUSDT, BOMEUSDT, …

Returns:

A model containing isolated symbol details

Return type:

IsolatedSymbolDetailsModel

Raises:

TypeError – If the response is not a dictionary or the response can’t be validated.

async get_margin_all_open_orders()¶

Gets all the open margin orders from server and returns it as a list of dictionaries.

Returns:: a List of MarginOpenOrderModel items
Return type:: list[MarginOpenOrderModel]
Raises:: TypeError – If the response is not a list.

async get_margin_asset_id(isolated_symbol)¶

Gets the ID of a margin asset from server and returns it as an integer.

Parameters:: isolated_symbol (str) – Isolated symbol of margin asset. example: BTCUSDT, MANAUSDT, BOMEUSDT, …
Returns:: Margin asset ID as integer
Return type:: int

async get_order_break_even_price(asset_id)¶

Gets the price point for an order which Tabdeal says it yields no profit and loss.

Parameters:: asset_id (int) – Margin asset ID got from get_asset_id() function
Returns:: The price as Decimal
Return type:: Decimal
Raises:: BreakEvenPriceNotFoundError – If no matching order is found.

async get_margin_pair_id(isolated_symbol)¶

Gets the pair ID for a margin asset from server and returns it as an integer.

Parameters:

isolated_symbol (str) – Isolated symbol of margin asset.
example – BTCUSDT, MANAUSDT, BOMEUSDT, …

Returns:

Margin pair ID as integer

Return type:

int

Raises:

TypeError – If the response is not a dictionary.

async get_margin_asset_balance(isolated_symbol)¶

Gets the margin asset balance in USDT from server and returns it as Decimal value.

Parameters:: isolated_symbol (str) – Isolated symbol of margin asset
Returns:: Asset balance in USDT as Decimal
Return type:: Decimal
Raises:: TypeError – If the response is not a dictionary.

async get_margin_asset_precision_requirements(isolated_symbol)¶

Gets the precision requirements of an asset from server and returns it as a tuple.

First return value is precision for volume. Second return value is precision for price.

Parameters:: isolated_symbol (str) – Isolated symbol of margin asset
Returns:: A Tuple containing precision requirements for (1)volume and (2)price
Return type:: tuple[int, int]
Raises:: TypeError – If the response is not a dictionary.

async is_margin_asset_trade_able(isolated_symbol)¶

Gets the trade-able status of requested margin asset from server.

Returns the status as boolean. If the asset is not found or not active for margin trading, returns False instead of raising an exception.

Parameters:: isolated_symbol (str) – Isolated symbol of margin asset
Returns:: Is margin asset trade-able?
Return type:: bool

async open_margin_order(order)¶

Opens a margin order.

Parameters:: order (MarginOrderModel) – margin order object containing order details
Raises:: TypeError – If the server response is not a dictionary or does not indicate success.
Returns:: Order ID of the opened order
Return type:: int

async set_sl_tp_for_margin_order(*, margin_asset_id, stop_loss_price, take_profit_price)¶

Sets the stop loss and take profit points.

Parameters:

margin_asset_id (int) – Margin Asset ID (7 digits or more)
stop_loss_price (Decimal) – Stop loss price
take_profit_price (Decimal) – Take profit price

Returns:

None

Return type:

None

async does_margin_asset_have_active_order(isolated_symbol)¶

Checks whether the margin asset has an active order or not.

Parameters:: isolated_symbol (str) – Isolated symbol of margin asset
Returns:: True if there is an active order, else False
Return type:: bool

async is_margin_order_filled(isolated_symbol)¶

Checks whether the isolated symbol’s order is filled or not.

Parameters:: isolated_symbol (str) – Isolated margin symbol
Raises:: MarginOrderNotFoundInActiveOrdersError – If the order is not found, we raise an exception
Returns:: Is margin order filled?
Return type:: bool

class unofficial_tabdeal_api.OrderClass(*, user_hash, authorization_key, _is_test=False)¶

Bases: unofficial_tabdeal_api.base.BaseClass

This is the class storing methods related to Ordering.

Parameters:

user_hash (str)
authorization_key (str)
_is_test (bool)

async get_orders_details_history(_max_history=500)¶

Gets the last 500(by default) orders details and returns them as a list.

Parameters:: _max_history (int, optional) – Max number of histories. Defaults to 500.
Raises:: TypeError – If the server responds incorrectly
Returns:: A List of dictionaries
Return type:: list[dict[str, Any]]

async get_order_state(order_id)¶

Gets the state of the requested order and returns it as an OrderState enum.

Parameters:: order_id (int) – ID of the trade order
Returns:: State of the order as enum
Return type:: OrderState

class unofficial_tabdeal_api.TabdealClient(*, user_hash, authorization_key, _is_test=False)¶

Bases: unofficial_tabdeal_api.authorization.AuthorizationClass, unofficial_tabdeal_api.margin.MarginClass, unofficial_tabdeal_api.wallet.WalletClass, unofficial_tabdeal_api.order.OrderClass

a client class to communicate with Tabdeal platform.

Parameters:

user_hash (str)
authorization_key (str)
_is_test (bool)

async _validate_trade_conditions(order)¶

Validate trade conditions for a margin order.

Parameters:: order (MarginOrderModel) – The margin order to validate.
Returns:: True if the trade conditions are valid, False otherwise.
Return type:: bool

async _open_order(order)¶

Open a margin order.

Parameters:: order (MarginOrderModel) – The margin order to open.
Returns:: None
Return type:: None

async _wait_for_order_fill(order)¶

Wait for the margin order to be filled.

Parameters:: order (MarginOrderModel) – The margin order to wait for.
Returns:: True if the order is filled, False otherwise.
Return type:: bool

async _setup_stop_loss_take_profit(order)¶

Setup stop loss and take profit for a margin order.

Parameters:: order (MarginOrderModel) – The margin order to setup SL/TP for.
Returns:: The margin asset ID.
Return type:: int

async _wait_for_order_close(margin_asset_id)¶

Wait for the margin order to close.

Parameters:: margin_asset_id (int) – The ID of the margin asset to wait for.
Return type:: None

async _withdraw_balance_if_requested(order)¶

Withdraw balance from margin asset to wallet if requested.

Parameters:: order (MarginOrderModel) – The margin order containing the asset symbol.
Return type:: None

async trade_margin_order(*, order, withdraw_balance_after_trade)¶

Trade a margin order.

Parameters:

order (MarginOrderModel) – MarginOrderModel object containing order details.
withdraw_balance_after_trade (bool) – Flag indicating whether to withdraw balance after trade.

Returns:

Whether the trade was successful or not.

Return type:

bool

class unofficial_tabdeal_api.WalletClass(*, user_hash, authorization_key, _is_test=False)¶

Bases: unofficial_tabdeal_api.base.BaseClass

This is the class storing methods related to account wallet.

Parameters:

user_hash (str)
authorization_key (str)
_is_test (bool)

async get_wallet_usdt_balance()¶

Gets the balance of wallet in USDT and returns it as Decimal.

Returns:: Wallet USDT balance in Decimal
Return type:: Decimal

async transfer_usdt_from_wallet_to_margin_asset(*, transfer_amount, isolated_symbol)¶

Transfers USDT from wallet to margin asset.

Parameters:

transfer_amount (Decimal) – Amount of USDT to transfer
isolated_symbol (str) – Isolated symbol to transfer USDT to

Return type:

None

async transfer_usdt_from_margin_asset_to_wallet(*, transfer_amount, isolated_symbol)¶

Transfers USDT from margin asset to wallet.

Parameters:

transfer_amount (Decimal) – Amount of USDT to transfer
isolated_symbol (str) – Isolated symbol to transfer USDT from

Return type:

None