Python models

`Level`

class Level(NamedTuple)

One order-book level, the [price, size] pair of the contract.

Field	Type
`price`	`Decimal`
`size`	`Decimal`

`Limits`

Ceilings of the stream and of trading, as printed by /v1/meta.

commands_per_second is the trading-command rate per listener, workspace_commands_per_second the workspace-command rate, settings_commands_per_second the settings-write rate; each is 0 for a terminal older than the stage that added the limit, which prints none because it accepts no such commands.

Field	Type
`ws_connections_per_token`	`int`
`subscriptions_per_connection`	`int`
`api_only_instruments`	`int`
`exchange_subscriptions_per_second`	`int`
`commands_per_second`	`int`
`workspace_commands_per_second`	`int`
`settings_commands_per_second`	`int`

`Meta`

GET /v1/meta: API version, terminal build, token scopes, limits, stream topics.

topics is empty when the terminal was built without the market-data tap; the stream and the market operations then answer unsupported.

Field	Type
`api_version`	`str`
`app_version`	`str`
`build_hash`	`str`
`build_env`	`str`
`features`	`str`
`scopes`	`list[str]`
`limits`	`Limits`
`topics`	`list[str]`

`Health`

GET /v1/health: listener state and the market-data hub counters.

Field	Type
`status`	`str`
`uptime_ms`	`int`
`clients`	`int`
`streams`	`int`
`api_only_instruments`	`int`
`dropped_events`	`int`
`dropped_frames`	`int`
`overflow_closes`	`int`
`stream_available`	`bool`

`LastEvent`

The last record of the connection history: a stage or error code and its time.

Field	Type
`code`	`str`
`ts`	`int`

`ConnectionStatus`

Connection state: disabled, enabled, connecting, connected or failed.

last_event is None when the connection has no history yet.

Field	Type
`state`	`str`
`last_event`	`LastEvent \| None`

`Connection`

One of the terminal's exchange connections. Carries no secrets, not even masked.

Field	Type
`id`	`int`
`exchange`	`str`
`market`	`str`
`label`	`str`
`enabled`	`bool`
`read_only`	`bool`
`has_credentials`	`bool`
`proxy_bound`	`bool`
`status`	`ConnectionStatus`

`Instrument`

A catalogue entry. Steps and minimums are None when the exchange did not report them.

Field	Type
`instrument`	`str`
`exchange`	`str`
`market`	`str`
`symbol`	`str`
`base`	`str`
`quote`	`str`
`status`	`str`
`tick_size`	`Decimal \| None`
`lot_size`	`Decimal \| None`
`min_size`	`Decimal \| None`
`contract_value`	`Decimal \| None`

`Page`

class Page(Generic[T])

One page of a list: data plus the next_cursor for the following page.

exchange and market name the pair the page was listed for. next_cursor is None on the last page.

Field	Type
`data`	`list[T]`
`next_cursor`	`str \| None`
`exchange`	`str`
`market`	`str`

`Interval`

An interval code the terminal knows and its nominal length.

Field	Type
`id`	`str`
`duration_ms`	`int`

`Intervals`

GET /v1/market/intervals: candle and cluster intervals.

Field	Type
`candles`	`list[Interval]`
`clusters`	`list[Interval]`

`Candle`

One bar. ts is the bar open; volume is in the base coin.

Field	Type
`ts`	`int`
`open`	`Decimal`
`high`	`Decimal`
`low`	`Decimal`
`close`	`Decimal`
`volume`	`Decimal`
`quote_volume`	`Decimal`
`closed`	`bool`

`Candles`

GET /v1/market/candles: bars of one instrument and the connection they came through.

Field	Type
`instrument`	`str`
`connection_id`	`int`
`interval`	`str`
`data`	`list[Candle]`

`Trade`

One trade. ts is when it passed through the terminal, exchange_ts the exchange time.

id is always None in v1.

Field	Type
`id`	`str \| None`
`price`	`Decimal`
`qty`	`Decimal`
`side`	`str`
`ts`	`int`
`exchange_ts`	`int`

`Trades`

GET /v1/market/trades: the latest trades of one instrument, oldest first.

Field	Type
`instrument`	`str`
`connection_id`	`int`
`data`	`list[Trade]`

`Ticker`

The 24h ticker. Fields the exchange does not report are None.

best_bid and best_ask here are prices from the ticker feed, not book levels; the book's top is on Snapshot.

Field	Type
`price`	`Decimal`
`change_24h_pct`	`Decimal \| None`
`volume_24h`	`Decimal \| None`
`high_24h`	`Decimal \| None`
`low_24h`	`Decimal \| None`
`best_bid`	`Decimal \| None`
`best_ask`	`Decimal \| None`
`ts`	`int`

`MarkPrice`

A mark_price stream frame: the mark price and its time.

Field	Type
`mark_price`	`Decimal`
`ts`	`int`

`Snapshot`

GET /v1/market/snapshot: the latest the hub knows about one instrument.

best_bid and best_ask are Level pairs from the hub's book, None until a book snapshot has arrived. The other fields are None until their data has arrived.

Field	Type
`instrument`	`str`
`connection_id`	`int`
`ts`	`int`
`best_bid`	`Level \| None`
`best_ask`	`Level \| None`
`last_trade`	`Trade \| None`
`mark_price`	`Decimal \| None`
`ticker`	`Ticker \| None`

`BookTop`

The top of the book: bids from the best downwards, asks from the best upwards.

This is the data of a book.top stream frame; OrderBook adds the instrument and the connection for the HTTP operation.

Field	Type
`ts`	`int`
`depth`	`int`
`bids`	`list[Level]`
`asks`	`list[Level]`

`OrderBook`

class OrderBook(BookTop)

GET /v1/market/orderbook: the top of one instrument's book.

Field	Type
`instrument`	`str`
`connection_id`	`int`

`ClusterLevel`

Volume traded at one price inside a cluster bucket.

Field	Type
`price`	`Decimal`
`volume`	`Decimal`
`buy_volume`	`Decimal`
`sell_volume`	`Decimal`
`buy_trades`	`int`
`sell_trades`	`int`

`Cluster`

One cluster bucket: totals, price range and every level from the lowest price up.

last_trade_ts is 0 for a bucket seeded from history without a trade time. vwap, min_price and max_price are None for a bucket without trades.

Field	Type
`interval`	`str`
`ts`	`int`
`end_ts`	`int`
`volume`	`Decimal`
`buy_volume`	`Decimal`
`sell_volume`	`Decimal`
`trades`	`int`
`vwap`	`Decimal \| None`
`min_price`	`Decimal \| None`
`max_price`	`Decimal \| None`
`completed`	`bool`
`last_trade_ts`	`int`
`levels`	`list[ClusterLevel]`

`Clusters`

GET /v1/market/clusters: the latest buckets of one instrument, oldest first.

interval is the one selected for the instrument in the terminal.

Field	Type
`instrument`	`str`
`connection_id`	`int`
`interval`	`str`
`ts`	`int`
`data`	`list[Cluster]`

`Order`

An open order of a connection: pending, open or partially_filled.

key is the terminal's order key (t-...), exchange_id the exchange's id; either is None while unknown. size, filled and remaining are in the base coin; notional is the quote amount the trader entered, None for an order that came from an exchange snapshot. The JSON key type is order_type here.

Field	Type
`key`	`str \| None`
`exchange_id`	`str \| None`
`instrument`	`str`
`side`	`str`
`order_type`	`str`
`price`	`Decimal \| None`
`size`	`Decimal`
`filled`	`Decimal`
`remaining`	`Decimal`
`notional`	`Decimal \| None`
`status`	`str`
`created_ts`	`int`

`TriggerOrder`

A trigger order: stop_loss, take_profit or stop (trigger_type).

rule is price_above_or_equal or price_below_or_equal; status is open, finished, inactive or invalid. size, notional, order_type, client_id and created_ts are None when the venue did not report them.

Field	Type
`id`	`str`
`instrument`	`str`
`trigger_type`	`str`
`trigger_price`	`Decimal`
`rule`	`str`
`size`	`Decimal \| None`
`notional`	`Decimal \| None`
`status`	`str`
`order_type`	`str \| None`
`client_id`	`str \| None`
`created_ts`	`int \| None`

`AccountOrders`

GET /v1/account/orders: open orders and trigger orders of one connection.

Field	Type
`connection_id`	`int`
`data`	`list[Order]`
`triggers`	`list[TriggerOrder]`

`Position`

An open position. size is in the base coin (lots on MOEX, lot_size base units each).

notional is in the quote; unrealized_pnl and mark_price are the terminal's own (best bid for a long, best ask for a short), None until the first book tick.

Field	Type
`instrument`	`str`
`side`	`str`
`size`	`Decimal`
`lot_size`	`Decimal \| None`
`entry_price`	`Decimal \| None`
`notional`	`Decimal \| None`
`unrealized_pnl`	`Decimal \| None`
`mark_price`	`Decimal \| None`

`AccountPositions`

GET /v1/account/positions: open positions of one connection.

Field	Type
`connection_id`	`int`
`data`	`list[Position]`

`Balance`

The latest balance of one currency.

available and locked are None when the venue does not report them; ts is the exchange time where there is one, otherwise the receive time.

