Wallet API Functions¶

Low-level functions for signed account endpoints (balances, snapshots, account trades, margin). Used internally by the Wallet class. Credentials are managed by panzer (~/.panzer_creds); see Secrets Module.

Functions:

`convert_str_date_to_ms`(date, time_zone)	Converts dates strings formatted as "2022-05-11 06:45:42" to timestamp in milliseconds.
`daily_account_snapshot`(account_type, ...[, ...])	The query time period must be inside the previous 30 days.
`assets_convertible_dust`(decimal_mode[, confirm])	Assets dust that can be converted to BNB.
`get_fills_price`(original_order_dict, ...)	Obtain averaged price from order API response or claims last trade.
`get_fills_qty`(original_order_dict, margin, ...)	Extracts order quantity from an order response or checks a trade from API.
`get_spot_trades_list`(symbol, decimal_mode[, ...])	Get trades for a specific account and symbol.
`get_margin_trades_list`(symbol, decimal_mode)	Get margin trades for a specific account and symbol.
`get_spot_account_info`(decimal_mode[, recvWindow])	Get current account information.
`get_spot_free_balances`(decimal_mode[, data_dic])	Parses available balances from account info.
`get_spot_locked_balances`(decimal_mode[, ...])	Parses locked in order balances from account info.
`get_coins_with_balance`(decimal_mode)	Get the non-zero balances of an account, free or locked ones.
`get_spot_balances_df`(decimal_mode[, ...])	Create a dataframe with the free or blocked amounts of the spot wallet.
`get_spot_balances_total_value`(decimal_mode)	Returns total value expressed in a quote coin.
`get_margin_account_details`(decimal_mode)	Query Cross Margin Account Details (USER_DATA)
`get_margin_balances`(decimal_mode)	Collects balances in the margin account that are not null.
`get_margin_free_balances`(decimal_mode[, ...])	Just returns free existing balances.
`get_margin_locked_balances`(decimal_mode[, ...])	Just returns locked existing balances.
`get_margin_borrowed_balances`(decimal_mode[, ...])	Just returns borrowed existing balances.
`get_margin_interest_balances`(decimal_mode[, ...])	Just returns interest existing balances.
`get_margin_netAsset_balances`(decimal_mode[, ...])	Just returns netAsset existing balances.
`get_margin_balances_total_value`(decimal_mode)	Returns total value expressed in a quote coin.

convert_str_date_to_ms(date: str | int, time_zone: str)[source]¶

Converts dates strings formatted as “2022-05-11 06:45:42” to timestamp in milliseconds. If timestamp passed it returns the timestamp.

Parameters:

date (str or int) – Date to check format.
time_zone – A time zone like ‘Europe/Madrid’

Return int:

Milliseconds of timestamp.

daily_account_snapshot(account_type: str, decimal_mode: bool, startTime: int | str = None, endTime: int | str = None, limit=30, time_zone=None) → DataFrame[source]¶

The query time period must be inside the previous 30 days. Support query within the last month, one month only. If startTime and endTime not sent, return records of the last days by default.

Weight(IP): 2400

Parameters:

account_type (str) – SPOT or MARGIN (cross)
decimal_mode (bool) – Fixes Decimal return type and operative. :param int limit: Days limit. Default 30.
startTime (int or str) – Can be integer timestamp in milliseconds or formatted string: 2022-05-11 06:45:42
endTime (int or str) – Can be integer timestamp in milliseconds or formatted string: 2022-05-11 06:45:42
time_zone (str) – A time zone to parse index like ‘Europe/Madrid’

Return pd.DataFrame:

Pandas DataFrame

assets_convertible_dust(decimal_mode: bool, confirm: bool = False) → dict | None[source]¶

Assets dust that can be converted to BNB. Weight(IP): 1

Parameters:

decimal_mode (bool) – It flags to work in decimal mode.
confirm (bool) – Must be True to execute. Prevents accidental wallet modifications.

Return dict:

A dictionary.

