STX

The STX client. Configuration comes from the options, then environment variables, then a profile in ~/.stx/credentials:

const client = new STX();
const me = await client.me();
const page = await client.markets({ status: "open", limit: 10 });

Constructor

new STX(opts?: STXOptions)

Parameter	Type	Description
opts (optional)	STXOptions
opts.env (optional)	string | null	"production" or "demo" ("prod" and "live" are accepted).
opts.environment (optional)	string | STXEnvironment	A published environment, Environments.OntarioDemo, or its name, "ontario-demo". Instead of region + env; host still wins.
opts.fetch (optional)	FetchLike	Inject a fetch implementation (tests, proxies).
opts.geoLocation (optional)	GeoLocationProvider	A geolocation packet, or a function returning one, sent as geo_location with every order write. Only needed where the exchange is geo-fenced and this machine’s IP address is not whitelisted for the account.
opts.host (optional)	string | null	A hostname or URL, overriding region/env: "demo.stxapp.ca", "http://localhost:4000".
opts.keyId (optional)	string | null	The API key ID.
opts.onResponse (optional)	(event: ResponseEvent) => void	Called once per HTTP attempt, after it completes or fails: an audit or activity log hook. Never throws into the request; an exception here is swallowed.
opts.privateKey (optional)	PrivateKeyInput | null	The Ed25519 private key: PEM text, a path to a PEM file, PEM bytes, or a KeyObject.
opts.profile (optional)	string | null	A section of ~/.stx/credentials to read.
opts.region (optional)	string | null	A known region, e.g. "ontario" or "us". With env, picks the host.
opts.retry (optional)	RetryPolicy	A RetryPolicy; NO_RETRY disables retries.
opts.signer (optional)	Signer	Instead of privateKey: signs message bytes, for keys in an HSM or KMS.
opts.timeoutMs (optional)	number	Milliseconds per HTTP request. Default 30000.
opts.verifyTls (optional)	boolean | null	Set false only for a local server. Honoured by the WebSocket; for HTTP requests, pass a fetch whose dispatcher skips verification (Node’s global fetch has no per-call switch).

Properties

Property	Type	Description
baseUrl	string
credentials	ApiKeyCredentials | undefined	The API key, when one is configured.
geoLocation	GeoLocationProvider | undefined
onResponse	(event: ResponseEvent) => void | undefined
profile	string
retry	RetryPolicy
socketUrl	string
timeoutMs	number
verifyTls	boolean

Methods

acceptTerms()

acceptTerms(deviceId: string, opts?: AcceptTermsOptions): Promise<string>

POST /api/v1/tnc/accept: accept the current terms. Resolves to the server’s message.

Parameter	Type	Description
deviceId	string
opts (optional)	AcceptTermsOptions
opts.acceptHouseRules (optional)	boolean
opts.acceptPrivacy (optional)	boolean
opts.acceptTerms (optional)	boolean

Returns Promise<string>.

accountMarketStats()

accountMarketStats(query?: MarketStatsQuery): Promise<Page<MarketStat>>

GET /api/v1/account/market_stats: your exposure and P&L per market. Not the market_stats WebSocket channel, which carries price history.

Parameter	Type	Description
query (optional)	MarketStatsQuery
query.competitions (optional)	StrList
query.cursor (optional)	string
query.eventIds (optional)	StrList
query.excludeZeroSettlements (optional)	boolean
query.fromTime (optional)	number
query.limit (optional)	number
query.marketIds (optional)	StrList
query.sports (optional)	StrList
query.toTime (optional)	number

Returns Promise<Page<MarketStat>>.

adjustments()

adjustments(query?: PageQuery): Promise<Page<PaymentTransaction>>

GET /api/v1/portfolio/adjustments: manual balance adjustments.

Parameter	Type	Description
query (optional)	PageQuery
query.cursor (optional)	string
query.limit (optional)	number

Returns Promise<Page<PaymentTransaction>>.

balance()

balance(): Promise<Balance>

GET /api/v1/account/balance: balance, liabilities and fee schedule. The same object the balances channel pushes.

Returns Promise<Balance>.

cancelAllOrders()

cancelAllOrders(opts?: GeoOption): Promise<Cancellation[]>

DELETE /api/v1/orders/all: cancel everything resting on the account.

Parameter	Type	Description
opts (optional)	GeoOption
opts.geoLocation (optional)	string | null	Overrides the client’s geoLocation for this call; null sends none.

Returns Promise<Cancellation[]>.

cancelOrder()

cancelOrder(orderId: string, opts?: GeoOption): Promise<Cancellation>

