SDK Reference

The published contract for AlphaProve strategy code: the strategy_sdk.v1 surface. v1.0.0 is frozen: minor versions add only, never remove (see the version policy note below and strategy_sdk/SUPPORTED.txt).

In the AlphaProve editor these names (Signal, StrategyContext, Indicators, CandleSeries, ...) are pre-injected into your namespace by the sandbox executor. User-submitted code MUST NOT import them. Imports are blocked by the AST validator. The signatures below are exactly what the in-editor IntelliSense mirrors.

How this page is generated

This reference is rendered statically from the published type contract (packages/strategy_sdk/v1/__init__.pyi and errors.py) via mkdocstrings. The docs build performs no import of the engine runtime, so the signatures here are the frozen contract, not whatever the engine happens to expose today.

Core types

The single argument to evaluate(ctx) is a StrategyContext; its return value is an optional Signal.

Strategy SDK v1.0.0 — runtime exports.

This module is the published runtime surface for user strategy code AND the engine's own in-process sandbox path. Names re-exported here are the contract: Signal, StrategyContext, Indicators, CandleSeries, Portfolio, Position, TimeframeView, Candle.

The companion __init__.pyi describes the published types for static analysers / Monaco IntelliSense; at runtime Python uses this file and consumers get the concrete engine classes by identity.

v1.0.0 is an honest mirror of the engine's current surface (uppercase Direction, indicator-by-pd.Series signatures, ...). Future minor versions may curate from Langfuse runtime_attr_error:<attr> data; those revisions land as v1.1.0+ ADDITIONS — never breaking removals.

StrategyContext

Bases: Protocol

current_time instance-attribute

current_time: datetime

symbol instance-attribute

symbol: str

timeframe instance-attribute

timeframe: str

bar_index instance-attribute

bar_index: int

current_bar instance-attribute

current_bar: Candle

candles instance-attribute

candles: CandleSeries

indicators instance-attribute

indicators: Indicators

latest_funding_rate instance-attribute

latest_funding_rate: Optional[float]

cvd_offset instance-attribute

cvd_offset: float

htf instance-attribute

htf: Dict[str, TimeframeView]

portfolio instance-attribute

portfolio: Portfolio

state instance-attribute

state: Dict[str, Any]

params instance-attribute

params: Mapping[str, Union[int, float, bool]]

risk instance-attribute

risk: Optional[RiskView]

position property

position: Optional[Position]

get_htf

get_htf(timeframe: str) -> TimeframeView

Signal

Signal(direction: Direction, stop_loss: Optional[float] = ..., take_profit: Optional[float] = ..., confidence: float = ..., setup_id: str = ..., order_type: OrderType = ..., entry_price: Optional[float] = ..., add_to_position: bool = ..., metadata: Optional[Dict[str, Any]] = ..., max_hold_bars: Optional[int] = ..., trailing_stop_distance: Optional[float] = ..., breakeven_at_profit_pct: Optional[float] = ..., risk_pct: Optional[float] = ...)

direction instance-attribute

direction: Direction

stop_loss instance-attribute

stop_loss: Optional[float]

take_profit instance-attribute

take_profit: Optional[float]

confidence instance-attribute

confidence: float

setup_id instance-attribute

setup_id: str

order_type instance-attribute

order_type: OrderType

entry_price instance-attribute

entry_price: Optional[float]

add_to_position instance-attribute

add_to_position: bool

metadata instance-attribute

metadata: Dict[str, Any]

max_hold_bars instance-attribute

max_hold_bars: Optional[int]

trailing_stop_distance instance-attribute

trailing_stop_distance: Optional[float]

breakeven_at_profit_pct instance-attribute

breakeven_at_profit_pct: Optional[float]

risk_pct instance-attribute

risk_pct: Optional[float]

CandleSeries

Bases: Protocol

open property

open: Series

high property

high: Series

low property

low: Series

close property

close: Series

volume property

volume: Series

delta property

delta: Series

buy_volume property

buy_volume: Series

sell_volume property

sell_volume: Series

trade_count property

trade_count: Series

df property

df: DataFrame

Candle

occurred_at instance-attribute

occurred_at: datetime

instrument_id instance-attribute

instrument_id: str

timeframe instance-attribute

timeframe: str

open instance-attribute

open: float

high instance-attribute

high: float

low instance-attribute

low: float

close instance-attribute

close: float

volume instance-attribute

volume: float

buy_volume instance-attribute

buy_volume: float

sell_volume instance-attribute

sell_volume: float

trade_count instance-attribute

trade_count: int

delta instance-attribute

delta: float

Indicators

Bases: Protocol

ema

ema(series: Series, period: int) -> pd.Series

sma

sma(series: Series, period: int) -> pd.Series

rsi

rsi(series: Series, period: int = 14) -> pd.Series

atr

atr(high: Series, low: Series, close: Series, period: int = 14) -> pd.Series

cvd

cvd(delta: Series, offset: float = 0.0) -> pd.Series

choppiness

choppiness(high: Series, low: Series, close: Series, period: int = 14) -> pd.Series

williams_fractals

williams_fractals(high: Series, low: Series, width: int) -> Tuple[pd.Series, pd.Series]

bollinger_bands

bollinger_bands(series: Series, period: int = 20, num_std: float = 2.0) -> Tuple[pd.Series, pd.Series, pd.Series]

macd

macd(series: Series, fast: int = 12, slow: int = 26, signal: int = 9) -> Tuple[pd.Series, pd.Series, pd.Series]

stochastic

