Algorithm File

A Ziplime strategy is a Python file with lifecycle functions. You don’t subclass anything: define the functions the engine should call and keep your strategy state on context. The file is imported, so module-level code runs — keep it to imports, constants and definitions.

File skeleton

from ziplime.domain.bar_data import BarData
from ziplime.finance.execution import MarketOrder
from ziplime.trading.trading_algorithm import TradingAlgorithm


async def initialize(context: TradingAlgorithm):
    context.asset = await context.symbol("AAPL")
    context.short_window = 20
    context.long_window = 100


async def handle_data(context: TradingAlgorithm, data: BarData):
    history = await data.history(
        assets=[context.asset],
        fields=["close"],
        bar_count=context.long_window,
    )
    closes = history["close"].to_numpy()

    if len(closes) < context.long_window:
        return

    short_ma = closes[-context.short_window:].mean()
    long_ma = closes.mean()
    target = 1.0 if short_ma > long_ma else 0.0

    await context.order_target_percent(context.asset, target, style=MarketOrder())
    context.record(short_ma=short_ma, long_ma=long_ma)

Importing TradingAlgorithm and BarData is optional; the type hints give your editor completion on context and data.

Hooks

Hook	Required	Define as	Called
`initialize(context)`	In practice, yes	`async def`	Once before the first bar
`handle_data(context, data)`	Yes — without it the strategy never trades	`async def`	On every bar, per `emission_rate`
`before_trading_start(context, data)`	No	`async def`	Once per session, before the open
`compute_signals(context, prices)`	No	`def`	Once, over the whole history, before the first bar
`analyze(context, perf)`	No	`def`	Once, after the run

The engine substitutes a no-op for any hook you leave out.

`initialize(context)`

Use it to:

Look up assets.
Store constants and mutable state on context.
Register scheduled callbacks and configure trading controls.
Mount point-in-time datasets with context.huggingface_dataset(...).
Attach pipelines.
Read configuration from context.algorithm.config.

async def initialize(context):
    context.assets = [
        await context.symbol("AAPL", mic="XNGS"),
        await context.symbol("MSFT@XNGS"),
    ]
    context.max_weight = 0.25

Do not place orders in initialize: there is no current bar yet.

`handle_data(context, data)`

Use it to read current or historical values, calculate signals, check cash, positions and open orders, place or cancel orders, and record metrics.

async def handle_data(context, data):
    current = await data.current(assets=[context.asset], fields=["close", "volume"])
    close = current["close"][0]
    volume = current["volume"][0]

    if volume > 0 and close > context.entry_price:
        await context.order_target_percent(context.asset, 1.0, style=MarketOrder())

    context.record(close=close)

`before_trading_start(context, data)`

Optional, once per session before normal bar processing. Define it async def: every data read is a coroutine, and the engine awaits the hook when it is one. A plain def still runs, but any await data... call inside it is impossible. Use it to reset daily state, read pipeline output or prepare the day’s universe. Orders are disallowed here.

async def before_trading_start(context, data):
    context.traded_this_session = False
    context.universe = await context.universe_symbols("Q500US")

`analyze(context, perf)`

Optional, once after the simulation finishes. perf is a pandas DataFrame with one row per session, including the columns you recorded with context.record(...).

def analyze(context, perf):
    print(perf[["portfolio_value", "returns"]].tail())
    print("Final portfolio value:", perf["portfolio_value"].iloc[-1])

Define analyze with plain def. The engine currently calls it without awaiting, so an async def analyze never runs. (The local MCP server’s check_strategy_code currently asks for async def on every hook — for analyze, follow this page.)

`compute_signals(context, prices)` and `WARMUP`

Optional. Return indicators computed over whole arrays; read them bar by bar through context.signals. Declare how many bars of history they need with a module-level WARMUP. See Vectorized Signals.

WARMUP = 60

def compute_signals(context, prices):
    return {"slow": prices.close.rolling(60).mean()}

Storing state

Use attributes on context for anything that must persist across bars:

async def initialize(context):
    context.last_rebalance_date = None
    context.assets = [await context.symbol("AAPL")]


async def handle_data(context, data):
    context.last_seen_dt = context.get_datetime()

Avoid module-level mutable globals for strategy state: they survive between runs in the same process.

Algorithm configuration

Subclass BaseAlgorithmConfig at module level, and the engine loads it from the JSON file passed as run_simulation(..., config_file=...).

from ziplime.config.base_algorithm_config import BaseAlgorithmConfig


class AlgorithmConfig(BaseAlgorithmConfig):
    symbols: list[str] = ["AAPL", "MSFT"]
    target_weight: float = 0.5


async def initialize(context):
    cfg = context.algorithm.config
    context.assets = [await context.symbol(symbol) for symbol in cfg.symbols]
    context.target_weight = cfg.target_weight

{
  "symbols": ["AAPL", "MSFT", "NVDA"],
  "target_weight": 0.33
}

Dates, capital, bundle, benchmark, calendar, commission and slippage belong to the run, not to the code. Setting them inside the strategy either does nothing or contradicts the run.

Common mistakes

Mistake	Fix
Forgetting `await` on `context.symbol`, `data.current`, `data.history` or an order call	Add `await`. Nothing raises otherwise
Using `.iloc`, `.loc`, `.at` on `data` results	They are Polars frames: `df["close"][-1]`, `df["close"].to_numpy()`
Defining `analyze` as `async def`	Use plain `def analyze(...)`
Placing orders in `initialize` or `before_trading_start`	Place them in `handle_data` or a scheduled callback
Inventing a MIC in `TICKER@MIC`	Use a plain ticker unless you know the venue
Ordering a symbol that isn’t in the bundle	Ingest it first; the run only knows what the bundle holds

Introduction

Writing Strategies

Strategy Language

Migrating to Ziplime

Limitations

File skeleton

Hooks

`initialize(context)`

`handle_data(context, data)`

`before_trading_start(context, data)`

`analyze(context, perf)`

`compute_signals(context, prices)` and `WARMUP`

Storing state

Algorithm configuration

Common mistakes

​File skeleton

​Hooks

​initialize(context)

​handle_data(context, data)

​before_trading_start(context, data)

​analyze(context, perf)

​compute_signals(context, prices) and WARMUP

​Storing state

​Algorithm configuration

​Common mistakes

File skeleton

Hooks

`initialize(context)`

`handle_data(context, data)`

`before_trading_start(context, data)`

`analyze(context, perf)`

`compute_signals(context, prices)` and `WARMUP`

Storing state

Algorithm configuration

Common mistakes