DELETE /api/v1/orders/{order_id}: request a cancel. A cancel is a request: a fill already in flight can still land.

Parameter	Type	Description
orderId	string
opts (optional)	GeoOption
opts.geoLocation (optional)	string | null	Overrides the client’s geoLocation for this call; null sends none.

Returns Promise<Cancellation>.

cancelOrders()

cancelOrders(orderIds: readonly string[], opts?: GeoOption): Promise<Cancellation[]>

DELETE /api/v1/orders/batched: cancel the named orders.

Parameter	Type	Description
orderIds	readonly string[]
opts (optional)	GeoOption
opts.geoLocation (optional)	string | null	Overrides the client’s geoLocation for this call; null sends none.

Returns Promise<Cancellation[]>.

close()

close(): Promise<void>

Nothing to release (fetch pools connections itself); present so await using and explicit cleanup work.

Returns Promise<void>.

createMarkets()

createMarkets(eventId: string, markets: readonly NewMarketInput[], opts?: CreateMarketsOptions): Promise<CreateMarketResult[]>

POST /api/v1/markets: create player-prop markets on a scheduled event, up to MAX_MARKETS_PER_REQUEST per call. Needs an OAuth app token with markets.write, which STX grants, from the client’s IP allow-list.

Returns one result per market, in order: created or exists (both with market_id), or rejected with a reason. A rejected market is a result, not an error, and resending is safe: a market that is already listed comes back exists. A refused request throws (403 without markets.write, 404 unknown event, 422 event not open).

Each line must be a positive number ending in .5, e.g. 18.5. More than MAX_MARKETS_PER_REQUEST markets throws TypeError before any request. validate also needs the events scope.

Parameter	Type	Description
eventId	string
markets	readonly NewMarketInput[]
opts (optional)	CreateMarketsOptions
opts.validate (optional)	boolean	Check each market against the event’s players and stats, and the line rule, before sending. Failing markets come back rejected without a request; the rest are sent with the event’s own stat key. The exchange checks every market either way. Reads eventPlayers(), so the token also needs the events scope.

Returns Promise<CreateMarketResult[]>.

deposits()

deposits(query?: PageQuery): Promise<Page<PaymentTransaction>>

GET /api/v1/portfolio/deposits.

Parameter	Type	Description
query (optional)	PageQuery
query.cursor (optional)	string
query.limit (optional)	number

Returns Promise<Page<PaymentTransaction>>.

eventPlayers()

eventPlayers(eventId: string): Promise<EventPlayers>

GET /api/v1/events/{event_id}/players: the event’s team rosters and the stats a market on it can use. teams is empty until the rosters are published. Needs an OAuth app token with events, or an API key.

Parameter	Type	Description
eventId	string

Returns Promise<EventPlayers>.

events()

events(query?: EventsQuery): Promise<Page<Event>>

GET /api/v1/events: one page of events.

Parameter	Type	Description
query (optional)	EventsQuery
query.competitions (optional)	StrList
query.cursor (optional)	string
query.eventIds (optional)	StrList
query.eventTypes (optional)	StrList
query.limit (optional)	number
query.promoted (optional)	boolean
query.sortBy (optional)	string	"start_time".
query.sortDirection (optional)	"asc" | "desc"
query.sports (optional)	StrList
query.status (optional)	string	scheduled, in_progress, completed or cancelled.
query.title (optional)	string

Returns Promise<Page<Event>>.

fees()

fees(query?: PageQuery): Promise<Page<FeeTransaction>>

GET /api/v1/portfolio/fees: fee and fee-refund entries.

Parameter	Type	Description
query (optional)	PageQuery
query.cursor (optional)	string
query.limit (optional)	number

Returns Promise<Page<FeeTransaction>>.

fills()

fills(query?: FillsQuery): Promise<Page<Fill>>

GET /api/v1/fills: one page of your executions.

Parameter	Type	Description
query (optional)	FillsQuery
query.cursor (optional)	string
query.limit (optional)	number
query.marketIds (optional)	StrList
query.orderIds (optional)	StrList
query.status (optional)	string	created, open, settled or cancelled.

Returns Promise<Page<Fill>>.

geoCheck()

geoCheck(opts?: GeoOption): Promise<GeoCheckResult>

Ask the exchange whether this machine may trade right now, without placing or cancelling anything.

Sends DELETE /api/v1/orders/00000000-0000-0000-0000-000000000000 (an order id that cannot exist) with the geolocation packet, if one is configured. The exchange runs its geo check before it looks the order up, so a 404 means the check passed, and a geo 422 means it did not. On an exchange without geo-fencing it always passes.