stochastic(high: Series, low: Series, close: Series, period: int = 14, smooth_k: int = 3, smooth_d: int = 3) -> Tuple[pd.Series, pd.Series]

obv

obv(close: Series, volume: Series, offset: float = 0.0) -> pd.Series

donchian

donchian(high: Series, low: Series, period: int = 20) -> Tuple[pd.Series, pd.Series]

keltner

keltner(high: Series, low: Series, close: Series, period: int = 20, atr_period: int = 10, mult: float = 2.0) -> Tuple[pd.Series, pd.Series, pd.Series]

roc

roc(series: Series, period: int = 12) -> pd.Series

cci

cci(high: Series, low: Series, close: Series, period: int = 20) -> pd.Series

adx

adx(high: Series, low: Series, close: Series, period: int = 14) -> Tuple[pd.Series, pd.Series, pd.Series]

supertrend

supertrend(high: Series, low: Series, close: Series, period: int = 10, mult: float = 3.0) -> Tuple[pd.Series, pd.Series]

wma

wma(series: Series, period: int) -> pd.Series

trima

trima(series: Series, period: int) -> pd.Series

hull_ma

hull_ma(series: Series, period: int) -> pd.Series

efficiency_ratio

efficiency_ratio(series: Series, period: int = 10) -> pd.Series

kama

kama(series: Series, period: int = 10, fast: int = 2, slow: int = 30) -> pd.Series

williams_r

williams_r(high: Series, low: Series, close: Series, period: int = 14) -> pd.Series

mfi

mfi(high: Series, low: Series, close: Series, volume: Series, period: int = 14) -> pd.Series

cmo

cmo(series: Series, period: int = 14) -> pd.Series

stoch_rsi

stoch_rsi(series: Series, period: int = 14, stoch_period: int = 14, smooth_k: int = 3, smooth_d: int = 3) -> Tuple[pd.Series, pd.Series]

tsi

tsi(series: Series, slow: int = 25, fast: int = 13) -> pd.Series

trix

trix(series: Series, period: int = 15, signal: int = 9) -> Tuple[pd.Series, pd.Series]

fisher_transform

fisher_transform(high: Series, low: Series, period: int = 10) -> Tuple[pd.Series, pd.Series]

inverse_fisher_rsi

inverse_fisher_rsi(series: Series, period: int = 14, smooth_period: int = 9) -> pd.Series

vwap

vwap(high: Series, low: Series, close: Series, volume: Series) -> pd.Series

rolling_vwap

rolling_vwap(high: Series, low: Series, close: Series, volume: Series, period: int = 20) -> pd.Series

pivot_points

pivot_points(high: Series, low: Series, close: Series) -> Tuple[pd.Series, pd.Series, pd.Series, pd.Series, pd.Series]

linreg_slope

linreg_slope(series: Series, period: int = 14) -> pd.Series

linreg_forecast

linreg_forecast(series: Series, period: int = 14, ahead: int = 0) -> pd.Series

linreg_r2

linreg_r2(series: Series, period: int = 14) -> pd.Series

linreg_channel

linreg_channel(series: Series, period: int = 100, num_std: float = 2.0) -> Tuple[pd.Series, pd.Series, pd.Series]

parabolic_sar

parabolic_sar(high: Series, low: Series, af_start: float = 0.02, af_step: float = 0.02, af_max: float = 0.2) -> Tuple[pd.Series, pd.Series]

divergence

divergence(price: Series, osc: Series, width: int = 2, lookback: int = 90, method: str = 'peaks') -> pd.Series

Portfolio

Bases: Protocol

equity instance-attribute

equity: float

cash instance-attribute

cash: float

sizing_equity instance-attribute

sizing_equity: float

open_orders_count instance-attribute

open_orders_count: int

open_positions property

open_positions: Tuple[Position, ...]

position

position(symbol: str) -> Optional[Position]

Position

Bases: Protocol

symbol instance-attribute

symbol: str

side instance-attribute

side: Literal['LONG', 'SHORT']

qty instance-attribute

qty: float

avg_entry_price instance-attribute

avg_entry_price: float

unrealized_pnl instance-attribute

unrealized_pnl: float

unrealized_pnl_pct instance-attribute

unrealized_pnl_pct: float

opened_at instance-attribute

opened_at: datetime

add_count instance-attribute

add_count: int

bars_since_entry instance-attribute

bars_since_entry: int

stop_loss instance-attribute

stop_loss: Optional[float]

take_profit instance-attribute

take_profit: Optional[float]

size property

size: float

TimeframeView

Bases: Protocol

timeframe instance-attribute

timeframe: str

candles instance-attribute

candles: CandleSeries

indicators instance-attribute

indicators: Indicators

expected_bars instance-attribute

expected_bars: int

Errors

The exception taxonomy a strategy author may except against. The engine raises these; future runtimes wrap their own failures into the same hierarchy so strategy code stays portable.

SDK error taxonomy (v1).

These are user-facing exceptions a strategy author should except against. Engine internals raise them; future Tier-A/Tier-B runtimes wrap their own errors into the same hierarchy so user code is portable across runtimes.

SDKError

Bases: Exception

Base class for every error a v1 strategy may encounter.

InvalidSignal

Bases: SDKError

Signal(...) constructed with values the engine refuses.

IndicatorParamError

Bases: SDKError

An indicator was called with an invalid period / series shape.

DataNotAvailable

Bases: SDKError

The strategy requested data the runtime cannot produce (missing HTF window, no orderbook, etc.).

BudgetExceeded

Bases: SDKError

The strategy exceeded a runtime budget (wall-clock, memory, ...).