Skip to Content
SDK reference

TypeScript types

The types of answers, requests and stream frames.

Decimal

type Decimal = string

A decimal number as the terminal sends it: "67000.10" stays "67000.10". Never convert it with Number() — bring a decimal library if you need arithmetic.

Timestamp

type Timestamp = number

UTC milliseconds since the epoch, an integer.

InstrumentAddress

type InstrumentAddress = string

Instrument address: exchange:market:symbol, exchange in lower case.

Side

type Side = "buy" | "sell"

Trade side.

Scope

type Scope = "market:read" | "connections:read" | "account:read" | "trading:write" | OpenString

Token scopes known to v1. New scopes may appear within v1.

MarketTopic

type MarketTopic = "trades" | "ticker" | "mark_price" | "book.top" | "clusters"

Market topics: instrument is required on subscribe, connection_id is chosen by the general rule.

AccountTopic

type AccountTopic = "account.orders" | "account.positions" | "account.balances" | "account.fills"

Account topics: connection_id is required on subscribe, instrument is not used.

TerminalTopic

type TerminalTopic = "workspace" | "settings"

The terminal's own topics: one per terminal, subscribed without instrument or connection.

WorkspaceTopic

type WorkspaceTopic = "workspace"

Topic

type Topic = MarketTopic | AccountTopic | TerminalTopic

Stream topics known to v1.

ErrorCode

type ErrorCode = | "unauthorized"
  | "forbidden"
  | "forbidden_scope"
  | "not_found"
  | "invalid_request"
  | "unsupported"
  | "not_active"
  | "rate_limited"
  | "not_tradable"
  | "unavailable"
  | OpenString

Error codes of the contract. New codes may appear within v1.

ConnectionState

type ConnectionState = "disabled" | "enabled" | "connecting" | "connected" | "failed"

status.state of a connection.

OrderType

type OrderType = "limit" | "market"

Order type: limit needs a price, market takes none.

OrderStatus

type OrderStatus = "pending" | "open" | "partially_filled"

Status of an open order.

TriggerType

type TriggerType = "stop_loss" | "take_profit" | "stop"

Kind of a trigger order.

TriggerRule

type TriggerRule = "price_above_or_equal" | "price_below_or_equal"

When a trigger fires.

TriggerStatus

type TriggerStatus = "open" | "finished" | "inactive" | "invalid"

Status of a trigger order.

PositionSide

type PositionSide = "long" | "short"

Side of a position.

TimeInForce

type TimeInForce = "gtc" | "ioc" | "fok" | "post_only"

Time in force of a placed order; absent — the venue's default.

ErrorEnvelope

The error envelope every non-2xx response carries.

FieldTypeDescription
error{ code: ErrorCode; message: string; }

List

Lists are wrapped as { data: [...] }.

FieldTypeDescription
dataT[]

Limits

Limits printed by /v1/meta.

FieldTypeDescription
ws_connections_per_tokennumber
subscriptions_per_connectionnumber
api_only_instrumentsnumber
exchange_subscriptions_per_secondnumber
commands_per_secondoptionalnumberTrading commands per second per listener. Absent on terminals older than the writing stage of the Local API.
workspace_commands_per_secondoptionalnumberWorkspace commands per second per listener. Absent before the window stage.
settings_commands_per_secondoptionalnumberSettings writes per second per listener. Absent before the settings stage.

Meta

GET /v1/meta.

FieldTypeDescription
api_versionstring"1" for this contract.
app_versionstring
build_hashstring
build_envstring
featuresstringEnabled build features, as one string.
scopesScope[]Scopes granted to the token used for the request.
limitsLimits
topicsTopic[]Empty when the terminal was built without the market-data tap.

Health

GET /v1/health.

FieldTypeDescription
statusstring
uptime_msnumber
clientsnumberOpen stream connections.
streamsnumberPairs the hub holds.
api_only_instrumentsnumberPairs opened only for the API.
dropped_eventsnumberEvents the hub did not accept from the market-data loop.
dropped_framesnumberFrames that did not fit into client queues.
overflow_closesnumberClients closed with code 4008.
stream_availablebooleanfalse when the build has no market-data tap.

