async def close_listen_key_isolated_margin(self, symbol: str,
key: str) -> Dict[str, Any]:
"""
Close a listen key for the ISOLATED MARGIN API.
Close a ListenKey (USER_STREAM).
`DELETE /sapi/v1/userDataStream`.
Parameters
----------
symbol : str
The symbol for the listen key request.
key : str
The listen key for the request.
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#listen-key-isolated-margin
"""
return await self.client.send_request(
http_method="DELETE",
url_path=self.BASE_ENDPOINT_ISOLATED,
payload={
"listenKey": key,
"symbol": format_symbol(symbol).upper()
},
)
async def depth(self,
symbol: str,
limit: Optional[int] = None) -> Dict[str, Any]:
"""
Get orderbook.
`GET /api/v3/depth`
Parameters
----------
symbol : str
The trading pair.
limit : int, optional, default 100
The limit for the response. Default 100; max 5000.
Valid limits:[5, 10, 20, 50, 100, 500, 1000, 5000].
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#order-book
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
if limit is not None:
payload["limit"] = str(limit)
return await self.client.query(
url_path=self.BASE_ENDPOINT + "depth",
payload=payload,
)
async def book_ticker(self, symbol: str = None) -> Dict[str, Any]:
"""
Symbol Order Book Ticker.
`GET /api/v3/ticker/bookTicker`
Parameters
----------
symbol : str, optional
The trading pair.
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#symbol-order-book-ticker
"""
payload: Dict[str, str] = {}
if symbol is not None:
payload["symbol"] = format_symbol(symbol).upper()
return await self.client.query(
url_path=self.BASE_ENDPOINT + "ticker/bookTicker",
payload=payload,
)
async def trades(self,
symbol: str,
limit: Optional[int] = None) -> List[Dict[str, Any]]:
"""
Get recent market trades.
Recent Trades List.
`GET /api/v3/trades`
Parameters
----------
symbol : str
The trading pair.
limit : int, optional
The limit for the response. Default 500; max 1000.
Returns
-------
list[dict[str, Any]]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#recent-trades-list
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
if limit is not None:
payload["limit"] = str(limit)
return await self.client.query(
url_path=self.BASE_ENDPOINT + "trades",
payload=payload,
)
async def create_listen_key_isolated_margin(self,
symbol: str) -> Dict[str, Any]:
"""
Create a new listen key for the ISOLATED MARGIN API.
Start a new user data stream. The stream will close after 60 minutes
unless a keepalive is sent. If the account has an active listenKey,
that listenKey will be returned and its validity will be extended for 60
minutes.
Create a ListenKey (USER_STREAM).
`POST /api/v3/userDataStream `.
Parameters
----------
symbol : str
The symbol for the listen key request.
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#listen-key-isolated-margin
"""
return await self.client.send_request(
http_method="POST",
url_path=self.BASE_ENDPOINT_ISOLATED,
payload={"symbol": format_symbol(symbol).upper()},
)
async def ticker_24hr(self, symbol: str = None) -> Dict[str, Any]:
"""
24hr Ticker Price Change Statistics.
`GET /api/v3/ticker/24hr`
Parameters
----------
symbol : str, optional
The trading pair.
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#24hr-ticker-price-change-statistics
"""
payload: Dict[str, str] = {}
if symbol is not None:
payload["symbol"] = format_symbol(symbol).upper()
return await self.client.query(
url_path=self.BASE_ENDPOINT + "ticker/24hr",
payload=payload,
)
async def avg_price(self, symbol: str) -> Dict[str, Any]:
"""
Get the current average price for the given symbol.
`GET /api/v3/avgPrice`
Parameters
----------
symbol : str
The trading pair.
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#current-average-price
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
return await self.client.query(
url_path=self.BASE_ENDPOINT + "avgPrice",
payload=payload,
)
async def get_orders(
self,
symbol: str,
order_id: Optional[str] = None,
start_time: Optional[int] = None,
end_time: Optional[int] = None,
limit: Optional[int] = None,
recv_window: Optional[int] = None,
) -> Dict[str, Any]:
"""
Get all account orders; active, canceled, or filled.
All Orders (USER_DATA).
`GET /api/v3/allOrders`.
Parameters
----------
symbol : str
The symbol for the request.
order_id : str, optional
The order ID for the request.
start_time : int, optional
The start time (UNIX milliseconds) filter for the request.
end_time : int, optional
The end time (UNIX milliseconds) filter for the request.
limit : int, optional
The limit for the response.
recv_window : int, optional
The response receive window for the request (cannot be greater than 60000).
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#all-orders-user_data
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
if order_id is not None:
payload["orderId"] = order_id
if start_time is not None:
payload["startTime"] = str(start_time)
if end_time is not None:
payload["endTime"] = str(end_time)
if limit is not None:
payload["limit"] = str(limit)
if recv_window is not None:
payload["recvWindow"] = str(recv_window)
return await self.client.sign_request(
http_method="GET",
url_path=self.BASE_ENDPOINT + "allOrders",
payload=payload,
)
async def cancel_oco_order(
self,
symbol: str,
order_list_id: Optional[str] = None,
list_client_order_id: Optional[str] = None,
new_client_order_id: Optional[str] = None,
recv_window: Optional[int] = None,
) -> Dict[str, Any]:
"""
Cancel an entire Order List.
Either `order_list_id` or `list_client_order_id` must be provided.
Cancel OCO (TRADE).
`DELETE /api/v3/orderList`.
Parameters
----------
symbol : str
The symbol for the request.
order_list_id : str, optional
The order list ID for the request.
list_client_order_id : str, optional
The list client order ID for the request.
new_client_order_id : str, optional
The new client order ID to uniquely identify this request.
recv_window : int, optional
The response receive window for the request (cannot be greater than 60000).
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#cancel-oco-trade
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
if order_list_id is not None:
payload["orderListId"] = order_list_id
if list_client_order_id is not None:
payload["listClientOrderId"] = list_client_order_id
if new_client_order_id is not None:
payload["newClientOrderId"] = new_client_order_id
if recv_window is not None:
payload["recvWindow"] = str(recv_window)
return await self.client.sign_request(
http_method="DELETE",
url_path=self.BASE_ENDPOINT + "orderList",
payload=payload,
)
async def cancel_order(
self,
symbol: str,
order_id: Optional[str] = None,
orig_client_order_id: Optional[str] = None,
new_client_order_id: Optional[str] = None,
recv_window: Optional[int] = None,
) -> Dict[str, Any]:
"""
Cancel an active order.
Cancel Order (TRADE).
`DELETE /api/v3/order`.
Parameters
----------
symbol : str
The symbol for the request.
order_id : str, optional
The order ID to cancel.
orig_client_order_id : str, optional
The original client order ID to cancel.
new_client_order_id : str, optional
The new client order ID to uniquely identify this request.
recv_window : int, optional
The response receive window for the request (cannot be greater than 60000).
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#cancel-order-trade
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
if order_id is not None:
payload["orderId"] = str(order_id)
if orig_client_order_id is not None:
payload["origClientOrderId"] = str(orig_client_order_id)
if new_client_order_id is not None:
payload["newClientOrderId"] = str(new_client_order_id)
if recv_window is not None:
payload["recvWindow"] = str(recv_window)
return await self.client.sign_request(
http_method="DELETE",
url_path=self.BASE_ENDPOINT + "order",
payload=payload,
)
async def agg_trades(
self,
symbol: str,
from_id: Optional[int] = None,
start_time_ms: Optional[int] = None,
end_time_ms: Optional[int] = None,
limit: Optional[int] = None,
) -> Dict[str, Any]:
"""
Get recent aggregated market trades.
Compressed/Aggregate Trades List.
`GET /api/v3/aggTrades`
Parameters
----------
symbol : str
The trading pair.
from_id : int, optional
The trade ID to fetch from. Default gets most recent trades.
start_time_ms : int, optional
The UNIX timestamp (milliseconds) to get aggregate trades from INCLUSIVE.
end_time_ms: int, optional
The UNIX timestamp (milliseconds) to get aggregate trades until INCLUSIVE.
limit : int, optional
The limit for the response. Default 500; max 1000.
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#compressed-aggregate-trades-list
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
if from_id is not None:
payload["fromId"] = str(from_id)
if start_time_ms is not None:
payload["startTime"] = str(start_time_ms)
if end_time_ms is not None:
payload["endTime"] = str(end_time_ms)
if limit is not None:
payload["limit"] = str(limit)
return await self.client.query(
url_path=self.BASE_ENDPOINT + "aggTrades",
payload=payload,
)
async def klines(
self,
symbol: str,
interval: str,
start_time_ms: Optional[int] = None,
end_time_ms: Optional[int] = None,
limit: Optional[int] = None,
) -> List[List[Any]]:
"""
Kline/Candlestick Data.
`GET /api/v3/klines`
Parameters
----------
symbol : str
The trading pair.
interval : str
The interval of kline, e.g 1m, 5m, 1h, 1d, etc.
start_time_ms : int, optional
The UNIX timestamp (milliseconds) to get aggregate trades from INCLUSIVE.
end_time_ms: int, optional
The UNIX timestamp (milliseconds) to get aggregate trades until INCLUSIVE.
limit : int, optional
The limit for the response. Default 500; max 1000.
Returns
-------
list[list[Any]]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#kline-candlestick-data
"""
payload: Dict[str, str] = {
"symbol": format_symbol(symbol).upper(),
"interval": interval,
}
if start_time_ms is not None:
payload["startTime"] = str(start_time_ms)
if end_time_ms is not None:
payload["endTime"] = str(end_time_ms)
if limit is not None:
payload["limit"] = str(limit)
return await self.client.query(
url_path=self.BASE_ENDPOINT + "klines",
payload=payload,
)
async def get_order(
self,
symbol: str,
order_id: Optional[str] = None,
orig_client_order_id: Optional[str] = None,
recv_window: Optional[int] = None,
) -> Dict[str, Any]:
"""
Check an order's status.
Query Order (USER_DATA).
`GET /api/v3/order`.
Parameters
----------
symbol : str
The symbol for the request.
order_id : str, optional
The order ID for the request.
orig_client_order_id : str, optional
The original client order ID for the request.
recv_window : int, optional
The response receive window for the request (cannot be greater than 60000).
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#query-order-user_data
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
if order_id is not None:
payload["orderId"] = order_id
if orig_client_order_id is not None:
payload["origClientOrderId"] = orig_client_order_id
if recv_window is not None:
payload["recvWindow"] = str(recv_window)
return await self.client.sign_request(
http_method="GET",
url_path=self.BASE_ENDPOINT + "order",
payload=payload,
)
async def historical_trades(
self,
symbol: str,
from_id: Optional[int] = None,
limit: Optional[int] = None,
) -> Dict[str, Any]:
"""
Get older market trades.
Old Trade Lookup.
`GET /api/v3/historicalTrades`
Parameters
----------
symbol : str
The trading pair.
from_id : int, optional
The trade ID to fetch from. Default gets most recent trades.
limit : int, optional
The limit for the response. Default 500; max 1000.
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#old-trade-lookup
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
if limit is not None:
payload["limit"] = str(limit)
if from_id is not None:
payload["fromId"] = str(from_id)
return await self.client.limit_request(
http_method="GET",
url_path=self.BASE_ENDPOINT + "historicalTrades",
payload=payload,
)
async def exchange_info(self,
symbol: str = None,
symbols: list = None) -> Dict[str, Any]:
"""
Get current exchange trading rules and symbol information.
Only either `symbol` or `symbols` should be passed.
Exchange Information.
`GET /api/v3/exchangeinfo`
Parameters
----------
symbol : str, optional
The trading pair.
symbols : list[str], optional
The list of trading pairs.
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#exchange-information
"""
if symbol and symbols:
raise ValueError("`symbol` and `symbols` cannot be sent together")
payload: Dict[str, str] = {}
if symbol is not None:
payload["symbol"] = format_symbol(symbol).upper()
if symbols is not None:
payload["symbols"] = convert_list_to_json_array(symbols)
return await self.client.query(
url_path=self.BASE_ENDPOINT + "exchangeInfo",
payload=payload,
)
async def get_open_orders(
self,
symbol: Optional[str] = None,
recv_window: Optional[int] = None,
) -> Dict[str, Any]:
"""
Get all open orders on a symbol.
Query Current Open Orders (USER_DATA).
`GET /api/v3/openOrders`.
Parameters
----------
symbol : str, optional
The symbol for the request.
recv_window : int, optional
The response receive window for the request (cannot be greater than 60000).
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#current-open-orders-user_data
"""
payload: Dict[str, str] = {}
if symbol is not None:
payload["symbol"] = format_symbol(symbol).upper()
if recv_window is not None:
payload["recvWindow"] = str(recv_window)
return await self.client.sign_request(
http_method="GET",
url_path=self.BASE_ENDPOINT + "openOrders",
payload=payload,
)
async def cancel_open_orders(
self,
symbol: str,
recv_window: Optional[int] = None,
) -> Dict[str, Any]:
"""
Cancel all active orders on a symbol. This includes OCO orders.
Cancel all Open Orders on a Symbol (TRADE).
`DELETE api/v3/openOrders`.
Parameters
----------
symbol : str
The symbol for the request.
recv_window : int, optional
The response receive window for the request (cannot be greater than 60000).
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#cancel-all-open-orders-on-a-symbol-trade
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
if recv_window is not None:
payload["recvWindow"] = str(recv_window)
return await self.client.sign_request(
http_method="DELETE",
url_path=self.BASE_ENDPOINT + "openOrders",
payload=payload,
)
async def ping_listen_key_isolated_margin(self, symbol: str,
key: str) -> Dict[str, Any]:
"""
Ping/Keep-alive a listen key for the ISOLATED MARGIN API.
Keep-alive a user data stream to prevent a time-out. User data streams
will close after 60 minutes. It's recommended to send a ping about every
30 minutes.
Ping/Keep-alive a ListenKey (USER_STREAM).
`PUT /api/v3/userDataStream`.
Parameters
----------
symbol : str
The symbol for the listen key request.
key : str
The listen key for the request.
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#listen-key-isolated-margin
"""
return await self.client.send_request(
http_method="PUT",
url_path=self.BASE_ENDPOINT_ISOLATED,
payload={
"listenKey": key,
"symbol": format_symbol(symbol).upper()
},
)
async def my_trades(
self,
symbol: str,
from_id: Optional[str] = None,
order_id: Optional[str] = None,
start_time: Optional[int] = None,
end_time: Optional[int] = None,
limit: Optional[int] = None,
recv_window: Optional[int] = None,
) -> Dict[str, Any]:
"""
Get trades for a specific account and symbol.
Account Trade List (USER_DATA)
`GET /api/v3/myTrades`.
Parameters
----------
symbol : str
The symbol for the request.
from_id : str, optional
The trade match ID to query from.
order_id : str, optional
The order ID for the trades. This can only be used in combination with symbol.
start_time : int, optional
The start time (UNIX milliseconds) filter for the request.
end_time : int, optional
The end time (UNIX milliseconds) filter for the request.
limit : int, optional
The limit for the response.
recv_window : int, optional
The response receive window for the request (cannot be greater than 60000).
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#account-trade-list-user_data
"""
payload: Dict[str, str] = {"symbol": format_symbol(symbol).upper()}
if from_id is not None:
payload["fromId"] = from_id
if order_id is not None:
payload["orderId"] = order_id
if start_time is not None:
payload["startTime"] = str(start_time)
if end_time is not None:
payload["endTime"] = str(end_time)
if limit is not None:
payload["limit"] = str(limit)
if recv_window is not None:
payload["recvWindow"] = str(recv_window)
return await self.client.sign_request(
http_method="GET",
url_path=self.BASE_ENDPOINT + "myTrades",
payload=payload,
)
async def new_oco_order(
self,
symbol: str,
side: str,
quantity: str,
price: str,
stop_price: str,
list_client_order_id: Optional[str] = None,
limit_client_order_id: Optional[str] = None,
limit_iceberg_qty: Optional[str] = None,
stop_client_order_id: Optional[str] = None,
stop_limit_price: Optional[str] = None,
stop_iceberg_qty: Optional[str] = None,
stop_limit_time_in_force: Optional[str] = None,
new_order_resp_type: NewOrderRespType = None,
recv_window: Optional[int] = None,
) -> Dict[str, Any]:
"""
Submit a new OCO order.
Submit New OCO (TRADE).
`POST /api/v3/order/oco`.
Parameters
----------
symbol : str
The symbol for the request.
side : str
The order side for the request.
quantity : str
The order quantity for the request.
price : str
The order price for the request.
stop_price : str
The order stop price for the request.
list_client_order_id : str, optional
The list client order ID for the request.
limit_client_order_id : str, optional
The LIMIT client order ID for the request.
limit_iceberg_qty : str, optional
The LIMIT order display quantity for the request.
stop_client_order_id : str, optional
The STOP order client order ID for the request.
stop_limit_price : str, optional
The STOP_LIMIT price for the request.
stop_iceberg_qty : str, optional
The STOP order display quantity for the request.
stop_limit_time_in_force : str, optional
The STOP_LIMIT time_in_force for the request.
new_order_resp_type : NewOrderRespType, optional
The response type for the order request.
MARKET and LIMIT order types default to FULL, all other orders default to ACK.
recv_window : int, optional
The response receive window for the request (cannot be greater than 60000).
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#new-oco-trade
"""
payload: Dict[str, str] = {
"symbol": format_symbol(symbol).upper(),
"side": side,
"quantity": quantity,
"price": price,
"stopPrice": stop_price,
}
if list_client_order_id is not None:
payload["listClientOrderId"] = list_client_order_id
if limit_client_order_id is not None:
payload["limitClientOrderId"] = limit_client_order_id
if limit_iceberg_qty is not None:
payload["limitIcebergQty"] = limit_iceberg_qty
if stop_client_order_id is not None:
payload["stopClientOrderId"] = stop_client_order_id
if stop_limit_price is not None:
payload["stopLimitPrice"] = stop_limit_price
if stop_iceberg_qty is not None:
payload["stopIcebergQty"] = stop_iceberg_qty
if stop_limit_time_in_force is not None:
payload["stopLimitTimeInForce"] = stop_limit_time_in_force
if new_order_resp_type is not None:
payload["new_order_resp_type"] = new_order_resp_type.value
if recv_window is not None:
payload["recvWindow"] = str(recv_window)
return await self.client.sign_request(
http_method="POST",
url_path=self.BASE_ENDPOINT + "order/oco",
payload=payload,
)
async def new_order_test(
self,
symbol: str,
side: str,
type: str,
time_in_force: Optional[str] = None,
quantity: Optional[str] = None,
quote_order_qty: Optional[str] = None,
price: Optional[str] = None,
new_client_order_id: Optional[str] = None,
stop_price: Optional[str] = None,
iceberg_qty: Optional[str] = None,
new_order_resp_type: NewOrderRespType = None,
recv_window: Optional[int] = None,
) -> Dict[str, Any]:
"""
Test new order creation and signature/recvWindow.
Creates and validates a new order but does not send it into the matching engine.
Test New Order (TRADE).
`POST /api/v3/order/test`.
Parameters
----------
symbol : str
The symbol for the request.
side : str
The order side for the request.
type : str
The order type for the request.
time_in_force : str, optional
The order time in force for the request.
quantity : str, optional
The order quantity in base asset units for the request.
quote_order_qty : str, optional
The order quantity in quote asset units for the request.
price : str, optional
The order price for the request.
new_client_order_id : str, optional
The client order ID for the request. A unique ID among open orders.
Automatically generated if not provided.
stop_price : str, optional
The order stop price for the request.
Used with STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.
iceberg_qty : str, optional
The order iceberg (display) quantity for the request.
Used with LIMIT, STOP_LOSS_LIMIT, and TAKE_PROFIT_LIMIT to create an iceberg order.
new_order_resp_type : NewOrderRespType, optional
The response type for the order request.
MARKET and LIMIT order types default to FULL, all other orders default to ACK.
recv_window : int, optional
The response receive window for the request (cannot be greater than 60000).
Returns
-------
dict[str, Any]
References
----------
https://binance-docs.github.io/apidocs/spot/en/#test-new-order-trade
"""
payload: Dict[str, str] = {
"symbol": format_symbol(symbol).upper(),
"side": side,
"type": type,
}
if time_in_force is not None:
payload["timeInForce"] = time_in_force
if quantity is not None:
payload["quantity"] = quantity
if quote_order_qty is not None:
payload["quoteOrderQty"] = quote_order_qty
if price is not None:
payload["price"] = price
if new_client_order_id is not None:
payload["newClientOrderId"] = new_client_order_id
if stop_price is not None:
payload["stopPrice"] = stop_price
if iceberg_qty is not None:
payload["icebergQty"] = iceberg_qty
if new_order_resp_type is not None:
payload["newOrderRespType"] = new_order_resp_type.value
if recv_window is not None:
payload["recvWindow"] = str(recv_window)
return await self.client.sign_request(
http_method="POST",
url_path=self.BASE_ENDPOINT + "order/test",
payload=payload,
)
