Perpetual Connector v2.1¶

Prerequisites¶

Before proceeding with the setup of the Spot Connector, ensure that you have the Hummingbot source version installed on your system. Follow the detailed installation instructions provided at Hummingbot Installation Guide.

API Checklist¶

Name	Required	Type	Comments	Path URL
GET ACTIVE MARKETS	True	Public REST	Endpoint to get list of active trading pairs. example	`GET /markets`
GET LAST TRADED PRICE	False	Public REST		`GET /markets`
GET ORDERBOOK SNAPSHOT	False	Public REST		`GET /markets/{market_name}/orderbook?depth={depth}`
[TR] MINIMUN NOTIONAL SIZE	Conditionally	Public REST	Endpoint to get trading rules. example	`GET /markets`
[TR] MINIMUN ORDER SIZE	Conditionally	Public REST	Endpoint to get trading rules. example	`GET /markets`
[TR] MINIMUN PRICE	Conditionally	Public REST	Endpoint to get trading rules. example	`GET /markets`
[TR] ORDER INCREMENT	Conditionally	Public REST	Endpoint to get trading rules. example	`GET /markets`
PING ENDPOINT	True	Public REST	For low info endpoints, like ping. example	`GET /`
GET ACCOUNT BALANCE	True	Private REST	Get current account balance. example	`GET /wallet/balances`
GET ORDER STATUS BY client order id	Conditionally	Private REST		`GET /orders/by_client_id/{client_order_id}`
GET ORDER STATUS BY exchange_order_id	Conditionally	Private REST		`GET /orders/{order_id}`
GET TRADES HISTORY BY ORDER ID	Conditionally	Private REST		`GET /fills`
GET TRADES HISTORY BY TIMESTAMPS	Conditionally	Private REST		`GET /fills`
GET OPEN ORDERS	True	Private REST	Get active orders. example	`GET /orders`
CREATE ORDERS	True	Private REST	Create new orders. example	`POST /orders`
CREATE ORDERS with client order id	Conditionally	Private REST	Create new orders. example	`POST /orders`
CANCEL ORDER BY exchange_order_id	True	Private REST		`DELETE /orders`
CANCEL ORDER BY client order id	Conditionally	Private REST		`DELETE /orders`
ORDERBOOK CHANNEL (Min depth 100)	True	Public Websocket	Public orders channel. example	`orderbook`
ORDERBOOK DIFF CHANNEL	Conditionally	Public Websocket	Public orders channel. example	`orderbook`
USER TRADES CHANNEL (Order Status, fills, fees)	True	Private Websocket	Private orders updates. example	`fills`
USER ORDER CHANNEL (Order Status, fills, fees)		Private Websocket		`orders`
USER BALANCE CHANNEL (total and available)	False	Private Websocket	Private balance events. example
AUTHENTICATION	True	Other	Auth logic for web assistant. example
Rate limits	True	Other	Rate limits documentation. example
SERVER TIME	Conditionally	Public REST
FUNDING PAYMENT	True	Public REST	Funding payment info	`GET /funding_payments`
GET POSITIONS	True	Private REST	Get current positions	`GET /positions`

Build Process¶

Constants¶

Add to the constant files the following variables

DEFAULT DOMAIN: check if is you have to add more than 1 domain, this constant will be used for generating the path url in web_utils.
REST_URLS: could be a dictionary like ByBit connector or a f-string like Binance connector, the DEFAULT DOMAIN variable will be used to select the correct URL.
SERVER_TIME_PATH_URL: check if the exchange needs that your timestamp is in sync with the server time.

Web Utils¶

connector_name_web_utils.py file
- Copy the Bybit Perpetual connector web_utils file.
- Replace Bybit Perpetual for connector_name with the first letter in uppercase.
- Replace Bybit Perpetual for connector_name.
- Check if you need to have linear perpetual or remove that logic
- If you find a pattern, you can code the functions to get the results or success from the rest response
- Also you can do it to extract the topics and payload form the websocket channels
- Code the function to create the rest url, check if you need public and private url or just one of them.
- If you need Time Sync:
  - Check that you have the function build_api_factory_without_time_synchronizer_pre_processor.
  - Check if you need changes in the function get_current_server_time (maybe you need to find the server time in the response).
  - Code the build_api_factory with the time synchronizer as a rest_pre_processor
- If you don’t need Time Sync:
  - Delete the files related with the Time Sync and code the build_api_factory function without that.

Utils¶

Code in connector_name_utils.py file
- Copy the Bybit Perpetual connector utils file.
- Replace Bybit for connector_name with the first letter in uppercase.
- Replace bybit_perpetual for connector_name.
- Replace DEFAULT_FEES with the appropriate values .
- Check if you need connection to other domains or delete it.
- Check if you need linear trading or deleted