ConnectionEvent

The last record of a connection's history.

FieldTypeDescription
codestringA code from the same feed the Settings App shows.
tsTimestamp

ConnectionStatus

Connection status derived from the toggle and the history feed.

FieldTypeDescription
stateConnectionState
last_eventoptionalConnectionEventAbsent when the connection has no history record in this session.

Connection

A terminal connection. Carries no secrets: no keys, no address, no mask.

FieldTypeDescription
idnumber
exchangestringExchange name in lower case, as in instrument addresses.
marketstringspot, futures, …
labelstring
enabledboolean
read_onlybooleanA connection without credentials, created by the terminal for market data.
has_credentialsboolean
proxy_boundboolean
statusConnectionStatus

Instrument

An instrument of the exchange catalogue.

FieldTypeDescription
instrumentInstrumentAddress
exchangestring
marketstring
symbolstring
basestring
quotestring
statusstringAs the exchange reported it: active, inactive, …
tick_sizeDecimal | nullnull when the exchange did not report it.
lot_sizeDecimal | null
min_sizeDecimal | null
contract_valueDecimal | null

InstrumentsPage

One page of GET /v1/instruments.

FieldTypeDescription
exchangestring
marketstring
dataInstrument[]
next_cursorstring | nullPass as cursor for the next page; null on the last page.

Candle

A candle; ts is the bar open, volume is in the base coin.

FieldTypeDescription
tsTimestamp
openDecimal
highDecimal
lowDecimal
closeDecimal
volumeDecimal
quote_volumeDecimal
closedboolean

Candles

GET /v1/market/candles.

FieldTypeDescription
instrumentInstrumentAddress
connection_idnumber
intervalstring
dataCandle[]

Interval

An interval the terminal knows; duration_ms is nominal (30 days for 1M).

FieldTypeDescription
idstring
duration_msnumber

Intervals

GET /v1/market/intervals.

FieldTypeDescription
candlesInterval[]
clustersInterval[]

Trade

A trade. ts is when it passed through the terminal.

FieldTypeDescription
idstring | nullExchange trade id; always null in v1.
priceDecimal
qtyDecimal
sideSide
tsTimestamp
exchange_tsTimestamp

Trades

GET /v1/market/trades, oldest to newest.

FieldTypeDescription
instrumentInstrumentAddress
connection_idnumber
dataTrade[]

Level

type Level = [price: Decimal, size: Decimal]

A book level as [price, size].

Ticker

The 24h ticker.

FieldTypeDescription
priceDecimal
change_24h_pctDecimal | null
volume_24hDecimal
high_24hDecimal | null
low_24hDecimal | null
best_bidDecimal | null
best_askDecimal | null
tsTimestamp

MarkPrice

Mark price, the data of a mark_price event.

FieldTypeDescription
mark_priceDecimal
tsTimestamp

Snapshot

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

FieldTypeDescription
instrumentInstrumentAddress
connection_idnumber
tsTimestamp
best_bidLevel | nullFrom the hub's book; null until a book snapshot has arrived.
best_askLevel | null
last_tradeTrade | null
mark_priceDecimal | null
tickerTicker | null

BookTop

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

FieldTypeDescription
tsTimestamp
depthnumber
bidsLevel[]
asksLevel[]

Orderbook

interface Orderbook extends BookTop

GET /v1/market/orderbook.

FieldTypeDescription
instrumentInstrumentAddress
connection_idnumber

ClusterLevel

One price level of a cluster bucket.

FieldTypeDescription
priceDecimal
volumeDecimal
buy_volumeDecimal
sell_volumeDecimal
buy_tradesnumber
sell_tradesnumber

ClusterBucket

A cluster bucket; levels run from the lowest price to the highest.

