OPBT SDK · 03

Data API

On this page

Data API

Every data API exposes only information available by the current simulation time and returns a pandas DataFrame indexed by UTC timestamps. Missing data raises DataNotPrefetched — check your universe and __data__ declaration.

history#

ctx.history(instrument, fields='close', window=100, freq=None) → DataFrame

At most window real completed observations before the decision. The UTC ts index may contain time gaps for listings or missing/no-trade slots; rows are never padded or forward-filled, so strategies that require continuity must inspect index spacing.

Parameter	Default	Description
instrument	—	e.g. binance:UPERP:BTCUSDT
fields	'close'	open/high/low/close/volume/turnover, string or list
window	100	maximum real observations
freq	run frequency	Backtest may use a declared coarser frequency; Paper/Live require the decision frequency

ctx.history_many(instruments=None, fields='close', window=100, freq=None) → dict[str, DataFrame]

Read completed history for multiple instruments in one bounded call. Every frame follows history's sparse UTC ts semantics independently; instruments need not share identical row timestamps.

ctx.klines(instrument, freq=None, lookback=100) → DataFrame

Canonical completed OHLCV + turnover observations in every mode, with the same sparse, never-padded UTC ts contract as history. Bar callback DTOs separately retain the quote_volume field name.

ctx.bbo(instrument) / ctx.orderbook(instrument) → BboSnapshot

Returns the current best bid and ask, not a full-depth order book. Backtest has no historical BBO archive, so it exposes the latest completed-bar close as a BAR_PROXY; this is useful for portable Strategy code but does not affect the separate backtest fill model. Paper and Live read a current OnePort BBO. Invalid or stale OnePort quotes are unavailable and cannot be used for an order. select_universe is PIT-history-only, so BBO/orderbook calls are rejected there in every mode.

funding_history#

ctx.funding_history(instrument, window=30) → DataFrame

Settled funding rates. Columns: rate (positive = longs pay shorts, normalized across venues), interval_hours (the venue's actual interval). Indexed by settlement time.

Versioned datasets#

ctx.data.history(alias, entity, fields=None, window=100) → DataFrame

Read one frozen dataset alias and entity with a UTC time index. Calls may only narrow fields declared in __data__.datasets; Factor Evaluation uses the identical factor_ctx.data method.

ctx.data.history_many(alias, entities=None, fields=None, window=100) → dict[str, DataFrame]

Bounded multi-entity read. ctx.data.latest returns zero or one row, while ctx.data.status returns the frozen identity and time semantics. The per-entity limit is 100,000 rows and one response is capped at 250,000 rows.

Availability by execution mode#

Surface	Backtest	Paper	Live
history · history_many · klines	UTC ts	UTC ts	UTC ts
bbo · orderbook	BAR_PROXY · completed close	OnePort BBO	OnePort BBO
ctx.accounts · order_status · open_orders	Available	Available	Available
ctx.data · versioned SERIES	Available	Available	Available
ADL history	Historical only	Rejected	Rejected

Properties#

ctx.now	current simulation timestamp at bar close
ctx.universe	instrument tuple
ctx.frequency	run frequency
ctx.data_quality	immutable opr.data-quality.v1 evidence for the current boundary
ctx.params	custom parameters passed at submission
ctx.state	durable attribute namespace, finite-JSON values, max 256 KiB

python

ctx.state.held = getattr(ctx.state, "held", {})
missing = ctx.data_quality["missing"]
status = ctx.data_quality["status"]

# For algorithms that modify the array in place:
values = frame["close"].to_numpy(copy=True)

History APIs return pandas DataFrames. Under pandas Copy-on-Write, .values and .to_numpy() may return read-only views. Request copy=True when an algorithm needs a writable array; never force shared arrays writable. For cross-sectional work, history_many batches reads without changing PIT rules or bypassing runtime limits.