Spot 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¶

Endpoint	Required	Type	Description
GET ACTIVE MARKETS	True	Public REST	Endpoint to get the list of active trading pairs (this is sometimes referred to as "tokens info"). (example)
GET LAST TRADED PRICE	True	Public REST
GET ORDERBOOK SNAPSHOT	True	Public REST
[TR] MINIMUM NOTIONAL SIZE	Conditionally	Public REST	Endpoint to get trading rules. (example)
[TR] MINIMUM ORDER SIZE	Conditionally	Public REST	Endpoint to get trading rules. (example)
[TR] MINIMUM PRICE	Conditionally	Public REST	Endpoint to get trading rules. (example)
[TR] ORDER INCREMENT	Conditionally	Public REST	Endpoint to get trading rules. (example)
PING ENDPOINT	True	Public REST	In general any endpoint returning a low amount of information could serve for this purpose, but a ping or time endpoint would be ideal. (example)
GET ACCOUNT BALANCE	True	Private REST	Endpoint to get the current account balance. (example)
GET ORDER STATUS BY client order id	Conditionally	Private REST
GET ORDER STATUS BY exchange_order_id	Conditionally	Private REST
GET TRADES HISTORY BY ORDER ID	Conditionally	Private REST
GET TRADES HISTORY BY TIMESTAMPS	Conditionally	Private REST
GET OPEN ORDERS	True	Private REST	Endpoint to get active orders (example)
CREATE ORDERS	True	Private REST	Endpoint to create new orders (example)
CREATE ORDERS with client_order_id	Conditionally	Private REST	Endpoint to create new orders (example)
CANCEL ORDER BY exchange_order_id	True	Private REST
CANCEL ORDER BY client order id	Conditionally	Private REST
ORDERBOOK CHANNEL (Min depth 100)	True	Public Websocket	Public orders channel (example)
ORDERBOOK DIFF CHANNEL	Conditionally	Public Websocket	Public orders channel (example)
USER ORDER/TRADES CHANNEL	True	Private Websocket	Private orders updates channel (example) Private orders updates channel (example)]
USER BALANCE CHANNEL (total and available balance)	False	Private Websocket	Private balance events channel (if not present the connector has to be configured to estimate balance based on the connector activity) (example)
AUTHENTICATION	True	Other	Class that provides the logic for the web assistant to correctly configure authenticated requests to the exchange (private endpoint). It should be a subclass of AuthBase (example)
Rate limits	True	Other	Documentation of the rate limits applied for each endpoint and global limits for each IP/connection. (example)
SERVER TIME	Conditionally	Public REST

Directory Setup¶

Connector¶

Create connector folder inside hummingbot/hummingbot/connector/exchange called connector_name.

Note

connector_name = the name of the connector in lowercase and separated with underscores if applies.

Example without underscore: binance
Example with underscore: crypto_com

Create the following files inside of the connector folder:

init.py
connector_name_api_order_book_data_source.py
connector_name_api_user_stream_data_source.py
connector_name_auth.py
connector_name_constants.py
connector_name_exchange.py
connector_name_order_book.py
connector_name_utils.py
connector_name_web_utils.py
dummy.pxd
dummy.pyx

Tests¶

Create test folder dwad inside hummingbot/test/hummingbot/exchange called connector_name.

Create the following files inside of the test folder:

init.py
test_connector_name_api_order_book_data_source.py
test_connector_name_api_user_stream_data_source.py
test_connector_name_auth.py
test_connector_name_exchange.py
test_connector_name_order_book.py
test_connector_name_utils.py
test_connector_name_web_utils.py

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.
RATE_LIMITS
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 Binance connector web_utils file.
- Replace Binance for connector_name with the first letter in uppercase.
- Replace binance for connector_name.
- 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 Binance connector utils file.
- Replace Binance for connector_name with the first letter in uppercase.
- Replace binance for connector_name.
- Replace DEFAULT_FEES with the appropriate values .
- Check if you need connection to other domains or delete it.

Order Book¶

connector_name_order_book.py
- Copy the Binance connector order book file.
- Replace Binance for connector_name with the first letter in uppercase.
- Replace binance for connector_name.
For now we will not implement any method, the only purpose of this step because we need to import this class in the connector_name_api_order_book_data_source.py and we don’t want to have errors.

Order Book Data Source¶

connector_name_api_order_book_data_source.py
- Copy the Binance connector order book data source file.
- Replace Binance for connector_name with the first letter in uppercase.
- Replace binance for connector_name.
- Replace the HEARTBEAT_TIME_INTERVAL with the appropriate value.
test_connector_name_api_order_book_data_source.py
- Copy the Binance the test of the order book 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 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
      - ExchangeOrderBook.snapshot_message_from_exchange
      - test_get_new_order_book_raises_exception
  - WEBSOCKET
    - listen_for_subscriptions
      - test_listen_for_subscriptions_subscribes_to_trades_and_order_diffs
      - listen_for_subscriptions
      - _subscribe_channels
      - _process_websocket_messages
      - 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
      - listen_for_trades
      - _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

Auth¶

connector_name_auth.py
- Copy the Binance connector auth file.
- Replace Binance for connector_name with the first letter in uppercase.
test_connector_name_auth.py
- Copy the Binance the test of the auth file.
- Replace Binance for connector_name with the first letter in uppercase.
- Replace binance 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 Binance connector user stream data source file.
- Replace Binance for connector_name with the first letter in uppercase.
- Replace binance 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