diff --git a/bfxapi/rest/bfx_rest.py b/bfxapi/rest/bfx_rest.py index 0333208..85a60d3 100644 --- a/bfxapi/rest/bfx_rest.py +++ b/bfxapi/rest/bfx_rest.py @@ -100,6 +100,7 @@ class BfxRest: """ Get all of the public candles between the start and end period. + # Attributes @param symbol symbol string: pair symbol i.e tBTCUSD @param secton string: available values: "last", "hist" @param start int: millisecond start time @@ -120,6 +121,7 @@ class BfxRest: """ Get all of the public trades between the start and end period. + # Attributes @param symbol symbol string: pair symbol i.e tBTCUSD @param start int: millisecond start time @param end int: millisecond end time @@ -136,6 +138,7 @@ class BfxRest: """ Get the public orderbook for a given symbol. + # Attributes @param symbol symbol string: pair symbol i.e tBTCUSD @param precision string: level of price aggregation (P0, P1, P2, P3, P4, R0) @param length int: number of price points ("25", "100") @@ -151,6 +154,7 @@ class BfxRest: Get tickers for the given symbol. Tickers shows you the current best bid and ask, as well as the last trade price. + # Attributes @param symbols symbol string: pair symbol i.e tBTCUSD @return Array [ SYMBOL, BID, BID_SIZE, ASK, ASK_SIZE, DAILY_CHANGE, DAILY_CHANGE_PERC, LAST_PRICE, VOLUME, HIGH, LOW ] @@ -164,6 +168,7 @@ class BfxRest: Get tickers for the given symbols. Tickers shows you the current best bid and ask, as well as the last trade price. + # Attributes @param symbols Array: array of symbols i.e [tBTCUSD, tETHUSD] @return Array [ SYMBOL, BID, BID_SIZE, ASK, ASK_SIZE, DAILY_CHANGE, DAILY_CHANGE_PERC, LAST_PRICE, VOLUME, HIGH, LOW ] @@ -176,6 +181,7 @@ class BfxRest: """ Gets platform information for derivative symbol. + # Attributes @param derivativeSymbol string: i.e tBTCF0:USTF0 @return [KEY/SYMBOL, MTS, PLACEHOLDER, DERIV_PRICE, SPOT_PRICE, PLACEHOLDER, INSURANCE_FUND_BALANCE4, PLACEHOLDER, PLACEHOLDER, FUNDING_ACCRUED, FUNDING_STEP, PLACEHOLDER] @@ -189,6 +195,7 @@ class BfxRest: """ Gets platform information for a collection of derivative symbols. + # Attributes @param derivativeSymbols Array: array of symbols i.e [tBTCF0:USTF0 ...] or ["ALL"] @return [KEY/SYMBOL, MTS, PLACEHOLDER, DERIV_PRICE, SPOT_PRICE, PLACEHOLDER, INSURANCE_FUND_BALANCE4, PLACEHOLDER, PLACEHOLDER, FUNDING_ACCRUED, FUNDING_STEP, PLACEHOLDER] @@ -215,6 +222,7 @@ class BfxRest: """ Get all of the active orders associated with API_KEY - Requires authentication. + # Attributes @param symbol string: pair symbol i.e tBTCUSD @return Array """ @@ -227,6 +235,7 @@ class BfxRest: Get all of the orders between the start and end period associated with API_KEY - Requires authentication. + # Attributes @param symbol string: pair symbol i.e tBTCUSD @param start int: millisecond start time @param end int: millisecond end time @@ -254,6 +263,7 @@ class BfxRest: Get all of the trades that have been generated by the given order associated with API_KEY - Requires authentication. + # Attributes @param symbol string: pair symbol i.e tBTCUSD @param order_id string: id of the order @return Array @@ -267,6 +277,7 @@ class BfxRest: Get all of the trades between the start and end period associated with API_KEY - Requires authentication. + # Attributes @param symbol string: pair symbol i.e tBTCUSD @param start int: millisecond start time @param end int: millisecond end time @@ -293,6 +304,7 @@ class BfxRest: Get all of the funding offers between the start and end period associated with API_KEY - Requires authentication. + # Attributes @param symbol string: pair symbol i.e tBTCUSD @param start int: millisecond start time @param end int: millisecond end time @@ -319,6 +331,7 @@ class BfxRest: Get all of the funding loans between the start and end period associated with API_KEY - Requires authentication. + # Attributes @param symbol string: pair symbol i.e tBTCUSD @param start int: millisecond start time @param end int: millisecond end time @@ -340,6 +353,7 @@ class BfxRest: Get all of the funding credits between the start and end period associated with API_KEY - Requires authentication. + # Attributes @param symbol string: pair symbol i.e tBTCUSD @param start int: millisecond start time @param end int: millisecond end time @@ -356,6 +370,7 @@ class BfxRest: """ Submits a new funding offer + # Attributes @param symbol string: pair symbol i.e fUSD @param amount float: funding size @param rate float: percentage rate to charge per a day @@ -379,6 +394,7 @@ class BfxRest: """ Cancel a funding offer + # Attributes @param fundingId int: the id of the funding offer """ endpoint = "auth/w/funding/offer/cancel" @@ -389,6 +405,7 @@ class BfxRest: """ Transfer funds between wallets + # Attributes @param from_wallet string: wallet name to transfer from i.e margin, exchange @param to_wallet string: wallet name to transfer to i.e margin, exchange @param from_currency string: currency symbol to tranfer from i.e BTC, USD @@ -410,6 +427,7 @@ class BfxRest: """ Get the deposit address for the given wallet and protocol + # Attributes @param wallet string: wallet name i.e margin, exchange @param method string: transfer protocol i.e bitcoin """ @@ -427,6 +445,7 @@ class BfxRest: Creates a new deposit address for the given wallet and protocol. Previously generated addresses remain linked. + # Attributes @param wallet string: wallet name i.e margin, exchange @param method string: transfer protocol i.e bitcoin """ @@ -434,7 +453,13 @@ class BfxRest: async def submit_wallet_withdraw(self, wallet, method, amount, address): """ - `/v2/auth/w/withdraw` (params: `wallet`, `method`, `amount`, `address + Submits a request to withdraw crypto funds to an external wallet. + + # Attributes + @param wallet string: wallet name i.e margin, exchange + @param method string: transfer protocol i.e bitcoin + @param amount float: amount of funds to withdraw + @param address string: external address to withdraw to """ endpoint = "auth/w/withdraw" payload = { @@ -471,6 +496,7 @@ class BfxRest: """ Submit a new order + # Attributes @param gid: assign the order to a group identifier @param symbol: the name of the symbol i.e 'tBTCUSD @param price: the price you want to buy/sell at (must be positive) @@ -523,6 +549,7 @@ class BfxRest: """ Cancel an existing open order + # Attributes @param orderId: the id of the order that you want to update """ endpoint = "auth/w/order/cancel" @@ -535,6 +562,7 @@ class BfxRest: """ Update an existing order + # Attributes @param orderId: the id of the order that you want to update @param price: the price you want to buy/sell at (must be positive) @param amount: order size: how much you want to buy/sell, @@ -581,6 +609,7 @@ class BfxRest: """ Update the amount of callateral used to back a derivative position. + # Attributes @param symbol of the derivative i.e 'tBTCF0:USTF0' @param collateral: amount of collateral/value to apply to the open position """ diff --git a/bfxapi/websockets/bfx_websocket.py b/bfxapi/websockets/bfx_websocket.py index f1e548f..a7afcf2 100644 --- a/bfxapi/websockets/bfx_websocket.py +++ b/bfxapi/websockets/bfx_websocket.py @@ -88,6 +88,38 @@ class BfxWebsocket(GenericWebsocket): More complex websocket that heavily relies on the btfxwss module. This websocket requires authentication and is capable of handling orders. https://github.com/Crypto-toolbox/btfxwss + + ### Subscribable events: + - `all` (array|json): listen for all messages coming through + - `connected:` () called when a connection is made + - `disconnected`: () called when a connection is ended (A reconnect attempt may follow) + - `stopped`: () called when max amount of connection retries is met and the socket is closed + - `authenticated` (): called when the websocket passes authentication + - `notification` (Notification): incoming account notification + - `error` (array): error from the websocket + - `order_closed` (Order, Trade): when an order has been closed + - `order_new` (Order, Trade): when an order has been created but not closed. Note: will not be called if order is executed and filled instantly + - `order_confirmed` (Order, Trade): When an order has been submitted and received + - `wallet_snapshot` (array[Wallet]): Initial wallet balances (Fired once) + - `order_snapshot` (array[Order]): Initial open orders (Fired once) + - `positions_snapshot` (array): Initial open positions (Fired once) + - `wallet_update` (Wallet): changes to the balance of wallets + - `status_update` (json): new platform status info + - `seed_candle` (json): initial past candle to prime strategy + - `seed_trade` (json): initial past trade to prime strategy + - `funding_offer_snapshot` (array): opening funding offer balances + - `funding_loan_snapshot` (array): opening funding loan balances + - `funding_credit_snapshot` (array): opening funding credit balances + - `balance_update` (array): when the state of a balance is changed + - `new_trade` (array): a new trade on the market has been executed + - `trade_update` (array): a trade on the market has been updated + - `new_candle` (array): a new candle has been produced + - `margin_info_updates` (array): new margin information has been broadcasted + - `funding_info_updates` (array): new funding information has been broadcasted + - `order_book_snapshot` (array): initial snapshot of the order book on connection + - `order_book_update` (array): a new order has been placed into the ordebrook + - `subscribed` (Subscription): a new channel has been subscribed to + - `unsubscribed` (Subscription): a channel has been un-subscribed """ ERRORS = { @@ -461,6 +493,12 @@ class BfxWebsocket(GenericWebsocket): return total async def enable_flag(self, flag): + """ + Enable flag on websocket connection + + # Attributes + flag (int): int flag value + """ payload = { "event": 'conf', "flags": flag @@ -471,50 +509,185 @@ class BfxWebsocket(GenericWebsocket): await socket.ws.send(json.dumps(payload)) async def subscribe_order_book(self, symbol): + """ + Subscribe to an orderbook data feed + + # Attributes + @param symbol: the trading symbol i.e 'tBTCUSD' + """ return await self.subscribe('book', symbol) async def subscribe_candles(self, symbol, timeframe): + """ + Subscribe to a candle data feed + + # Attributes + @param symbol: the trading symbol i.e 'tBTCUSD' + """ return await self.subscribe('candles', symbol, timeframe=timeframe) async def subscribe_trades(self, symbol): + """ + Subscribe to a trades data feed + + # Attributes + @param symbol: the trading symbol i.e 'tBTCUSD' + """ return await self.subscribe('trades', symbol) async def subscribe_ticker(self, symbol): + """ + Subscribe to a ticker data feed + + # Attributes + @param symbol: the trading symbol i.e 'tBTCUSD' + """ return await self.subscribe('ticker', symbol) async def subscribe_derivative_status(self, symbol): + """ + Subscribe to a status data feed + + # Attributes + @param symbol: the trading symbol i.e 'tBTCUSD' + """ key = 'deriv:{}'.format(symbol) return await self.subscribe('status', symbol, key=key) async def subscribe(self, *args, **kwargs): + """ + Subscribe to a new channel + + # Attributes + @param channel_name: the name of the channel i.e 'books', 'candles' + @param symbol: the trading symbol i.e 'tBTCUSD' + @param timeframe: sepecifies the data timeframe between each candle (only required + for the candles channel) + """ return await self.subscriptionManager.subscribe(*args, **kwargs) async def unsubscribe(self, *args, **kwargs): + """ + Unsubscribe from the channel with the given chanId + + # Attributes + @param onComplete: function called when the bitfinex websocket resoponds with + a signal that confirms the subscription has been unsubscribed to + """ return await self.subscriptionManager.unsubscribe(*args, **kwargs) async def resubscribe(self, *args, **kwargs): + """ + Unsubscribes and then subscribes to the channel with the given Id + + This function is mostly used to force the channel to produce a fresh snapshot. + """ return await self.subscriptionManager.resubscribe(*args, **kwargs) async def unsubscribe_all(self, *args, **kwargs): + """ + Unsubscribe from all channels. + """ return await self.subscriptionManager.unsubscribe_all(*args, **kwargs) async def resubscribe_all(self, *args, **kwargs): + """ + Unsubscribe and then subscribe to all channels + """ return await self.subscriptionManager.resubscribe_all(*args, **kwargs) async def submit_order(self, *args, **kwargs): + """ + Submit a new order + + # Attributes + @param gid: assign the order to a group identifier + @param symbol: the name of the symbol i.e 'tBTCUSD + @param price: the price you want to buy/sell at (must be positive) + @param amount: order size: how much you want to buy/sell, + a negative amount indicates a sell order and positive a buy order + @param market_type Order.Type: please see Order.Type enum + amount decimal string Positive for buy, Negative for sell + @param hidden: if True, order should be hidden from orderbooks + @param price_trailing: decimal trailing price + @param price_aux_limit: decimal auxiliary Limit price (only for STOP LIMIT) + @param oco_stop_price: set the oco stop price (requires oco = True) + @param close: if True, close position if position present + @param reduce_only: if True, ensures that the executed order does not flip the opened position + @param post_only: if True, ensures the limit order will be added to the order book and not + match with a pre-existing order + @param oco: cancels other order option allows you to place a pair of orders stipulating + that if one order is executed fully or partially, then the other is automatically canceled + + @param time_in_force: datetime for automatic order cancellation ie. 2020-01-01 10:45:23 + @param leverage: the amount of leverage to apply to the order as an integer + @param onConfirm: function called when the bitfinex websocket receives signal that the order + was confirmed + @param onClose: function called when the bitfinex websocket receives signal that the order + was closed due to being filled or cancelled + """ return await self.orderManager.submit_order(*args, **kwargs) async def update_order(self, *args, **kwargs): + """ + Update an existing order + + # Attributes + @param orderId: the id of the order that you want to update + @param price: the price you want to buy/sell at (must be positive) + @param amount: order size: how much you want to buy/sell, + a negative amount indicates a sell order and positive a buy order + @param delta: change of amount + @param price_trailing: decimal trailing price + @param price_aux_limit: decimal auxiliary Limit price (only for STOP LIMIT) + @param hidden: if True, order should be hidden from orderbooks + @param close: if True, close position if position present + @param reduce_only: if True, ensures that the executed order does not flip the opened position + @param post_only: if True, ensures the limit order will be added to the order book and not + match with a pre-existing order + @param time_in_force: datetime for automatic order cancellation ie. 2020-01-01 10:45:23 + @param leverage: the amount of leverage to apply to the order as an integer + @param onConfirm: function called when the bitfinex websocket receives signal that the order + was confirmed + @param onClose: function called when the bitfinex websocket receives signal that the order + was closed due to being filled or cancelled + """ return await self.orderManager.update_order(*args, **kwargs) async def cancel_order(self, *args, **kwargs): + """ + Cancel an existing open order + + # Attributes + @param orderId: the id of the order that you want to update + @param onConfirm: function called when the bitfinex websocket receives signal that the + order + was confirmed + @param onClose: function called when the bitfinex websocket receives signal that the order + was closed due to being filled or cancelled + """ return await self.orderManager.cancel_order(*args, **kwargs) async def cancel_order_group(self, *args, **kwargs): + """ + Cancel a set of orders using a single group id. + """ return await self.orderManager.cancel_order_group(*args, **kwargs) async def cancel_all_orders(self, *args, **kwargs): + """ + Cancel all existing open orders + + This function closes all open orders. + """ return await self.orderManager.cancel_all_orders(*args, **kwargs) async def cancel_order_multi(self, *args, **kwargs): + """ + Cancel existing open orders as a batch + + # Attributes + @param ids: an array of order ids + @param gids: an array of group ids + """ return await self.orderManager.cancel_order_multi(*args, **kwargs)