{
     "details": [
         {
             "asset": "ADA",
             "assetFullName": "ADA",
             "amountFree": "6.21",   //Convertible amount
             "toBTC": "0.00016848",  //BTC amount
             "toBNB": "0.01777302",  //BNB amount（Not deducted commission fee）
             "toBNBOffExchange": "0.01741756", //BNB amount（Deducted commission fee）
             "exchange": "0.00035546" //Commission fee
         }
     ],
     "totalTransferBtc": "0.00016848",
     "totalTransferBNB": "0.01777302",
     "dribbletPercentage": "0.02"     //Commission fee
 }

get_fills_price(original_order_dict: dict, isBuyer: bool, margin: bool, test_mode: bool, operation_time: int, decimal_mode: bool) → float[source]¶

Obtain averaged price from order API response or claims last trade.

Parameters:

original_order_dict (dict) – API order dict response.
isBuyer (bool) – Sets if was a buyer order to filter for wanted order.
margin (bool) – Sets margin order if it is to claim.
test_mode (bool) – Set if test mode is on.
operation_time (int) – Time limit of operation to analyze.
decimal_mode (bool) – Fixes Decimal return type and operative. :return float: Price averaged.

Example of not totally done order:

{'symbol': 'ACMBUSD',
'orderId': 53255492,
'orderListId': -1,
'clientOrderId': 'DUHlcCqIX2OO298XoAbvEB',
'transactTime': 1660332903950,
'price': 4.158,
'origQty': 21.1,
'executedQty': 0.0,
'cummulativeQuoteQty': 0.0,
'status': 'NEW',
'timeInForce': 'GTC',
'type': 'LIMIT',
'side': 'BUY',
'fills': []}

Example of full SPOT response:

{
  "symbol": "BTCUSDT",
  "orderId": 28,
  "orderListId": -1, //Unless OCO, value will be -1
  "clientOrderId": "6gCrw2kRUFF9CvJDWP16IP",
  "transactTime": 1507725176595,
  "price": "0.00000000",
  "origQty": "10.00000000",
  "executedQty": "10.00000000",
  "cummulativeQuoteQty": "10.00000000",
  "status": "FILLED",
  "timeInForce": "GTC",
  "type": "MARKET",
  "side": "SELL",
  "strategyId": 1,               // This is only visible if the field was populated on order placement.
  "strategyType": 1000000        // This is only visible if the field was populated on order placement.
  "fills": [
    {
      "price": "4000.00000000",
      "qty": "1.00000000",
      "commission": "4.00000000",
      "commissionAsset": "USDT",
      "tradeId": 56
    },
    {
      "price": "3999.00000000",
      "qty": "5.00000000",
      "commission": "19.99500000",
      "commissionAsset": "USDT",
      "tradeId": 57
    },
    {
      "price": "3998.00000000",
      "qty": "2.00000000",
      "commission": "7.99600000",
      "commissionAsset": "USDT",
      "tradeId": 58
    },
    {
      "price": "3997.00000000",
      "qty": "1.00000000",
      "commission": "3.99700000",
      "commissionAsset": "USDT",
      "tradeId": 59
    },
    {
      "price": "3995.00000000",
      "qty": "1.00000000",
      "commission": "3.99500000",
      "commissionAsset": "USDT",
      "tradeId": 60
    }
  ]
}

Example of FULL MARGIN RESPONSE:

