Candles
Overview¶
The Candles component allows users to maintains a moving window of data and indicators that can be used in their strategy. It is a vital feature for traders to generate custom OHLCV (Open, High, Low, Close, Volume) candles. It combines historical and real-time data, allowing the creation of real-time custom technical indicators with the use of pandas_ta.
Usage Examples¶
Initializing Candles¶
Create an instance of a candle for BTC-USDT
from Binance Spot:
class InitializingCandlesExample(ScriptStrategyBase):
candles = CandlesFactory.get_candle("binance", "BTC-USDT", "3m")
...
Logging Candles on Tick¶
To log candle data periodically, you can use the on_tick
method:
Multiple Candles Initialization¶
For strategies that require multiple candle intervals or trading pairs, initialize separate instances:
class InitializingCandlesExample(ScriptStrategyBase):
candles_1 = CandlesFactory.get_candle("binance", "BTC-USDT", "3m")
candles_2 = CandlesFactory.get_candle("binance_perpetual", "ETH-USDT", "1m")
...
Relevant Scripts¶
For practical examples of the Candles component in action, visit the following scripts in the Hummingbot codebase:
- download_candles.py
- candles_example
- simple_directional_strategy_example
- advanced_directional_strategy_example
These scripts show how to effectively use the Candles component within trading strategies and data analysis tasks.
Available Exchanges¶
Currently, the following exchanges support the Candles component:
Spot Exchanges¶
- Binance (
binance_spot
) - KuCoin (
kucoin
) - Gate.io (
gate_io
) - AscendEX (
ascendex
)
Perpetual Exchanges¶
- Binance (
binance_perpetual
) - KuCoin (
kucoin_perpetual
) - Gate.io (
gate_io_perpetual
)
To fetch candles from one of these exchanges, apply the connector_name
above in the get_candle
method of CandlesFactory
:
CandlesFactory.get_candle(connector_name: str, trading_pair: str, interval:str = "1m", max_records:int = 500)
Key Methods and Properties¶
Candles Factory¶
The CandlesFactory class creates and returns a Candle object based on the specified connector and trading pair. It has a class method get_candle
which takes in a connector, trading pair, interval, and max_records as parameters.
The CandlesBase
class is the cornerstone for fetching and storing candle data from exchanges. It ensures compatibility across different connectors by utilizing REST and WebSocket connections for data retrieval.
Key Features:
- Inherits from
NetworkBase
, ensuring network reliability and consistency. - Utilizes Rest and WS Assistants for all I/O operations.
- Incorporates a double-ended queue to store candles efficiently.
- Implements the Throttler module for API rate limiting.
Below are the key methods and properties available in a Candles object. See BinancePerpetualsCandles or BinanceSpotCandles for examples.
get_candle
Method¶
A static method from the CandlesFactory
class to obtain candle data:
CandlesFactory.get_candle(connector_name: str, trading_pair: str, interval:str = "1m", max_records:int = 500)
Parameters:
connector_name
: Identifies the data source, likebinance
orbinance_perpetual
.trading_pair
: The trading pair in 'BASE-QUOTE' format, e.g.,BTC-USDT
.interval
: The time interval between candles.max_records
: Maximum number of candles to store.
start
and stop
Methods¶
Essential for initializing and terminating the candle data stream:
start()
: Begin streaming and collecting candle data.stop()
: Terminate the candle data stream.
is_ready
Property¶
Confirms if the candle data set is complete:
candles_df
Property¶
Accesses the latest DataFrame of candle data: