Private API

A python class for sending API requests that require authorization.

The private API is a class to send API requests that requires authorization, e.g. get my balance in Binance spot wallet, create a buy order of BTCUSDT, cancel an order, and etc.

It is initialized prior to your code as a variable named privateAPI. When initializing, it automatically gathers the API keys that you have registered.

The private API class can only be used in terminal. In other words, it does not work in analytics.

If you didn't register the API key of some exchanges, then the functions which send API requests to them will throw exceptions.

...

import PrivateAPI

# `privateAPI` object is automatically initialized
# before running your code.
privateAPI = PrivateAPI()

# your python code is placed here
# In your code, you can send private API requests like below:
## privateAPI.buy('binance', 'BTCUSDT', 0.02, 28000)

Common Functions

The common functions are the methods of the private API, available for (almost) any exchanges we support. By using these functions, you can easily switch the exchanges you want to send API request to.

Every common function has its first argument as an exchange. It specifies which exchange should the request be sent to. For example, you can get the balance in your Binance spot wallet by privateAPI.get_balance('binance'), while privateAPI.get_balance('binance_um_futures') returns the balance in your Binance USDⓈ-M futures wallet in a same response structure.

For now, the available exchanges are,

  • binance : Binance Spot

  • binance_um_futures : Binance USDⓈ-M Futures

  • binance_cm_futures : Binance COIN-M Futures

1. Get Balance

privateAPI.get_balance(exchange: str) -> dict

It is a function to get the asset information in the exchange's wallet.

Arguments

  • exchange : (string) The name of the exchange.

Returns

It returns the dictionary object with its key as a name of the asset in string, and value as the information on the asset. The information has three key:

  • amount : (float) Current actual amount of the asset. unrealized_pnl is not included.

  • available : (float) The amount of the asset available for trading.

  • unrealized_pnl : (float) The unrealized PnL(profit & loss) of the asset by the derivatives such as futures position. If the exchange is spot-only, then it is always 0.

Usually, amount = available + (locked amount because of open orders, maintenance margin, etc.) holds.

# returning object example
{
    'BTC':{
        'amount':0.122503,
        'available':0.122503,
        'unrealized_pnl':0
    },
    'USDT':{
        'amount':160.32,
        'available':131.681,
        'unrealized_pnl':-3.1252
    }
}

2. Get Positions

privateAPI.get_positions(exchange: str) -> dict

It is a function to get the position information in the exchange's account.

This function merges all open positions by the symbol. For example, if you have both 0.1 BTCUSDT long and -0.2 BTCUSDT short position, then this method will return BTCUSDT short position with the amount = -0.1.

Only the exchanges which have futures are available. c.f. binance(= Binance spot) cannot be the value of the exchange argument for this function.

Arguments

  • exchange : (string) The name of the exchange.

Returns

It returns the dictionary object with its key as a name of the symbol in string, and value as the information on the position. The information has three key:

  • side : (string) 'long' for long, or 'short' for short.

  • amount : (float) The amount of the position currently holding. Positive for long, negative for short.

  • unrealized_pnl : (float) The unrealized PnL of the position.

# returning object example
{
    'BTCUSDT':{
        'side':'short',
        'amount':-0.1125,
        'unrealized_pnl':21.3225
    },
    'BTCUSDT_220930':{
        'side':'long',
        'amount':0.351,
        'unrealized_pnl':-1.7862
    }
}

3. Buy

privateAPI.buy(exchange: str, symbol: str, amount: float, price: float = None, order_type: str = 'limit', reduce_only: bool = False) -> None

Create a buy/long order.

Arguments

  • exchange : (string) The name of the exchange.

  • symbol : (string) The name of the symbol.

  • amount : (float) The amount of the order. It must be positive.

  • price : (float) The price of the order to be trade. Default value is None. It should be None when the order_type == 'market'.

  • order_type : (string) The type of the order. 'limit' for limit order, 'market' for market order. Default value is 'limit'.

  • reduce_only : (boolean) Futures only arguments. Enable reduce only option. If it's true, then the order works only to close the current position. Default value is False.

Returns

None

4. Sell

privateAPI.sell(exchange: str, symbol: str, amount: float=None, price: float = None, order_type: str = 'limit', reduce_only: bool = False, **kwargs) -> None

Create a sell/short order.

Arguments

  • exchange : (string) The name of the exchange.

  • symbol : (string) The name of the symbol.

  • amount : (float) The amount of the order. It must be positive.

  • price : (float) The price of the order to be trade. Default value is None. It should be None when the order_type == 'market'.

  • order_type : (string) The type of the order. 'limit' for limit order, 'market' for market order. Default value is 'limit'.

  • reduce_only : (boolean) Futures only arguments. Enable reduce only option. If it's true, then the order works only to close the current position. Default value is False.