Needs a read_write key (the probe is a write route). The exchange records a failed check in its geolocation log exactly as it would a real order from the same place, and may raise a compliance alert, so call it once at start-up, not in a loop.

Parameter	Type	Description
opts (optional)	GeoOption
opts.geoLocation (optional)	string | null	Overrides the client’s geoLocation for this call; null sends none.

Returns Promise<GeoCheckResult>.

iterAccountMarketStats()

iterAccountMarketStats(query?: WithoutCursor<MarketStatsQuery>): AsyncGenerator<MarketStat, void, undefined>

Every per-market stat row, following the cursor.

Parameter	Type	Description
query (optional)	WithoutCursor<MarketStatsQuery>
query.competitions (optional)	StrList
query.eventIds (optional)	StrList
query.excludeZeroSettlements (optional)	boolean
query.fromTime (optional)	number
query.limit (optional)	number
query.marketIds (optional)	StrList
query.sports (optional)	StrList
query.toTime (optional)	number

Returns AsyncGenerator<MarketStat, void, undefined>.

iterAdjustments()

iterAdjustments(query?: { limit?: number }): AsyncGenerator<PaymentTransaction, void, undefined>

Every adjustment, following the cursor.

Parameter	Type	Description
query (optional)	{ limit?: number }
query.limit (optional)	number

Returns AsyncGenerator<PaymentTransaction, void, undefined>.

iterDeposits()

iterDeposits(query?: { limit?: number }): AsyncGenerator<PaymentTransaction, void, undefined>

Every deposit, following the cursor.

Parameter	Type	Description
query (optional)	{ limit?: number }
query.limit (optional)	number

Returns AsyncGenerator<PaymentTransaction, void, undefined>.

iterEvents()

iterEvents(query?: WithoutCursor<EventsQuery>): AsyncGenerator<Event, void, undefined>

Every event matching the filters, following the cursor.

Parameter	Type	Description
query (optional)	WithoutCursor<EventsQuery>
query.competitions (optional)	StrList
query.eventIds (optional)	StrList
query.eventTypes (optional)	StrList
query.limit (optional)	number
query.promoted (optional)	boolean
query.sortBy (optional)	string	"start_time".
query.sortDirection (optional)	"asc" | "desc"
query.sports (optional)	StrList
query.status (optional)	string	scheduled, in_progress, completed or cancelled.
query.title (optional)	string

Returns AsyncGenerator<Event, void, undefined>.

iterFees()

iterFees(query?: { limit?: number }): AsyncGenerator<FeeTransaction, void, undefined>

Every fee entry, following the cursor.

Parameter	Type	Description
query (optional)	{ limit?: number }
query.limit (optional)	number

Returns AsyncGenerator<FeeTransaction, void, undefined>.

iterFills()

iterFills(query?: WithoutCursor<FillsQuery>): AsyncGenerator<Fill, void, undefined>

Every fill matching the filters, following the cursor.

Parameter	Type	Description
query (optional)	WithoutCursor<FillsQuery>
query.limit (optional)	number
query.marketIds (optional)	StrList
query.orderIds (optional)	StrList
query.status (optional)	string	created, open, settled or cancelled.

Returns AsyncGenerator<Fill, void, undefined>.

iterLoyalty()

iterLoyalty(query?: { limit?: number }): AsyncGenerator<Transaction, void, undefined>

Every loyalty entry, following the cursor.

Parameter	Type	Description
query (optional)	{ limit?: number }
query.limit (optional)	number

Returns AsyncGenerator<Transaction, void, undefined>.

iterMarkets()

iterMarkets(query?: WithoutCursor<MarketsQuery>): AsyncGenerator<Market, void, undefined>

Every market matching the filters, following the cursor.

Parameter	Type	Description
query (optional)	WithoutCursor<MarketsQuery>
query.competitions (optional)	StrList
query.eventIds (optional)	StrList
query.limit (optional)	number	Default 100, maximum 200.
query.marketIds (optional)	StrList
query.sortBy (optional)	string	"event_start".
query.sortDirection (optional)	"asc" | "desc"
query.sports (optional)	StrList
query.status (optional)	StrList	One status or a list, e.g. ["pre_open", "open"].
query.trading (optional)	boolean	true for only the markets accepting orders now, false for only those that are not.

Returns AsyncGenerator<Market, void, undefined>.

iterOrders()

iterOrders(query?: WithoutCursor<OrdersQuery>): AsyncGenerator<Order, void, undefined>

Every order matching the filters, following the cursor.