{
  "symbol": "BTCUSDT",
  "orderId": 28,
  "clientOrderId": "6gCrw2kRUFF9CvJDWP16IP",
  "transactTime": 1507725176595,
  "price": "1.00000000",
  "origQty": "10.00000000",
  "executedQty": "10.00000000",
  "cummulativeQuoteQty": "10.00000000",
  "status": "FILLED",
  "timeInForce": "GTC",
  "type": "MARKET",
  "side": "SELL",
  "marginBuyBorrowAmount": 5,       // will not return if no margin trade happens
  "marginBuyBorrowAsset": "BTC",    // will not return if no margin trade happens
  "isIsolated": true,       // if isolated margin
  "fills": [
    {
      "price": "4000.00000000",
      "qty": "1.00000000",
      "commission": "4.00000000",
      "commissionAsset": "USDT"
    },
    {
      "price": "3999.00000000",
      "qty": "5.00000000",
      "commission": "19.99500000",
      "commissionAsset": "USDT"
    },
    {
      "price": "3998.00000000",
      "qty": "2.00000000",
      "commission": "7.99600000",
      "commissionAsset": "USDT"
    },
    {
      "price": "3997.00000000",
      "qty": "1.00000000",
      "commission": "3.99700000",
      "commissionAsset": "USDT"
    },
    {
      "price": "3995.00000000",
      "qty": "1.00000000",
      "commission": "3.99500000",
      "commissionAsset": "USDT"
    }
  ]
}

STOP LIMIT EXAMPLE requested order response:

{'symbol': 'CHZBUSD',
 'orderId': 212320642,
 'orderListId': 72689217,
 'clientOrderId': 'FLc7AHuuZCpChiH99eHtZh',
 'price': 0.2139,
 'origQty': 224.0,
 'executedQty': 224.0,
 'cummulativeQuoteQty': 47.9584,
 'status': 'FILLED',
 'timeInForce': 'GTC',
 'type': 'STOP_LOSS_LIMIT',
 'side': 'SELL',
 'stopPrice': 0.2141,
 'icebergQty': '0.00000000',
 'time': 1661203865507,
 'updateTime': 1661203966780,
 'isWorking': True,
 'origQuoteOrderQty': 0.0},

get_fills_qty(original_order_dict: dict, margin: bool, isBuyer: bool, operation_time: int, decimal_mode: bool) → float | Decimal[source]¶

Extracts order quantity from an order response or checks a trade from API.

Parameters:

original_order_dict (dict) – A putting order response from API dict. :param bool margin: Checks if margin or not.
isBuyer (bool) – Sets if buy or sell side.
operation_time (int) – A limit old timestamp to verify existence of order.
decimal_mode (bool) – Sets Decimal operating mode.

Return float or decimal.Decimal:

Returns the needed value.

get_spot_trades_list(symbol: str, decimal_mode: bool, limit: int = 1000, orderId: int = None, startTime: int = None, endTime: int = None, fromId: int = None, recvWindow: int = 10000) → list[source]¶

Get trades for a specific account and symbol.

Weight(IP): 10

Parameters:

symbol (str) – Symbol’s trades.
decimal_mode (bool) – Fixes Decimal return type and operative. :param int limit: Default 500; max 1000.
fromId – TradeId to fetch from. Default gets most recent trades. If fromId is set, it will get id >= that fromId. Otherwise, most recent trades are returned.
endTime (int) – Optional.
startTime (int) – Optional.
orderId (int) – This can only be used in combination with symbol.
recvWindow (int) – The value cannot be greater than 60000

Return list:

A list.

Example:

[
   {
       "symbol": "BNBBTC",
       "id": 28457,
       "orderId": 100234,
       "orderListId": -1, //Unless OCO, the value will always be -1
       "price": "4.00000100",
       "qty": "12.00000000",
       "quoteQty": "48.000012",
       "commission": "10.10000000",
       "commissionAsset": "BNB",
       "time": 1499865549590,
       "isBuyer": true,
       "isMaker": false,
       "isBestMatch": true
     }
  ]

get_margin_trades_list(symbol: str, decimal_mode: bool, isIsolated: bool = False, limit: int = 1000, orderId: int = None, startTime: int = None, endTime: int = None, fromId: int = None, recvWindow: int = 10000) → list[source]¶

Get margin trades for a specific account and symbol.

If fromId is set, it will get trades >= that fromId. Otherwise most recent trades are returned.

Weight(IP): 10

Parameters:

symbol (str) – Symbol’s trades.
decimal_mode (bool) – Fixes Decimal return type and operative. :param bool isIsolated: Sets for getting isolated or not isolated trades. Default is false.
limit (int) – Default 500; max 1000.
fromId – TradeId to fetch from. Default gets most recent trades. If fromId is set, it will get id >= that fromId. Otherwise, most recent trades are returned.
endTime (int) – Optional.
startTime (int) – Optional.
orderId (int) – This can only be used in combination with symbol.
recvWindow (int) – The value cannot be greater than 60000

Return list:

A list.

Example:

 [
    {
        "commission": "0.00006000",
        "commissionAsset": "BTC",
        "id": 34,
        "isBestMatch": true,
        "isBuyer": false,
        "isMaker": false,
        "orderId": 39324,
        "price": "0.02000000",
        "qty": "3.00000000",
        "symbol": "BNBBTC",
        "isIsolated": false,
        "time": 1561973357171
    }
]

get_spot_account_info(decimal_mode: bool, recvWindow: int = 10000) → dict[source]¶

Get current account information.

Weight(IP): 10

Parameters:: decimal_mode (bool) – Fixes Decimal return type and operative. :param int recvWindow: The value cannot be greater than 60000
Return dict:: A dictionary with data.

Example:

{
   "makerCommission": 15,
   "takerCommission": 15,
   "buyerCommission": 0,
   "sellerCommission": 0,
   "canTrade": true,
   "canWithdraw": true,
   "canDeposit": true,
   "updateTime": 123456789,
   "accountType": "SPOT",
   "balances": [
     {"asset": "BTC", "free": "4723846.89208129","locked": "0.00000000"},
     {"asset": "LTC","free": "4763368.68006011","locked": "0.00000000"}
   ],
   "permissions": ["SPOT"]
}

get_spot_free_balances(decimal_mode: bool, data_dic: dict = None) → dict[source]¶

Parses available balances from account info.

Parameters:

data_dic (dict) – If available, account info can be passed as data_dic parameter to avoid API calling.
decimal_mode (bool) – Fixes Decimal return type and operative. :return dict: Free balances.

get_spot_locked_balances(decimal_mode: bool, data_dic: dict = None) → dict[source]¶

Parses locked in order balances from account info.

Parameters:: decimal_mode (bool) – Fixes Decimal return type and operative. :param dict data_dic: If available, account info can be passed as data_dic parameter to avoid API calling.
Return dict:: Locked balances.

get_coins_with_balance(decimal_mode: bool) → list[source]¶

Get the non-zero balances of an account, free or locked ones. Useful getting wallet value.

Parameters:: decimal_mode (bool) – Fixes Decimal return type and operative. :return list:

get_spot_balances_df(decimal_mode: bool, filter_empty: bool = True) → DataFrame[source]¶

Create a dataframe with the free or blocked amounts of the spot wallet. The index is the assets list.

Example:

from binpan.api.wallet_api import get_spot_balances_df

df = get_spot_balances_df(decimal_mode=False)

print(df)

            free      locked
     asset
     BNB    0.128359     0.0
     BUSD   0.000001     0.0

Parameters:: decimal_mode (bool) – Fixes Decimal return type and operative. :param bool filter_empty: Discards empty quantities.
Return pd.DataFrame:: A dataframe with assets locked or free.

get_spot_balances_total_value(decimal_mode: bool, balances_df: DataFrame = None, convert_to: str = 'BUSD') → float[source]¶

Returns total value expressed in a quote coin. Counts free and locked assets.

Parameters:

decimal_mode (bool) – Fixes Decimal return type and operative. :param pd.DataFrame balances_df: A BinPan balances dataframe.
convert_to (str) – A Binance coin.

Return float:

Total quantity expressed in quote.

get_margin_account_details(decimal_mode: bool) → dict[source]¶

Query Cross Margin Account Details (USER_DATA)

GET /sapi/v1/margin/account (HMAC SHA256)

Weight(IP): 10

Parameters:: decimal_mode (bool) – Fixes Decimal return type and operative.

Response:

{
       "borrowEnabled": true,
       "marginLevel": "11.64405625",
       "totalAssetOfBtc": "6.82728457",
       "totalLiabilityOfBtc": "0.58633215",
       "totalNetAssetOfBtc": "6.24095242",
       "tradeEnabled": true,
       "transferEnabled": true,
       "userAssets": [
           {
               "asset": "BTC",
               "borrowed": "0.00000000",
               "free": "0.00499500",
               "interest": "0.00000000",
               "locked": "0.00000000",
               "netAsset": "0.00499500"
           },
           {
               "asset": "BNB",
               "borrowed": "201.66666672",
               "free": "2346.50000000",
               "interest": "0.00000000",
               "locked": "0.00000000",
               "netAsset": "2144.83333328"
           },
           {
               "asset": "ETH",
               "borrowed": "0.00000000",
               "free": "0.00000000",
               "interest": "0.00000000",
               "locked": "0.00000000",
               "netAsset": "0.00000000"
           },
           {
               "asset": "USDT",
               "borrowed": "0.00000000",
               "free": "0.00000000",
               "interest": "0.00000000",
               "locked": "0.00000000",
               "netAsset": "0.00000000"
           }
       ]
 }

get_margin_balances(decimal_mode: bool) → dict[source]¶

Collects balances in the margin account that are not null.

Parameters:: decimal_mode (bool) – Fixes Decimal return type and operative. :return dict: A dictionary with coins with balances.

Example:

{'BNB': {'free': 0.06,
   'locked': 0.0,
   'borrowed': 0.0,
   'interest': 0.0,
   'netAsset': 0.06},
  'BUSD': {'free': 50.0,
   'locked': 0.0,
   'borrowed': 0.0,
   'interest': 0.0,
   'netAsset': 50.0}}

get_margin_free_balances(decimal_mode: bool, balances: dict = None) → dict[source]¶

Just returns free existing balances. It is optional to avoid an API call.

Parameters:: balances (dict) – Returns dict with assets as keys and a float value for not null quantities. :param bool decimal_mode: Fixes Decimal return type.
Return dict:: A dict with float values.

get_margin_locked_balances(decimal_mode: bool, balances: dict = None) → dict[source]¶

Just returns locked existing balances. It is optional to avoid an API call.

Parameters:: decimal_mode (bool) – Fixes Decimal return type. :param dict balances: Returns dict with assets as keys and a float value for not null quantities.
Return dict:: A dict with float values.

get_margin_borrowed_balances(decimal_mode: bool, balances: dict = None) → dict[source]¶

Just returns borrowed existing balances. It is optional to avoid an API call.

Parameters:: decimal_mode (bool) – Fixes Decimal return type. :param dict balances: Returns dict with assets as keys and a float value for not null quantities.
Return dict:: A dict with float values.

get_margin_interest_balances(decimal_mode: bool, balances: dict = None) → dict[source]¶

Just returns interest existing balances. It is optional to avoid an API call.

Parameters:: decimal_mode (bool) – Fixes Decimal return type. :param dict balances: Returns dict with assets as keys and a float value for not null quantities.
Return dict:: A dict with float values.

get_margin_netAsset_balances(decimal_mode: bool, balances: dict = None)[source]¶

Just returns netAsset existing balances. It is optional to avoid an API call.

Parameters:: decimal_mode (bool) – Fixes Decimal return type. :param dict balances: Returns dict with assets as keys and a float value for not null quantities.
Return dict:: A dict with float values.

get_margin_balances_total_value(decimal_mode: bool, balances: dict = None, convert_to: str = 'BUSD') → float | Decimal[source]¶

Returns total value expressed in a quote coin. Counts free, locked, borrowed and interest assets.

Parameters:

balances (dict) – A BinPan balances dict. It is optional to avoid an API call. :param str convert_to: A Binance coin.
decimal_mode (bool) – Fixes Decimal return type.

Return float:

Total quantity expressed in quote.