FieldTypeDescription
intervalstring
tsTimestampBucket start.
end_tsTimestamp
volumeDecimal
buy_volumeDecimal
sell_volumeDecimal
tradesnumber
vwapDecimal | nullnull for a bucket without trades.
min_priceDecimal | null
max_priceDecimal | null
completedboolean
last_trade_tsTimestamp0 for a bucket from history without a trade time.
levelsClusterLevel[]

Clusters

GET /v1/market/clusters, oldest to newest, at most ten buckets.

FieldTypeDescription
instrumentInstrumentAddress
connection_idnumber
intervalstringThe interval selected for the instrument in the terminal.
tsTimestamp
dataClusterBucket[]

Order

An open order of a connection.

FieldTypeDescription
keystring | nullThe terminal's order key (t-…); null while unknown.
exchange_idstring | nullThe exchange's order id; null while unknown.
instrumentInstrumentAddress
sideSide
typeOrderType
priceDecimal
sizeDecimalIn the base coin.
filledDecimal
remainingDecimal
notionalDecimal | nullThe quote amount the trader entered; null for an order from an exchange snapshot.
statusOrderStatus
created_tsTimestamp

TriggerOrder

A trigger order (stop loss, take profit, stop) of a connection.

FieldTypeDescription
idstring
instrumentInstrumentAddress
typeTriggerType
trigger_priceDecimal
ruleTriggerRule
sizeDecimal | null
notionalDecimal | null
statusTriggerStatus
order_typestring | nullThe order placed when the trigger fires; null when unknown.
client_idstring | null
created_tsTimestamp | null

AccountOrders

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

FieldTypeDescription
connection_idnumber
dataOrder[]
triggersTriggerOrder[]

Position

An open position.

FieldTypeDescription
instrumentInstrumentAddress
sidePositionSide
sizeDecimalIn the base coin; on MOEX in lots.
lot_sizeDecimalBase units per lot.
entry_priceDecimal
notionalDecimalIn the quote.
unrealized_pnlDecimalAs the terminal computes it.
mark_priceDecimal | nullThe terminal's mark: best bid for a long, best ask for a short; null until the first book tick.

AccountPositions

GET /v1/account/positions.

FieldTypeDescription
connection_idnumber
dataPosition[]

Balance

The latest balance of one currency, as the exchange reported it.

FieldTypeDescription
currencystring
totalDecimal
availableDecimal | nullnull when the venue does not report it.
lockedDecimal | null
tsTimestampExchange time where there is one, otherwise the receive time.

AccountBalances

GET /v1/account/balances: currencies that changed since the API was switched on.

FieldTypeDescription
connection_idnumber
dataBalance[]

Fill

A fill of the connection's own order.

FieldTypeDescription
trade_idstring
order_idstring
instrumentInstrumentAddress
sideSide
priceDecimal
qtyDecimal
feeDecimal
fee_currencystring
position_sidePositionSide | nulllong / short on hedged venues, otherwise null.
tsTimestamp

AccountFills

GET /v1/account/fills, oldest to newest.

FieldTypeDescription
connection_idnumber
dataFill[]

PlaceOrderRequest

The body of POST /v1/orders as sent on the wire.

FieldTypeDescription
connection_idnumber
instrumentInstrumentAddress
sideSide
typeOrderType
priceoptionalDecimalRequired for limit, absent for market.
sizeoptionalDecimalAmount in the base coin; exactly one of size and notional.
notionaloptionalDecimalThe quote amount; exactly one of size and notional.
reduce_onlyoptionalboolean
post_onlyoptionalboolean
time_in_forceoptionalTimeInForce
client_keyoptionalstringIdempotency key: a repeat with the same key returns the previous answer.

InstrumentCommandRequest

The body of POST /v1/orders/cancel-all, POST /v1/orders/trigger/cancel-all and POST /v1/positions/close.

FieldTypeDescription
connection_idnumber
instrumentInstrumentAddress

PlaceTriggerRequest

The body of POST /v1/orders/trigger. stop_loss and take_profit are placed on the open position (side, size and rule come from it); a stop carries its own side, notional and optional rule.

FieldTypeDescription
connection_idnumber
instrumentInstrumentAddress
kindTriggerType
trigger_priceDecimal
sideoptionalSidestop only.
notionaloptionalDecimalstop only: the quote amount.
ruleoptionalTriggerRulestop only; absent means above the market for a buy, below for a sell.
client_keyoptionalstringIdempotency key, as for POST /v1/orders.

AmendTriggerRequest

The body of PATCH /v1/orders/trigger/{id}: a new trigger price.

FieldTypeDescription
connection_idnumber
instrumentInstrumentAddress
kindTriggerType
trigger_priceDecimal
sideoptionalSidestop only.
ruleoptionalTriggerRulestop only.

LeverageMode

type LeverageMode = "manual" | "max" | "smart"

The terminal's leverage mode of an instrument, not the exchange's.

MarginMode

type MarginMode = "cross" | "isolated"

Margin mode of a futures instrument.

Leverage

GET /v1/account/leverage: leverage and margin mode of one futures instrument, from the terminal's cache. An instrument the terminal has not touched yet answers 409 not_active.

FieldTypeDescription
connection_idnumber
instrumentInstrumentAddress
leveragenumber
max_leveragenumber
modeLeverageMode
margin_modeMarginMode

SetLeverageRequest

The body of POST /v1/account/leverage: exactly one of leverage and mode.

FieldTypeDescription
connection_idnumber
instrumentInstrumentAddress
leverageoptionalnumberAn integer of at least 1.
modeoptional"max" | "smart"

SetMarginModeRequest

The body of POST /v1/account/margin-mode.

FieldTypeDescription
connection_idnumber
instrumentInstrumentAddress
margin_modeMarginMode

Accepted

The answer of every trading command: accepted by the terminal, not by the exchange. The exchange's confirmation, fill or rejection arrives through account.orders in the stream or GET /v1/account/orders.

FieldTypeDescription
acceptedboolean
operation_idstringThe operation in the terminal's operations file.
keystring | nullThe terminal's key under which the order (t-…) or trigger (sl_…, tp_…, stop_…) appears in account.orders; null for cancellations, amendments and leverage.
connection_idnumber
instrumentInstrumentAddress

CellPosition

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

FieldTypeDescription
columnnumber
rownumber
cellnumber

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 null while the stack is empty; position is null for a stack hidden inside a stack group.

FieldTypeDescription
widget_idnumber
instrumentInstrumentAddress | null
connection_idnumber | null
emptyboolean
frozenboolean
positionCellPosition | null

Chart

A chart inside a tab; owner_widget_id is the stack it follows, null when standalone.

FieldTypeDescription
widget_idnumber
instrumentInstrumentAddress | null
connection_idnumber | null
intervalstringCandle interval code (1m, 5m, …).
owner_widget_idnumber | null
positionCellPosition | null

Tab

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

FieldTypeDescription
idnumber
namestring
activeboolean
stacksStack[]
chartsChart[]

WindowGeometry

Window position and size in logical screen pixels.

FieldTypeDescription
xnumber
ynumber
widthnumber
heightnumber
maximizedboolean

Window

A terminal window; main cannot be closed through the API, chart_window is a torn-off chart.

FieldTypeDescription
idnumber
mainboolean
chart_windowboolean
focusedboolean
geometryWindowGeometry
monitorstring | nullThe OS's monitor name, or null.
tabsTab[]

WorkspaceSnapshot

data of GET /v1/workspace and of a workspace event: every window, by ascending id.

FieldTypeDescription
windowsWindow[]

Workspace

GET /v1/workspace. The ids are internal to this run of the terminal.

FieldTypeDescription
dataWorkspaceSnapshot

WorkspaceWindow

GET /v1/workspace/windows/{id}.

FieldTypeDescription
dataWindow

OpenTarget

type OpenTarget = "new_tab" | "new_window"

Where a workspace opening lands.

OpenStackRequest

The body of POST /v1/workspace/stacks.