Field	Type
`currency`	`str`
`total`	`Decimal`
`available`	`Decimal \| None`
`locked`	`Decimal \| None`
`ts`	`int`

`AccountBalances`

GET /v1/account/balances: per currency, the latest value since the API came on.

Field	Type
`connection_id`	`int`
`data`	`list[Balance]`

`Fill`

One execution. position_side is long/short on hedged venues, else None.

Field	Type
`trade_id`	`str \| None`
`order_id`	`str \| None`
`instrument`	`str`
`side`	`str`
`price`	`Decimal`
`qty`	`Decimal`
`fee`	`Decimal \| None`
`fee_currency`	`str \| None`
`position_side`	`str \| None`
`ts`	`int`

`AccountFills`

GET /v1/account/fills: the connection's latest fills, oldest first.

Field	Type
`connection_id`	`int`
`data`	`list[Fill]`

`Accepted`

A trading command was accepted by the terminal, not yet by the exchange.

operation_id names the operation in the terminal's operations file; key is the order key (t-...) under which the order will appear in account.orders, None for a cancellation. The exchange's confirmation, fill or rejection arrives through the stream.

Field	Type
`accepted`	`bool`
`operation_id`	`str`
`key`	`str \| None`
`connection_id`	`int`
`instrument`	`str`

`Leverage`

GET /v1/account/leverage: leverage and margin mode of one futures instrument.

Read from the terminal's cache, which the window's instrument selection and set_leverage fill; an instrument the terminal has not touched yet is ApiError not_active. mode is the terminal's leverage mode (manual, max, smart), not the exchange's; margin_mode is cross or isolated.

Field	Type
`connection_id`	`int`
`instrument`	`str`
`leverage`	`int`
`max_leverage`	`int`
`mode`	`str`
`margin_mode`	`str`

`CellPosition`

A cell of a tab's grid: column left to right, row top to bottom, cell within the row.

Field	Type
`column`	`int`
`row`	`int`
`cell`	`int`

`Stack`

A stack — order book with its trade tape and clusters — inside a tab.

widget_id is global for this run of the terminal. instrument and connection_id are None while the stack is empty; position is None for a stack hidden inside a stack group.

Field	Type
`widget_id`	`int`
`instrument`	`str \| None`
`connection_id`	`int \| None`
`empty`	`bool`
`frozen`	`bool`
`position`	`CellPosition \| None`

`Chart`

A chart inside a tab.

owner_widget_id is the stack the chart follows, None when standalone.

Field	Type
`widget_id`	`int`
`instrument`	`str \| None`
`connection_id`	`int \| None`
`interval`	`str`
`owner_widget_id`	`int \| None`
`position`	`CellPosition \| None`

`Tab`

A tab of a window: id is numbered per window from 1, exactly one tab is active.

Field	Type
`id`	`int`
`name`	`str`
`active`	`bool`
`stacks`	`list[Stack]`
`charts`	`list[Chart]`

`Window`

A terminal window; main cannot be closed through the API.

chart_window is a torn-off chart window. The geometry is in logical screen pixels; monitor is the OS's monitor name or None.

Field	Type
`id`	`int`
`main`	`bool`
`chart_window`	`bool`
`focused`	`bool`
`x`	`int`
`y`	`int`
`width`	`int`
`height`	`int`
`maximized`	`bool`
`monitor`	`str \| None`
`tabs`	`list[Tab]`

`Workspace`

GET /v1/workspace and the workspace stream topic: every window, by ascending id.

The ids are internal numbers of this run of the terminal: do not keep them across restarts, read them again.

Field	Type
`windows`	`list[Window]`

`TabItem`

One column of a tab opened or extended through the API.

A stack of instrument on connection_id (the general rule picks one when None) and, with chart, a chart over it.

Field	Type
`instrument`	`str`
`connection_id`	`int \| None`
`chart`	`bool`

`WorkspaceOutcome`

What the window did for a workspace command.

For an opening: the window, the new tab and its stacks and charts in column order; for columns added to a tab only the added widgets. For closing and activating: the touched ids, the rest None or empty.

Field	Type
`window_id`	`int \| None`
`tab_id`	`int \| None`
`stacks`	`list[int]`
`charts`	`list[int]`

`SettingRow`

One row of the terminal's settings table, as stored.

scope is global or order_book; scope_id is default, an instrument address, or None for hotkeys; connection_id is the owning connection or None. value is the decoded JSON (numbers as written). writable says whether update_settings accepts the key; it is None on a settings stream frame, which carries no such flag.

Field	Type
`scope`	`str`
`scope_id`	`str \| None`
`connection_id`	`int \| None`
`category`	`str`
`key`	`str`
`value`	`Any`
`writable`	`bool \| None`

`Settings`

GET /v1/settings: rows as stored, without the default ladder.

Field	Type
`data`	`list[SettingRow]`

`OrderbookSetting`

One stack setting with the level it was resolved from.

resolved_from is instrument (the pair's row on the connection), connection (the connection's default), app_instrument (the pair's row without a connection) or global.

Field	Type
`value`	`Any`
`resolved_from`	`str`
`writable`	`bool`

`OrderbookSettings`

GET /v1/settings/orderbook: one instrument's stack settings as its stack sees them.

Field	Type
`connection_id`	`int`
`instrument`	`str`
`data`	`dict[str, dict[str, OrderbookSetting]]`

`SettingChange`

One change for update_settings.

instrument addresses the pair's row (scope order_book); connection_id with scope="order_book" and no instrument addresses the connection's default; neither addresses the global default. Global settings take no connection.

Field	Type
`category`	`str`
`key`	`str`
`value`	`Any`
`scope`	`str \| None`
`instrument`	`str \| None`
`connection_id`	`int \| None`

`SettingsApplied`

PATCH /v1/settings: how many changes were applied (all of them, or the call raised).

Field	Type
`applied`	`int`

`OrdersUpdate`

An account.orders frame: orders and triggers of one instrument after a change.

Field	Type
`instrument`	`str`
`orders`	`list[Order]`
`triggers`	`list[TriggerOrder]`

`PositionUpdate`

An account.positions frame: one instrument's position; a close is position=None.

Field	Type
`instrument`	`str`
`position`	`Position \| None`

`Subscribed`

Reply to subscribe: the subscription id and the connection chosen for it.

connection_id is None for workspace and settings: neither has a connection.

Field	Type
`sub`	`str`
`connection_id`	`int \| None`
`request_id`	`str \| None`

`Unsubscribed`

Reply to unsubscribe.

Field	Type
`sub`	`str`
`request_id`	`str \| None`

`Event`

A data frame of a subscription.

seq grows by one for trades; for conflated topics gaps in the numbering are normal. data is typed by the topic, see parse_event_data.

Field	Type
`sub`	`str`
`seq`	`int`
`ts`	`int`
`data`	`Any`

`Gap`

Events from_seq..to_seq of a trades subscription were lost.

Arrives before the first frame after the loss; the trades can be re-read with Terminal.trades(..., since_ts=...).

Field	Type
`sub`	`str`
`from_seq`	`int`
`to_seq`	`int`
`reason`	`str`

`SubscriptionError`

The server removed a subscription: the venue refused or the pair could not be subscribed.

A new subscribe starts it again.

Field	Type
`sub`	`str`
`code`	`str`
`message`	`str`

Generated from the code of spectre-terminal at commit 2d1c324.

LevelCopy Anchor Link

LimitsCopy Anchor Link

MetaCopy Anchor Link

HealthCopy Anchor Link

LastEventCopy Anchor Link

ConnectionStatusCopy Anchor Link

ConnectionCopy Anchor Link

InstrumentCopy Anchor Link

PageCopy Anchor Link

IntervalCopy Anchor Link

IntervalsCopy Anchor Link

CandleCopy Anchor Link

CandlesCopy Anchor Link

TradeCopy Anchor Link

TradesCopy Anchor Link

TickerCopy Anchor Link

MarkPriceCopy Anchor Link

SnapshotCopy Anchor Link

BookTopCopy Anchor Link

OrderBookCopy Anchor Link

ClusterLevelCopy Anchor Link

ClusterCopy Anchor Link

ClustersCopy Anchor Link

OrderCopy Anchor Link

TriggerOrderCopy Anchor Link

AccountOrdersCopy Anchor Link

PositionCopy Anchor Link

AccountPositionsCopy Anchor Link

BalanceCopy Anchor Link

AccountBalancesCopy Anchor Link

FillCopy Anchor Link

AccountFillsCopy Anchor Link

AcceptedCopy Anchor Link

LeverageCopy Anchor Link

CellPositionCopy Anchor Link

StackCopy Anchor Link

ChartCopy Anchor Link

TabCopy Anchor Link

WindowCopy Anchor Link

WorkspaceCopy Anchor Link

TabItemCopy Anchor Link

WorkspaceOutcomeCopy Anchor Link

SettingRowCopy Anchor Link

SettingsCopy Anchor Link

OrderbookSettingCopy Anchor Link

OrderbookSettingsCopy Anchor Link

SettingChangeCopy Anchor Link

SettingsAppliedCopy Anchor Link

OrdersUpdateCopy Anchor Link

PositionUpdateCopy Anchor Link

SubscribedCopy Anchor Link

UnsubscribedCopy Anchor Link

EventCopy Anchor Link

GapCopy Anchor Link

SubscriptionErrorCopy Anchor Link

On this page