HiveQ Flow API Reference

pip install hiveq-sdk

import hiveq.flow as hf
from hiveq.flow import StrategyConfig
from hiveq.flow.config import AssetType
from hiveq.flow.logger import logger as _get_logger

logger = _get_logger()   # module-level — REQUIRED in every strategy

class BuyAndHold:
    def __init__(self):
        self.bought = False

    def on_start(self, ctx, event):
        ctx.subscribe_bars(ctx.strategy_config.symbols,
                           asset_type=AssetType.EQUITY, interval='1m')
        logger.info(f"[START] subscribed 1m bars for {ctx.strategy_config.symbols}")

    def on_bar(self, ctx, event):
        bar = event.data()                       # -> SigmaBar
        logger.debug(f"[BAR] {bar.symbol} {bar.time} close={bar.close:.2f} bought={self.bought}")
        if not self.bought and ctx.is_flat(bar.symbol):
            logger.info(f"[ENTRY] buying 100 {bar.symbol} at {bar.close:.2f}")
            ctx.buy_order(bar.symbol, quantity=100)
            self.bought = True

    def on_order(self, ctx, event):              # fills come HERE, not on_order_filled
        order = event.data()                     # -> SigmaOrder
        logger.info(f"[ORDER] {order.symbol} status={order.status} filled={order.is_filled}")
        if order.is_filled:
            fill = order.last_fill               # -> SigmaFill

# run_backtest returns a Run HANDLE, not a report directly.
run = hf.run_backtest(
    strategy_configs=[StrategyConfig(name='BuyAndHold', type='BuyAndHold')],
    symbols=['AAPL'],
    start_date='2025-08-01',
    end_date='2025-08-31',
    # declare the data source; the schema also sets the fill model (bars vs ticks)
    data_configs=[{'type': 'hiveq_historical', 'dataset': 'HIVEQ_US_EQ',
                   'schema': ['bars_1m']}],
)

print(f"run {run.run_id} task {run.task_id}")    # returns immediately (silent=True is the default)
run.wait(progress=False)                         # block quietly until terminal — no live progress bar
report = run.report()                            # -> PerformanceReport (the deliverable)
print(report.return_stats.to_string())

class MyStrategy:
    def __init__(self): ...               # per-strategy state
    def on_start(self, ctx, event): ...   # subscribe here
    def on_bar(self, ctx, event): ...     # event.data() -> SigmaBar
    def on_order(self, ctx, event): ...   # fills/rejects/cancels -> SigmaOrder
    def on_position(self, ctx, event):... # event.data() -> SigmaPosition
    def on_timer(self, ctx, event): ...   # event.data() -> TimerEventData
    def on_rollover(self, ctx, event):... # futures contract roll

from hiveq.flow.logger import logger as _get_logger
logger = _get_logger()   # module level — never logging.getLogger(__name__)

# Required coverage:
# on_start -> subscriptions/config (INFO)
# on_bar -> time, price, state, every condition outcome (DEBUG)
# order placement + on_order -> side, quantity, reason, status/fill (INFO)

ctx.subscribe_bars(symbols, asset_type=AssetType.EQUITY, interval='1m')
ctx.subscribe_trades(symbols)     # tick prints  (asset_type defaults to EQUITY)
ctx.subscribe_quotes(symbols)     # bid/ask      (asset_type defaults to EQUITY)
ctx.subscribe_option_snaps('SPY', expiration_type='0dte')  # '0dte' | 'YYYY-MM-DD' | datetime

# futures: by symbol string, or the root= / contract= / continuous= selectors
ctx.subscribe_futures_bars(symbols=['ES.c.0'], interval='1m')
ctx.subscribe_futures_trades(symbols=['ES.c.0'])

# custom / quant signals — data_id must match the 'id' in data_configs
ctx.subscribe_data(data_id='mysignals')   # -> on_custom_data

ctx.buy_order(symbol, quantity, order_type=OrderType.LIMIT, limit_price=px)
ctx.sell_order(symbol, quantity)         # exit long
ctx.short_order(symbol, quantity)        # open short

# sizing helpers (off the current net position)
ctx.close_position(symbol)               # flatten one symbol (no-op if flat)
ctx.order_to_target(symbol, 100)         # signed target: +long / -short / 0
ctx.flatten_all()                        # close every position in this strategy

ctx.cancel_order(order_id)
ctx.modify_order(order_id, limit_price=..., stop_price=...)
ctx.cancel_all_orders(symbol)