FieldTypeDescription
instrumentInstrumentAddress
connection_idoptionalnumber
chartoptionalbooleanA chart of the same instrument over the stack.
targetoptionalOpenTargetnew_tab (default) or new_window.
window_idoptionalnumberThe window for a new tab; the focused window when omitted.
activateoptionalbooleanfalse opens the tab in the background; a new window always takes focus.

OpenMultiviewRequest

The body of POST /v1/workspace/multiview.

FieldTypeDescription
basestringA coin (BTC) or a pair (BTC/USDT).
targetoptionalOpenTargetOmitted: the Multiview «open as» setting decides.
window_idoptionalnumber
activateoptionalboolean

TabItemRequest

One column of POST /v1/workspace/tabs and …/tabs/{tab}/stacks: a stack and, with chart, a chart over it.

FieldTypeDescription
instrumentInstrumentAddress
connection_idoptionalnumber
chartoptionalboolean

OpenTabRequest

The body of POST /v1/workspace/tabs: a column per item, one to fifty.

FieldTypeDescription
itemsTabItemRequest[]
nameoptionalstringUp to 64 characters; omitted, the terminal names the tab after the instruments.
targetoptionalOpenTarget
window_idoptionalnumber
activateoptionalboolean

AddStacksRequest

The body of POST /v1/workspace/windows/{id}/tabs/{tab}/stacks.

FieldTypeDescription
itemsTabItemRequest[]

StackInstrumentRequest

The body of PATCH /v1/workspace/stacks/{widget_id}.

FieldTypeDescription
instrumentInstrumentAddress
connection_idoptionalnumber

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 closing and activating: the touched ids, the rest null or empty.

FieldTypeDescription
window_idnumber | null
tab_idnumber | null
stacksnumber[]
chartsnumber[]

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 null for hotkeys; connection_id is the owning connection or null. value is the decoded JSON, numbers as written. writable says whether PATCH /v1/settings accepts the key; a settings stream frame carries no such flag.

FieldTypeDescription
scopestring
scope_idstring | null
connection_idnumber | null
categorystring
keystring
valueunknown
writableoptionalboolean

Settings

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

FieldTypeDescription
dataSettingRow[]

ResolvedFrom

type ResolvedFrom = "instrument" | "connection" | "app_instrument" | "global" | OpenString

The level a stack setting was resolved from.

OrderbookSetting

One stack setting with the level it came from.

FieldTypeDescription
valueunknown
resolved_fromResolvedFrom
writableboolean

OrderbookSettings

GET /v1/settings/orderbook: data[category][key] as the instrument's stack sees them.

FieldTypeDescription
connection_idnumber
instrumentInstrumentAddress
dataRecord<string, Record<string, OrderbookSetting>>

SettingChange

One change of PATCH /v1/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.

FieldTypeDescription
scopeoptional"global" | "order_book"
instrumentoptionalInstrumentAddress
connection_idoptionalnumber
categorystring
keystring
valueunknown

UpdateSettingsRequest

The body of PATCH /v1/settings.

FieldTypeDescription
changesSettingChange[]

SettingsApplied

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

FieldTypeDescription
appliednumber

BookTopParams

Parameters of a book.top subscription; other topics take none. Wire names.

FieldTypeDescription
depthoptionalnumber1–200, default 50.
interval_msoptionalnumberConflation interval, at least 50, default 100.

SubscribeRequest

A subscribe request as sent on the wire.

FieldTypeDescription
type"subscribe"
request_idstring
topicTopic
instrumentoptionalInstrumentAddressRequired for market topics, omitted for account.*.
connection_idoptionalnumberChosen by the general rule for market topics, required for account.*.
paramsoptionalBookTopParams

UnsubscribeRequest

An unsubscribe request as sent on the wire.

FieldTypeDescription
type"unsubscribe"
request_idstring
substring

SubscribedFrame

Server reply to subscribe.

FieldTypeDescription
type"subscribed"
request_idoptionalstring
substringSubscription id, "{stream}:{topic}" ("{connection}:account.<topic>", "workspace"); pass it to unsubscribe.
connection_idoptionalnumberThe connection chosen for market and account topics; absent for workspace.