Parameter	Type	Description
query (optional)	WithoutCursor<OrdersQuery>
query.clientOrderIds (optional)	StrList
query.limit (optional)	number
query.marketIds (optional)	StrList
query.orderIds (optional)	StrList
query.status (optional)	StrList	One status or a list, e.g. ["open", "delayed"].

Returns AsyncGenerator<Order, void, undefined>.

iterSettlements()

iterSettlements(query?: WithoutCursor<SettlementsQuery>): AsyncGenerator<Settlement, void, undefined>

Every settlement, following the cursor.

Parameter	Type	Description
query (optional)	WithoutCursor<SettlementsQuery>
query.limit (optional)	number
query.marketIds (optional)	StrList
query.type (optional)	string	closed_short, closed_long, expired_short or expired_long.

Returns AsyncGenerator<Settlement, void, undefined>.

iterWithdrawals()

iterWithdrawals(query?: { limit?: number }): AsyncGenerator<PaymentTransaction, void, undefined>

Every withdrawal, following the cursor.

Parameter	Type	Description
query (optional)	{ limit?: number }
query.limit (optional)	number

Returns AsyncGenerator<PaymentTransaction, void, undefined>.

loyalty()

loyalty(query?: PageQuery): Promise<Page<Transaction>>

GET /api/v1/portfolio/loyalty: loyalty entries.

Parameter	Type	Description
query (optional)	PageQuery
query.cursor (optional)	string
query.limit (optional)	number

Returns Promise<Page<Transaction>>.

market()

market(marketId: string): Promise<Market>

One market by id. Throws STXNotFoundException if there is none.

Parameter	Type	Description
marketId	string

Returns Promise<Market>.

markets()

markets(query?: MarketsQuery): Promise<Page<Market>>

GET /api/v1/markets: one page of markets. Filters combine with AND; list filters match any value.

Parameter	Type	Description
query (optional)	MarketsQuery
query.competitions (optional)	StrList
query.cursor (optional)	string
query.eventIds (optional)	StrList
query.limit (optional)	number	Default 100, maximum 200.
query.marketIds (optional)	StrList
query.sortBy (optional)	string	"event_start".
query.sortDirection (optional)	"asc" | "desc"
query.sports (optional)	StrList
query.status (optional)	StrList	One status or a list, e.g. ["pre_open", "open"].
query.trading (optional)	boolean	true for only the markets accepting orders now, false for only those that are not.

Returns Promise<Page<Market>>.

me()

me(): Promise<Me>

GET /api/v1/me: who this key belongs to. Returns the user_id the account channels are keyed by, the account_id, and the key’s scope (read_only or read_write).

Returns Promise<Me>.

order()

order(orderId: string): Promise<Order>

GET /api/v1/orders/{order_id}: one of your orders.

Parameter	Type	Description
orderId	string

Returns Promise<Order>.

orders()

orders(query?: OrdersQuery): Promise<Page<Order>>

GET /api/v1/orders: one page of your orders, newest first.

Parameter	Type	Description
query (optional)	OrdersQuery
query.clientOrderIds (optional)	StrList
query.cursor (optional)	string
query.limit (optional)	number
query.marketIds (optional)	StrList
query.orderIds (optional)	StrList
query.status (optional)	StrList	One status or a list, e.g. ["open", "delayed"].

Returns Promise<Page<Order>>.

placeOrder()

placeOrder(marketId: string, action: string, orderType: string, opts: OrderOptions): Promise<Order>

POST /api/v1/orders: place one order.

action is "buy" or "sell"; orderType is "limit" or "market". price (dollars, required for a limit order) and quantity (contracts) are decimal strings, e.g. { price: "0.56", quantity: "2" }. Numbers are refused client-side.

The exchange validates the order: a bad price step or a fractional quantity throws STXValidationException (400) or STXRejectedException (422) with the API’s message; a geo-fencing refusal throws STXGeoLocationException.

A POST is never retried after a 5xx or a dropped connection; pass clientOrderId so you can look the order up if that happens.

Parameter	Type	Description
marketId	string
action	string
orderType	string
opts	OrderOptions
opts.cancelOnDisconnect (optional)	boolean
opts.clientOrderId (optional)	string
opts.deviceId (optional)	string
opts.expiration (optional)	string	"good_till_start" or "good_till_time".
opts.expirationTime (optional)	number	Unix microseconds, with expiration: "good_till_time".
opts.geoLocation (optional)	string | null	Overrides the client’s geoLocation for this call; null sends none.
opts.price (optional)	string	Dollars, as a decimal string: "0.56". Required for a limit order.
opts.quantity	string	Contracts, as a decimal string: "2".

