From 1333e80a8caded0fda677f1a1dd63ee4a2fe5311 Mon Sep 17 00:00:00 2001 From: Davide Casale Date: Wed, 12 Apr 2023 03:12:36 +0200 Subject: [PATCH] Improve readability for some paragraphs in README.md documentation. --- README.md | 108 ++++++++++++++++++++++++------------------------------ 1 file changed, 48 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 21cd9be..01e2642 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ python3 -m pip install bitfinex-api-py==3.0.0b1 --- -### Index +## Index * [WebSocket client documentation](#websocket-client-documentation) * [Building the source code](#building-the-source-code) @@ -48,17 +48,17 @@ python3 -m pip install bitfinex-api-py==3.0.0b1 1. [Instantiating the client](#instantiating-the-client) * [Authentication](#authentication) - - [Filtering](#filtering) + - [Filtering the channels](#filtering-the-channels) 2. [Running the client](#running-the-client) * [Closing the connection](#closing-the-connection) 3. [Subscribing to public channels](#subscribing-to-public-channels) * [Unsubscribing from a public channel](#unsubscribing-from-a-public-channel) * [Setting a custom `sub_id`](#setting-a-custom-sub_id) 4. [Listening to events](#listening-to-events) -5. [Advanced Features](#advanced-features) - * [Connection multiplexing](#connection-multiplexing) - * [Sending custom notifications](#sending-custom-notifications) - * [Handling reconnections in case of network failure](#handling-reconnections-in-case-of-network-failure) + +### Advanced features +* [Sending custom notifications](#sending-custom-notifications) +* [Setting up connection multiplexing](#setting-up-connection-multiplexing) ## Instantiating the client @@ -71,7 +71,7 @@ The `wss_host` argument is used to indicate the URL to which the WebSocket clien The `bfxapi` package exports 2 constants to quickly set this URL: Constant | URL | When to use ---- | --- | --- +:--- | :--- | :--- WSS_HOST | wss://api.bitfinex.com/ws/2 | Suitable for all situations, supports authentication. PUB_WSS_HOST | wss://api-pub.bitfinex.com/ws/2 | For public uses only, doesn't support authentication. @@ -91,8 +91,8 @@ bfx = Client( ``` If authentication succeeds, the client will emit the `authenticated` event. \ -All operations that require authentication must be performed after the emission of this event. \ -The `data` argument contains information regarding the authentication, such as the `userId`, the `auth_id`, etc... +All operations that require authentication will fail if run before the emission of this event. \ +The `data` argument contains various information about the authentication, such as the `userId`, the `auth_id`, etc... ```python @bfx.wss.on("authenticated") @@ -100,12 +100,24 @@ def on_authenticated(data: Dict[str, Any]): print(f"Successful login for user <{data['userId']}>.") ``` +`data` can also be useful for checking API-KEY's permissions: + +```python +@bfx.wss.on("authenticated") +def on_authenticated(data: Dict[str, Any]): + if not data["caps"]["orders"]["read"]: + raise Exception("This application requires read permissions on orders.") + + if not data["caps"]["positions"]["write"]: + raise Exception("This application requires write permissions on positions.") +``` + > **NOTE:** A guide on how to create, edit and revoke API-KEYs and API-SECRETs can be found [here](https://support.bitfinex.com/hc/en-us/articles/115003363429-How-to-create-and-revoke-a-Bitfinex-API-Key). -#### Filtering +#### Filtering the channels -`Client` accepts a `filters` argument, which you can use to select which channels the client should subscribe to: +It is possible to select which channels the client should subscribe to using the `filters` argument: ```python bfx = Client( @@ -116,21 +128,17 @@ bfx = Client( ) ``` -If `filters` is not given, the client will subscribe to all channels. - -Filters can be very useful both for safety reasons and for lightening network traffic (by excluding useless channels). \ +Filtering can be very useful both for safety reasons and for lightening network traffic (by excluding useless channels). \ Ideally, you should always use `filters`, selecting only the channels your application will actually use. \ -Below, you can find a complete list of available filters (and the events they will emit): +Below, you can find a complete list of available filters (and the channels they will subscribe the client to): Filter | Subscribes the client to... | Available events are... ---- | --- | --- +:--- | :--- | :--- trading | All channels regarding the user's orders, positions and trades (all trading pairs). | `order_snapshot`, `order_new`, `order_update`, `order_cancel`, `position_snapshot`, `position_new`, `position_update`, `position_close`, `trade_execution`, `trade_execution_update` trading-tBTCUSD | All channels regarding the user's orders, positions and trades (tBTCUSD). | `order_snapshot`, `order_new`, `order_update`, `order_cancel`, `position_snapshot`, `position_new`, `position_update`, `position_close`, `trade_executed`, `trade_execution_update` funding | All channels regarding the user's offers, credits and loans (all funding currencies). | `funding_offer_snapshot`, `funding_offer_new`, `funding_offer_update`, `funding_offer_cancel`, `funding_credit_snapshot`, `funding_credit_new`, `funding_credit_update`, `funding_credit_close`, `funding_loan_snapshot`, `funding_loan_new`, `funding_loan_update`, `funding_loan_close` funding-fBTC | All channels regarding the user's offers, credits and loans (fBTC). | `funding_offer_snapshot`, `funding_offer_new`, `funding_offer_update`, `funding_offer_cancel`, `funding_credit_snapshot`, `funding_credit_new`, `funding_credit_update`, `funding_credit_close`, `funding_loan_snapshot`, `funding_loan_new`, `funding_loan_update`, `funding_loan_close` wallet | All channels regarding user's exchange, trading and deposit wallets. | `wallet_snapshot`, `wallet_update` -wallet-exchange-BTC | Channel regarding user's BTC exchange wallet. | `wallet_snapshot`, `wallet_update` -balance | Channel regarding user's balances (tradable balance, etc...). | `balance_update` ## Running the client @@ -231,9 +239,29 @@ You can pass any number of events to register for the same callback function: bfx.wss.on("t_ticker_update", "f_ticker_update", callback=on_ticker_update) ``` -## Advanced features +# Advanced features -### Connection multiplexing +## Sending custom notifications + +**Sending custom notifications requires user authentication.** + +Users can send custom notifications using `BfxWebSocketClient::notify`: +```python +await bfx.wss.notify({ "foo": 1 }) +``` + +Any data can be sent along with a custom notification. + +Custom notifications are broadcast by the server on all user's open connections. \ +So, each custom notification will be sent to every online client of the current user. \ +Whenever a client receives a custom notification, it will emit the `notification` event: +```python +@bfx.wss.on("notification") +def on_notification(notification: Notification[Any]): + print(notification.data) # { "foo": 1 } +``` + +## Setting up connection multiplexing `BfxWebSocketClient::run` and `BfxWebSocketClient::start` accept a `connections` argument: ```python @@ -254,46 +282,6 @@ Keep in mind that using a large number of connections could slow down the client The use of more than 20 connections is not recommended. -### Sending custom notifications - -**Sending custom notifications requires user authentication.** - -Users can send custom notifications using `BfxWebSocketClient::notify`: -```python -await bfx.wss.notify({ "foo": 1 }) -``` - -Any data can be sent along with a custom notification. - -Custom notifications are broadcast by the server on all user's open connections. \ -So, each custom notification will be sent to every online client of the current user. \ -Whenever a client receives a custom notification, it will emit the `notification` event: -```python -@bfx.wss.on("notification") -def on_notification(notification: Notification[Any]): - print(notification.data) # { "foo": 1 } -``` - -### Handling reconnections in case of network failure - -In case of network failure, the client will keep waiting until it is able to restore the connection with the server. - -The client will try to reconnect with exponential backoff; the backoff delay starts at three seconds and increases up to one minute. - -After a successful reconnection attempt, the client will emit the `reconnection` event. - -This event accepts two arguments: \ -`attemps` (`int`) which is the number of reconnection attempts (including the successful one), \ -`timedelta` (`datetime.timedelta`) which contains the amount of time the client has been down. - -Users can use this event for a variety of things, such as sending a notification if the client has been down for too long: -```python -@bfx.wss.on("reconnection") -async def on_reconnection(attempts: int, timedelta: datetime.timedelta): - if timedelta.total_seconds() >= 60 * 60: # 60s * 60s = 3600s = 1h - await bfx.wss.notify(f"The client has been down for {timedelta}.") -``` - --- # Building the source code