ctx.net_position(symbol)   # signed float (+long / -short / 0)
ctx.is_flat(symbol)        # bool
ctx.has_open_order(symbol) # bool
ctx.now()                  # ET datetime   (time is ALWAYS U.S. Eastern)
ctx.set_timer('poll', timedelta(minutes=1))   # fires on_timer

params = ctx.build_executor_params(
    symbol='AAPL', quantity=1000, side='BUY',
    executor_type='POV', participate_pct=10,   # work at 10% of volume
)
handle = ctx.add_executor(params)              # start it (None if it failed)
ctx.executor_state(handle)                     # "PARTIALLY_FILLED" | "FILLED" | ...

# re-target IN PLACE — never add a second executor for the same target:
eid = str(handle.executorID)
ctx.replace_executor_params_by_id(eid, new_params)

event.type        # EventType  (branch on this)
event.data()      # payload object (type depends on event.type)
event.time        # ET datetime
event.ts_event    # int nanoseconds

run.report()          # -> PerformanceReport
run.positions()       # positions over time   (DataFrame)
run.trades()          # executed trades        (DataFrame)
run.daily_returns()   # daily P&L              (DataFrame)
run.tearsheet()                      # -> '<run>.pdf' in the cwd (PDF, the default)
run.tearsheet(output='report.html')  # explicit HTML file (format from the extension)

# silent=True is the DEFAULT — run_backtest deploys and returns the Run immediately:
run = hf.run_backtest(...)
run.wait(progress=False)                          # block quietly until terminal (no tqdm bar)
report = run.report()
# reattach later from any machine (results outlive your Python process):
report = hf.get_run(run.run_id).wait(progress=False).report()

report = run.report()
print(report.return_stats.to_string())   # Sharpe, Sortino, vol, drawdown, win rate

stats = report.summary_stats()           # dict: Sharpe, CAGR, Max Drawdown, ...
html = report.create_tearsheet()         # inline HTML string (Jupyter/Marimo) — to save a file use run.tearsheet()

import hiveq.flow as hf

def zscore(series, window=20):
    """Rolling z-score."""
    import numpy as np
    return (series[-1] - np.mean(series[-window:])) / np.std(series[-window:])

# register once...
hf.push_function(zscore, version="1.0.0", requirements=["numpy"])

# ...then load it back and run it on the platform from anywhere:
fn = hf.load_function("zscore", version="1.0.0")
hf.run_function(fn, [1, 2, 3, 4, 5], window=3, requirements=["numpy"])  # -> value

# Futures: subscribe to a continuous contract; rollover is automatic.
class Breakout:
    def on_start(self, ctx, event):
        ctx.subscribe_futures_bars(symbols=['ES.c.0'], interval='1m')
    def on_rollover(self, ctx, event):
        roll = event.data()   # Rollover: prev_contract -> current_contract

run = hf.run_backtest(
    strategy_configs=[StrategyConfig(name='Breakout', type='Breakout')],
    symbols=['ES.c.0'],
    start_date='2024-01-01', end_date='2024-03-01',
    data_configs=[{'type': 'hiveq_historical', 'dataset': 'HIVEQ_US_FUT',
                   'schema': ['bars_1m']}],
    backtest_config=BacktestConfig(enable_auto_rollover=True),
)

import hiveq.flow as hf
from hiveq.flow import StrategyConfig, BacktestConfig, EngineConfig, AssetType, get_run
from hiveq.flow.config import EventType, EventLogType, OMSType
from hiveq.flow.logger import logger as _get_logger
from hiveq.flow.trading_types import OrderType, OrderSide, OrderStatus, MarketCenter
from hiveq.flow.trading.price_utils import adjust_tick_size, get_min_tick

BacktestConfig(
    initial_capital=1_000_000.0,
    commission=0.001,
    equity_fee=0.0011,        # per share
    futures_fee=0.5,          # per contract
    session_start=None,       # ET "HH:MM"
    session_end=None,
    enable_auto_rollover=False,
    auto_flatten_at_close=False,  # force-close non-option positions at session close
    enable_tca=False,
)

def on_order(self, ctx, event):
    o = event.data()
    if o.is_filled and o.symbol == self.entry_symbol and not self.protected:
        entry = o.avg_px
        ctx.sell_order(o.symbol, quantity=o.filled_qty,
                       order_type=OrderType.STOP,  stop_price=entry * 0.98)
        ctx.sell_order(o.symbol, quantity=o.filled_qty,
                       order_type=OrderType.LIMIT, limit_price=entry * 1.04)
        self.protected = True
    # when one leg fills, cancel_all_orders(symbol) to emulate OCO