Returns Promise<Order>.

placeOrders()

placeOrders(orders: readonly NewOrderInput[], opts?: GeoOption): Promise<BatchOrderResult[]>

POST /api/v1/orders/batched: place several orders in one call. One geo check covers the batch. Returns one result per order, in order; a rejected order has errors instead of order and does not stop the others.

Parameter	Type	Description
orders	readonly NewOrderInput[]
opts (optional)	GeoOption
opts.geoLocation (optional)	string | null	Overrides the client’s geoLocation for this call; null sends none.

Returns Promise<BatchOrderResult[]>.

positions()

positions(query?: { marketIds?: StrList }): Promise<Position[]>

GET /api/v1/positions: your open positions, the same objects the positions channel sends on join. position is positive when long, negative when short.

Parameter	Type	Description
query (optional)	{ marketIds?: StrList }
query.marketIds (optional)	StrList

Returns Promise<Position[]>.

settlements()

settlements(query?: SettlementsQuery): Promise<Page<Settlement>>

GET /api/v1/portfolio/settlements: settlements on your account.

Parameter	Type	Description
query (optional)	SettlementsQuery
query.cursor (optional)	string
query.limit (optional)	number
query.marketIds (optional)	StrList
query.type (optional)	string	closed_short, closed_long, expired_short or expired_long.

Returns Promise<Page<Settlement>>.

statsFor()

statsFor(event: string | { event_id?: string | null }): Promise<EventStat[]>

The stats event accepts for new markets.

Parameter	Type	Description
event	string | { event_id?: string | null }

Returns Promise<EventStat[]>.

userId()

userId(): Promise<string>

The user id from me(), fetched once and cached. If me() is not permitted, the id comes from balance(), which carries the same user_id.

Returns Promise<string>.

websocket()

websocket(opts?: Omit<STXWebSocketOptions, "rest">): STXWebSocket

An STXWebSocket using this client’s host and key. Account channels need your user id; the socket fetches it through me() on first use.

Parameter	Type	Description
opts (optional)	Omit<STXWebSocketOptions, "rest">
opts.channelPingIntervalMs (optional)	number | null	Milliseconds between channel ping frames on every joined topic; null disables them. orders with cancel-on-disconnect pings faster, from the granted timeout. Default 30000.
opts.env (optional)	string | null	"production" or "demo" ("prod" and "live" are accepted).
opts.environment (optional)	string | STXEnvironment	A published environment, Environments.OntarioDemo, or its name, "ontario-demo". Instead of region + env; host still wins.
opts.heartbeatIntervalMs (optional)	number	Milliseconds between socket heartbeats. The server closes a socket silent for 60 s. Default 25000.
opts.host (optional)	string | null	A hostname or URL, overriding region/env: "demo.stxapp.ca", "http://localhost:4000".
opts.joinTimeoutMs (optional)	number	Milliseconds to wait for a join or push reply. Default 10000.
opts.keyId (optional)	string | null	The API key ID.
opts.logger (optional)	Logger
opts.onReconnect (optional)	() => void | Promise<void>	Called after every successful reconnect and rejoin: the moment to read open orders and anything else you loaded with STX again.
opts.privateKey (optional)	PrivateKeyInput | null	The Ed25519 private key: PEM text, a path to a PEM file, PEM bytes, or a KeyObject.
opts.profile (optional)	string | null	A section of ~/.stx/credentials to read.
opts.queueSize (optional)	number	Messages buffered per channel for iteration; the oldest is dropped when full. Default 10000.
opts.reconnect (optional)	boolean	Reconnect after a drop. Default true.
opts.reconnectPolicy (optional)	ReconnectPolicy
opts.region (optional)	string | null	A known region, e.g. "ontario" or "us". With env, picks the host.
opts.signer (optional)	Signer	Instead of privateKey: signs message bytes, for keys in an HSM or KMS.
opts.userId (optional)	string	Your user id, if you already have it (skips GET /me).
opts.verifyTls (optional)	boolean | null	Set false only for a local server. Honoured by the WebSocket; for HTTP requests, pass a fetch whose dispatcher skips verification (Node’s global fetch has no per-call switch).

Returns STXWebSocket.

withdrawals()

withdrawals(query?: PageQuery): Promise<Page<PaymentTransaction>>

GET /api/v1/portfolio/withdrawals.

Parameter	Type	Description
query (optional)	PageQuery
query.cursor (optional)	string
query.limit (optional)	number

Returns Promise<Page<PaymentTransaction>>.