Returns

None

5. Get Open Orders

privateAPI.get_open_orders(exchange: str, **kwargs) -> list

Get the list of the open orders' symbol and order ID.

Some exchanges may require additional arguments.

Arguments

  • exchange : (string) The name of the exchange.

  • **kwargs : Additional arguments.

    • symbol : (string) The symbol of the orders. binance, binance_um_futures, and binance_cm_futures require symbol argument.

Returns

It returns a list of the order element. The order element is a dictionary of symbol and order_id.

  • symbol : (string) The symbol of the order.

  • order_id : (string) The order ID of the order.

# function example that requires additional `symbol` argument.
# Without symbol='BTCUSDT' in the argument, it would raise an exception.
orders = privateAPI.get_open_orders('binance', symbol='BTCUSDT')

# returning object example
[
    {
        'symbol':'BTCUSDT',
        'order_id':'123612397'
    },
    ...
]

6. Cancel an Order

privateAPI.cancel_order(exchange: str, order_id, **kwargs) -> None

Cancel an open order by its order ID.

Some exchanges may require additional arguments.

Arguments

  • exchange : (string) The name of the exchange.

  • order_id : An ID of the order to cancel.

  • **kwargs : Additional arguments.

    • symbol : (string) The symbol of the orders. binance, binance_um_futures, and binance_cm_futures require symbol argument.

Returns

None

# function example that requires additional `symbol` argument.
# Without symbol='ETHUSDT' in the argument, it would raise an exception.
privateAPI.cancel_order('binance', '12312722', symbol='ETHUSDT')

7. Cancel All Orders

privateAPI.cancel_all_orders(exchange: str, **kwargs) -> None

Cancel all the open orders.

Some exchanges may require additional arguments.

Arguments

  • exchange : (string) The name of the exchange.

  • **kwargs : Additional arguments.

    • symbol : (string) The symbol of the orders. binance, binance_um_futures, and binance_cm_futures require symbol argument.

Returns

None

# function example that requires additional `symbol` argument.
# Without symbol='BTCUSD' in the argument, it would raise an exception.
privateAPI.cancel_all_orders('binance_cm_futures', symbol='BTCUSD')

8. Set Leverage

privateAPI.set_leverage(exchange: str, leverage:int, **kwargs) -> None

Set leverage value.

Some exchanges may require additional arguments.

Only the exchanges which have futures are available. c.f. binance(= Binance spot) cannot be the value of the exchange argument for this function.

Arguments

  • exchange : (string) The name of the exchange.

  • leverage : The leverage value to set. It is usually a positive integer value.

  • **kwargs : Additional arguments.

    • symbol : (string) The symbol of the orders. binance_um_futures, and binance_cm_futures require symbol argument.

Returns

None

# function example that requires additional `symbol` argument.
# Without symbol='BTCUSDT' in the argument, it would raise an exception.
privateAPI.set_leverage('binance_um_futures', 5, symbol='BTCUSDT')

9. Get API request result

privateAPI._get(exchange: str, api_url:str, **kwargs) -> Any

This is a special function that can call any API requests that read/get the information.

If you are about the get public API requests such as getting orderbook, getting exchange info, and etc, then user publicAPI._get()

Arguments

  • exchange : (string) The name of the exchange.

  • api_url : (string) Endpoint of the request, such as '/api/v1/exchangeIfo'.

  • **kwargs : Additional arguments. They will be used as the parameters of the request.

Returns

None

# This code will returns the leverage bracket information of 'BTCUSDT'.
# Link : https://binance-docs.github.io/apidocs/futures/en/#notional-and-leverage-brackets-user_data
result = privateAPI._get(
    exchange = 'binance_um_futures', 
    api_url = '/fapi/v1/leverageBracket',
    symbol='BTCUSDT'
)

Exchange-Only Functions

While common functions make it easy to switch exchanges, there are API requests which are specialized for the specific exchanges. Or, you may want to handle detailed options or values that the common functions cannot cover. In that case, the exchange-only functions can help you with that.

Most of the exchange-only functions have **kwargs to support all the parameters that the API can have.

The returns are the object obtained by parsing the API response(Usually in JSON format). Therefore, the type of them are dict, list or None.

Binance

Binance

PreviousPython LibraryNextBinance

Last updated

Copyright © 2023, UnBlinked Co., Ltd. | All rights reserved.