Order Book Data Source¶

connector_name_api_order_book_data_source.py
- Copy the Bybit Perpetual connector order book data source file.
- Replace Bybit for connector_name with the first letter in uppercase.
- Replace bybitl for connector_name.
- Replace the HEARTBEAT_TIME_INTERVAL with the appropriate value.
test_connector_name_api_order_book_data_source.py
- Copy the Bybit Perpetual the test of the order book data source file.
- Replace Bybit for connector_name with the first letter in uppercase.
- Replace bybit for connector_name.
Now we are going to start implementing the functionalities of the Order Book Data source but in a TDD way.
Methods development
- REST
  - orderbook
    - test_get_new_order_book_successful
    - _order_book_snapshot
    - _request_order_book_snapshot
    - test_get_new_order_book_raises_exception
  - funding_info
    - test_get_funding_info
    - get_funding_info
- WEBSOCKET
  - listen_for_subscriptions
    - test_listen_for_subscriptions_subscribes_to_trades_and_order_diffs_and_funding_info
    - listen_for_subscriptions (is in the superclass)
    - _connected_websocket_assistant
    - _subscribe_channels
    - _process_websocket_messages
    - _channel_originating_message
    - test_listen_for_subscriptions_raises_cancel_exception
    - test_listen_for_subscriptions_logs_exception_details
    - test_subscribe_channels_raises_cancel_exception
    - test_subscribe_channels_raises_exception_and_logs_error
  - listen_for_trades
    - test_listen_for_trades_successful
    - _parse_trade_message
    - test_listen_for_trades_cancelled_when_listening
    - test_listen_for_trades_logs_exception
  - listen_for_order_book_diffs
    - test_listen_for_order_book_diffs_successful
    - listen_for_order_book_diffs
    - _parse_order_book_diff_message
    - test_listen_for_order_book_diffs_cancelled
    - test_listen_for_order_book_diffs_logs_exception
  - listen_for_order_book_snapshots
    - test_listen_for_order_book_snapshots_cancelled_when_fetching_snapshot
    - listen_for_order_book_snapshots
    - _parse_order_book_snapshot_message
    - test_listen_for_order_book_snapshots_log_exception
    - test_listen_for_order_book_snapshots_successful
  - listen_for_funding_info
    - test_listen_for_funding_info_cancelled_when_listening
    - _parse_funding_info_message
    - test_listen_for_funding_info_logs_exception
    - test_listen_for_funding_info_successful

Auth¶

connector_name_auth.py
- Copy the Bybit Perpetual connector auth file.
- Replace Bybit for connector_name with the first letter in uppercase.
test_connector_name_auth.py
- Copy the Bybit Perpetual the test of the auth file.
- Replace Bybit Perpetual for connector_name with the first letter in uppercase.
- Replace Bybit Perpetual for connector_name.
Methods development
- REST
  - rest_authenticate
    - test_rest_authenticate
    - rest_authenticate
    - add_auth_to_params
    - header_for_authentication
    - _generate_signature
- WEBSOCKET
  - ws_authenticate

User Stream Data Source¶

connector_name_api_user_stream_data_source.py
- Copy the Bybit perpetual connector user stream data source file.
- Replace Bybit for connector_name with the first letter in uppercase.
- Replace bybit for connector_name.
- Replace the HEARTBEAT_TIME_INTERVAL with the appropriate value.
- Check if you need LISTEN_KEY_KEEP_ALIVE_INTERVAL.
test_connector_name_api_user_stream_data_source.py
- Copy the Binance the test of the user stream data source file.
- Replace Binance for connector_name with the first letter in uppercase.
- Replace binance for connector_name.
Now we are going to start implementing the functionalities of the User Stream Data source but in a TDD way.
Methods development
- WEBSOCKET
  
  If you need Listen Key:
  - get_listen_key
    - test_get_listen_key_log_exception
    - _get_listen_key
    - test_get_listen_key_successful
    - test_ping_listen_key_log_exception
    - _ping_listen_key
    - test_ping_listen_key_successful
    - test_manage_listen_key_task_loop_keep_alive_failed
    - _manage_listen_key_task_loop
    - test_manage_listen_key_task_loop_keep_alive_successful
  - listen_for_user_stream
    - test_listen_for_user_stream_get_listen_key_successful_with_user_update_event
    - listen_for_user_stream (is in the superclass)
    - _connected_websocket_assistant
    - _subscribe_channels
    - _get_ws_assistant
    - _on_user_stream_interruption
    - test_listen_for_user_stream_does_not_queue_empty_payload
    - test_listen_for_user_stream_connection_failed
    - test_listen_for_user_stream_iter_message_throws_exception