UnsubscribedFrame

Server reply to unsubscribe.

FieldTypeDescription
type"unsubscribed"
request_idoptionalstring
substring

ErrorFrame

An error frame: with request_id it answers a request, with sub and no request_id it says the server removed that subscription.

FieldTypeDescription
type"error"
request_idoptionalstring
suboptionalstring
codeErrorCode
messagestring

EventFrame

An event frame as it arrives, before the client tags it with its topic.

FieldTypeDescription
type"event"
substring
seqnumberEvent number within the subscription; grows by one for trades.
tsTimestamp
dataT

Gap

A gap frame: events from_seq..to_seq of a trades subscription were lost.

FieldTypeDescription
type"gap"
substring
from_seqnumber
to_seqnumber
reasonstring

SubscriptionError

The server removed a subscription (an error frame with sub, no request_id).

FieldTypeDescription
type"error"
substring
codeErrorCode
messagestring

Subscribed

interface Subscribed extends SubscribedFrame

What subscribe resolves with: the subscribed frame plus what was asked for.

FieldTypeDescription
topicTopic
instrumentoptionalInstrumentAddressAbsent for account.* subscriptions.

OrdersUpdate

data of an account.orders event: orders and triggers of one instrument after a change.

FieldTypeDescription
instrumentInstrumentAddress
ordersOrder[]
triggersTriggerOrder[]

PositionUpdate

data of an account.positions event; a close arrives as position: null.

FieldTypeDescription
instrumentInstrumentAddress
positionPosition | null

TradesEvent

interface TradesEvent extends EventFrame<Trade[]>

Every event the client can tag by topic; topic is read from sub (the part after the first colon).

FieldTypeDescription
topic"trades"

TickerEvent

interface TickerEvent extends EventFrame<Ticker>
FieldTypeDescription
topic"ticker"

MarkPriceEvent

interface MarkPriceEvent extends EventFrame<MarkPrice>
FieldTypeDescription
topic"mark_price"

BookTopEvent

interface BookTopEvent extends EventFrame<BookTop>
FieldTypeDescription
topic"book.top"

ClustersEvent

interface ClustersEvent extends EventFrame<ClusterBucket>
FieldTypeDescription
topic"clusters"

AccountOrdersEvent

interface AccountOrdersEvent extends EventFrame<OrdersUpdate>
FieldTypeDescription
topic"account.orders"

AccountPositionsEvent

interface AccountPositionsEvent extends EventFrame<PositionUpdate>
FieldTypeDescription
topic"account.positions"

AccountBalancesEvent

interface AccountBalancesEvent extends EventFrame<Balance>
FieldTypeDescription
topic"account.balances"

AccountFillsEvent

interface AccountFillsEvent extends EventFrame<Fill>
FieldTypeDescription
topic"account.fills"

WorkspaceEvent

interface WorkspaceEvent extends EventFrame<WorkspaceSnapshot>

data of a workspace event: the whole layout; the first frame is the current snapshot.

FieldTypeDescription
topic"workspace"

SettingsEvent

interface SettingsEvent extends EventFrame<SettingRow>

data of a settings event: one written row, without writable.

FieldTypeDescription
topic"settings"

UnknownTopicEvent

interface UnknownTopicEvent extends EventFrame<unknown>

An event of a topic this client version does not know (the contract may add topics within v1). topic is undefined; the raw topic name is the part of sub after the colon.

FieldTypeDescription
topicundefined

Event

type Event = | TradesEvent
  | TickerEvent
  | MarkPriceEvent
  | BookTopEvent
  | ClustersEvent
  | AccountOrdersEvent
  | AccountPositionsEvent
  | AccountBalancesEvent
  | AccountFillsEvent
  | WorkspaceEvent
  | SettingsEvent
  | UnknownTopicEvent

An event frame, discriminated by topic.

StreamFrame

type StreamFrame = Event | Gap | SubscriptionError

What iterating a Stream yields, in arrival order.

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

On this page