We provide a few handful functions that allow you to:

  • Create (even fake) candles
  • Store candles in the database
  • Fetch candles from the database
  • Plot candles

They can be quite useful for doing research in Jupyter notebooks or when writing your own custom scripts.


The equivalent to the import candles modeopen in new window in the GUI dashboard.

Useful for operations such as a script to batch-import candles for a list of symbols.

Returns the success message in the string format after a successful import. By default, a progress bar is shown which is helpful in environments such as Jupyter notebooks but it can be disabled by setting show_progress_bar to False.

import_candles(exchange, symbol, start_date, show_progressbar=True)


  • exchange: str
  • symbol: str
  • start_date: str
  • show_progressbar: bool (default: True)

Return Type: str


Stores candles in the database. The stored data can later be used for being fetched again via get_candles or even for running backtests on them.

A common use case for this function is for importing candles from a CSV file so you can later use them for backtesting.

store_candles(candles, exchange, symbol)


Jesse uses 1m timeframe candles and generates others as needed on the fly. So the candles you pass to this function must be in the 1m timeframe.


  • candles: str
  • exchange: str
  • symbol: str

Return Type: None


Fetches candles from the database and returns them as a numpy array with the same structure that Jesse's self.candles does.

get_candles(exchange, symbol, timeframe, start_date, finish_date)


  • exchange: str
  • symbol: str
  • timeframe: str (supported: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 3h, 4h, 6h, 1D)
  • start_date: str
  • finish_date: str

Return Type: np.ndarray


eth_candles = research.get_candles('Binance', 'ETH-USDT', '4h', '2019-07-28', '2019-09-28')

# array([
#     1.56427200e+12, # timestamp 
#     2.07300000e+02, # open
#     2.07750000e+02, # close
#     2.08230000e+02, # high
#     2.06170000e+02, # low
#     2.15143531e+04 # volume
# ])


Generates a fake candle. If attributes are passed, then it'll create using those values. Else, it will generate one.

If reset is passed as True, then all values including timestamp will be reset (and no longer will look like a price series)

candlestick_chart(attributes, reset)


  • attributes: dict
  • reset: bool = False

Return Type: np.ndarray


# example without attributes
c1 = research.fake_candle()
# output:
# [1.60945986e+12 9.70000000e+01 1.02000000e+02 1.02000000e+02
#  9.60000000e+01 2.20000000e+01]

# example with attributes
c2 = research.fake_candle({
    'timestamp': 1643104557000,
    'open': 10,
    'close': 11,
    'high': 12,
    'low': 8,
    'volume': 200,
# output:
# [1.64310456e+12 1.00000000e+01 1.10000000e+01 1.20000000e+01
#  8.00000000e+00 2.00000000e+02]

See Also: fake_range_candles, candles_from_close_prices


Similar to fake_candle, but generates a range of candles as many as you pass.



  • count: int

Return Type: np.ndarray


range_candles = research.fake_range_candles(3)
# output:
# [[1.60945920e+12 1.06000000e+02 1.09000000e+02 1.09000000e+02
#   1.05000000e+02 9.70000000e+01]
#  [1.60945926e+12 1.09000000e+02 1.10000000e+02 1.10000000e+02
#   1.08000000e+02 1.50000000e+01]
#  [1.60945932e+12 1.10000000e+02 1.17000000e+02 1.17000000e+02
#   1.09000000e+02 2.00000000e+00]]

See Also: fake_candle, candles_from_close_prices


Generates a numpy array of candles from a list of close prices.

This is very helpful for when you have a range of close prices, and intend to run backtest on them. Because backtesting requires you to have candles (and not merely close prices), you can use this function to generate candles from close prices.

The first candle has the timestamp of 1609459200000 (2021-01-01T00:00:00+00:00) and after that, each has the timestamp of the previous candle plus 1 minute.



  • prices: list

Return Type: np.ndarray


close_prices = [10, 11, 12, 12, 11, 13, 14, 12, 11, 15]
np_candles = research.candles_from_close_prices(close_prices)

# output:
# [[1.60945920e+12 9.50000000e+00 1.00000000e+01 1.00000000e+01
#   9.50000000e+00 1.00000000e+02]
#  [1.60945926e+12 1.00000000e+01 1.10000000e+01 1.10000000e+01
#   1.00000000e+01 2.80000000e+01]
#  [1.60945932e+12 1.10000000e+01 1.20000000e+01 1.20000000e+01
#   1.10000000e+01 1.30000000e+02]
#  [1.60945938e+12 1.20000000e+01 1.20000000e+01 1.20000000e+01
#   1.20000000e+01 7.50000000e+01]
#  [1.60945944e+12 1.20000000e+01 1.10000000e+01 1.20000000e+01
#   1.10000000e+01 1.51000000e+02]
#  [1.60945950e+12 1.10000000e+01 1.30000000e+01 1.30000000e+01
#   1.10000000e+01 5.10000000e+01]
#  [1.60945956e+12 1.30000000e+01 1.40000000e+01 1.40000000e+01
#   1.30000000e+01 1.68000000e+02]
#  [1.60945962e+12 1.40000000e+01 1.20000000e+01 1.40000000e+01
#   1.20000000e+01 2.20000000e+01]
#  [1.60945968e+12 1.20000000e+01 1.10000000e+01 1.20000000e+01
#   1.10000000e+01 1.44000000e+02]
#  [1.60945974e+12 1.10000000e+01 1.50000000e+01 1.50000000e+01
#   1.10000000e+01 1.80000000e+02]]

See Also: fake_candle, fake_range_candles


Displays a candlestick chart from candles in numpy array format (which is the default for Jesse).



  • candles: np.ndarray

Return Type: None


# generate fake candles from close prices
close_prices = [10, 11, 12, 12, 11, 13, 14, 12, 11, 15]
np_candles = research.candles_from_close_prices(close_prices)


Which would display: