Changes the current ticker. The active window is always notified. When a named binding is provided, that binding's linked panels are also updated.

Accepts two request formats: a ticker pattern string (e.g. BINANCE:BTCUSDT.p) or explicit fields (exchange + market + ticker).

A binding is a named group of linked panels inside MetaScalp (e.g. a chart, order book, and trade feed showing the same ticker). Bindings are numbered "001"–"500" and configured by the user in the MetaScalp UI.

Opens a combo layout for the specified ticker in the MetaScalp UI.

Two mutually exclusive payload shapes are accepted — the shape decides the behaviour, there is no request flag:

• { "ticker": "BTCUSDT" } — opens one combo layout for a single ticker (unchanged behaviour).
• { "tickers": ["BTCUSDT", "ETHUSDT", "SOLUSDT"] } — opens one combo layout per ticker, in the order given.

The tickers form is a write validated as all-or-nothing: the whole list is validated first, and if any ticker resolves on no eligible connection, nothing is opened and the request returns 400 naming the rejected tickers. Supplying both ticker and tickers, or an empty tickers array with no ticker, also returns 400.

Returns all currently active exchange connections. Use the id from the response to query orders, positions, balances, or to subscribe via WebSocket.

Returns details for a single connection by ID.

Returns all available trading pairs on a connection with price/size precision, trading status, and constraints.

Optional query parameter Refresh=true forces a fresh fetch of the ticker list from the exchange instead of returning the cached set.

Returns open orders for a specific ticker on a connection. The Ticker query parameter is required.

Read-only. Reports, live from the venue, the maximum leverage the venue allows and the maximum position size available for a ticker at the current (or an explicitly supplied) leverage. Values come from the venue's own risk-limit tiers — nothing is locally computed, cached or defaulted. The Ticker query parameter is required.

Read-only. Returns a fresh REST order-book snapshot for every panel currently in link group groupId. The membership is read LIVE from the UI's own grouping — a panel unlinked or closed a moment ago is already absent, and nothing about linking is changed by this request. A link group is a number (the link value the UI shows), not a stored entity: an in-range group with no live members is a legitimate empty result (200 with an empty members list), NOT a 404. Valid group ids are 1–500.

Partial failure never fails the whole response. Each member is reported independently: a good book carries ok: true and a book object; a member that could not be snapshotted carries ok: false and a stable machine-readable reason token. One failing book never turns into a 500.

Status codes: 200 (including an empty group); 400 for a non-numeric or out-of-range groupId.

Returns all open positions on a connection (futures/margin markets).

Returns account balances for all assets on a connection.

Places a new order on the exchange through a connection. Returns an auto-generated clientId for order tracking and executionTimeMs indicating how long the exchange request took (in milliseconds).

Cancels an existing order on the exchange.

Cancels all open orders for a given ticker on the exchange.

Returns { status, cancelledCount } — cancelledCount: 0 if there are no open orders for that ticker.

Returns the current cluster (volume profile / footprint) data for a ticker. The snapshot contains up to 10 time columns, each holding bid/ask volumes at every price level.

When ZoomIndex > 1, prices are grouped into buckets of ZoomIndex × PriceIncrement and volumes are summed.

Returns all signal levels for a specific ticker on a connection, each with the fields described above (id, connectionId, ticker, price, isTriggered, triggerTime, triggerRule, note and the seven appearance fields, null when unset).

Read-modify-write: id, connectionId, ticker, isTriggered and triggerTime are accepted and ignored by the matching PUT, so the object returned here can be edited and sent straight back. Trigger state is owned by the signal engine and is never settable over the API.

Creates a signal level for a ticker. The ticker must have live order book data (best ask is required) — subscribe to its order book first.

Appearance is additive and optional (MC-421): every appearance field defaults to unset — a level created without them looks exactly as it does today.

Errors: missing ticker/price → 400; price ≤ 0 → 400 Price must be greater than zero; unknown triggerRule → 400 Invalid 'triggerRule'. Allowed values: LessThanEqual, GreaterThanEqual.; an invalid appearance enum value (lineStyle / textAlignment / textStyle) → 400 Invalid '{field}'.; no order book data for the ticker → 400; unknown connection → 404 Connection {id} not found.

Partial in-place update of an existing signal level. Only the supplied fields are applied; the level keeps its identity (the same id row is modified — no delete + re-create). At least one of price / triggerRule must be present.

Partial update (MC-421): the note and every appearance field follow the same partial-apply rule as price/triggerRule — only the fields present are written, the rest are left untouched. At least one of price / triggerRule / note / an appearance field must be present. An invalid appearance enum value → 400 Invalid '{field}'.

Re-arm on price move: if the level had already fired (isTriggered = true) and its price is changed, it is re-armed (isTriggered back to false, triggerTime cleared) so it can fire again at the new price.

Errors: invalid connection id → 400 Invalid connection ID; connection not open → 404 Connection {id} not found; invalid level id → 400 Invalid signal level ID; empty body / all fields null → 400 Request body must set at least one of 'price', 'triggerRule', 'note' or an appearance field.; price ≤ 0 → 400 Price must be greater than zero; unknown triggerRule → 400 Invalid 'triggerRule'. Allowed values: LessThanEqual, GreaterThanEqual.; level not found → 404 Signal level {id} not found.

Removes a single signal level by ID.

Removes all signal levels for a specific ticker on a connection.

Removes all triggered signal levels across all connections and tickers.

Returns all order book settings for a specific ticker on a connection. Settings include trading defaults, order book display configuration, tick thresholds, and cluster options.

Partial update — only send the fields you want to change. Omitted fields keep their current values. Changes are pushed live to the running panels. Returns the full updated settings object.

Enum fields: ShowRuler (None, Points, Percent, PercentVolume), ZoomType (Absolute, Percentage), SizeType (Coin, Usd).

Fetches a fresh order book snapshot directly from the exchange REST endpoint — no cache lookup, no WebSocket subscription side effects. Intended as a one-shot complement to orderbook_subscribe with FetchSnapshot=false: subscribe to deltas cheaply, then call this once per ticker when you actually need to seed the book.

Each call performs one REST request to the exchange. The caller is responsible for not exceeding the exchange's rate limit when invoking this endpoint for many tickers in quick succession.

Returns 501 Not Implemented for exchanges that don't expose a REST snapshot endpoint (e.g. Bybit USDT Perpetual, which only delivers snapshots over WebSocket).

Returns all user levels for a specific ticker on a connection, each with the fields described above (id, connectionId, ticker, price, name, note, date — the date is returned as a nullable ISO-8601 timestamp), plus the seven appearance fields lineThickness, lineStyle, lineColor, textSize, textColor, textAlignment, textStyle (each null when unset; the enum-backed ones are emitted as their string name). (MC-421 Step 15) note is the user level's own free-text note (null when unset), read back exactly as sent — the same as on a signal level; it is distinct from name.

Read-modify-write: id, connectionId and ticker are accepted and ignored by the matching PUT, so the object returned here can be edited and sent straight back. One exception: a level whose date is non-null is not round-trippable verbatim — GET emits ISO-8601 while PUT takes raw epoch seconds.

⚠ Stored and returned, but not drawn. Unlike a signal-level note, a user-level note is not rendered on the order book or on either chart engine: a user level has a single label slot and name already occupies it. The note is an API-level attribute only until the layout question is settled.

Errors: invalid connection id → 400 Invalid connection ID; unknown connection → 404 Connection {id} not found; missing Ticker query → 400 Query parameter 'Ticker' is required.

Creates a user level for a ticker. Unlike signal levels there is no market-data precondition — the hand-drawn path has none, so the API does not add one.

Appearance is additive and optional (MC-421): every appearance field defaults to unset — a level created without them looks exactly as it does today.

Errors: missing ticker/price → 400 Invalid request body. 'ticker' and 'price' are required.; price ≤ 0 → 400 Price must be greater than zero; an invalid appearance enum value (lineStyle / textAlignment / textStyle) → 400 Invalid '{field}'.; invalid connection id → 400 Invalid connection ID; unknown connection → 404 Connection {id} not found.

Partial in-place update of an existing user level. Only the supplied fields are applied; the level keeps its identity (the same id row is modified — no delete + re-create). At least one of price / name / date must be present.

Partial update (MC-421): every appearance field follows the same partial-apply rule — only the fields present are written, the rest are left untouched. At least one of price / name / note / date / an appearance field must be present.

Errors: invalid connection id → 400 Invalid connection ID; connection not open → 404 Connection {id} not found; invalid level id → 400 Invalid user level ID; empty body / all fields null → 400 Request body must set at least one of 'price', 'name', 'date', 'note' or an appearance field.; an invalid appearance enum value → 400 Invalid '{field}'.; price ≤ 0 → 400 Price must be greater than zero; level not found → 404 User level {id} not found.

Removes a single user level by ID.

Errors: invalid connection id → 400 Invalid connection ID; unknown connection → 404 Connection {id} not found; invalid level id → 400 Invalid user level ID.

Removes all user levels for a specific ticker on a connection.

Errors: invalid connection id → 400 Invalid connection ID; unknown connection → 404 Connection {id} not found; missing Ticker query → 400 Query parameter 'Ticker' is required.

Returns the whole set as { connectionId, ticker, lineAnnotations[], horizontalLineAnnotations[], horizontalRayAnnotations[] }. Each item carries its geometry plus its zero-based index in its own list — the only handle usable for DELETE .../{type}/{index}.

The y / y1 / y2 values are venue prices, converted out of the chart's internal axis units per (connectionId, ticker). A hand-drawn shape reads back at its on-screen price (e.g. 0.2, not ≈1999.79).

Since MC-400 Step 15c: this GET also returns shapes a trader draws by hand on the TradingView chart — horizontal_line, horizontal_ray and trend_line tools are written back into the same shared store as they are created / moved / removed, and appear here in venue prices exactly like API-created shapes (the TradingView bundle dist/bundle.js was rebuilt for this).

Errors: invalid connection id → 400 Invalid connection ID; unknown connection → 404 Connection {id} not found; missing Ticker query → 400 Query parameter 'Ticker' is required; unknown ticker or PriceIncrement ≤ 0 → 400 Ticker '{ticker}' not found on connection {connectionId}.

The primary write: replaces the entire list for {type} with the posted array. The body is a JSON array of items of that type's geometry (a null / empty body clears the list). This is how a client persists edits — read with GET, mutate the array client-side, PUT it back.

Concurrency — last-writer-wins. Because the annotation model has no per-item identity (the only handle is the list index) the write is a whole-list replace, not a per-item patch. If the sidebar and the API (or two API clients) edit the same (connectionId, ticker) list concurrently, the last PUT overwrites the other's changes wholesale. Read immediately before you PUT to minimise the window.

Send y / y1 / y2 as venue prices; they are converted to the chart's axis units per (connectionId, ticker) before storage, so the shape lands at the price you sent.

Errors: unknown {type} → 400 Unknown annotation type '{type}'. Allowed values: lines, horizontal-lines, horizontal-rays.; invalid connection id → 400; unknown connection → 404; missing Ticker → 400; unknown ticker or PriceIncrement ≤ 0 → 400 Ticker '{ticker}' not found on connection {connectionId}.

Appends a single annotation to the {type} list. The body is one item (not an array) of that type's geometry, with y / y1 / y2 as venue prices (converted to axis units per (connectionId, ticker) before storage). Implemented as read-modify-write inside the one action (read the current list, append, replace the whole list) — the list is never cached across requests. The appended item lands at the last index.

Errors: unknown {type} → 400; empty / wrong-shape body → 400 Request body must be a {type} annotation.; invalid connection id → 400; unknown connection → 404; missing Ticker → 400; unknown ticker or PriceIncrement ≤ 0 → 400 Ticker '{ticker}' not found on connection {connectionId}.

Removes the annotation at the given zero-based {index} in the {type} list (read-modify-write inside the one action). An out-of-range index is a 404 and the stored list is left unchanged (the whole-list replace is not performed). The index is the value stamped on each item by GET.

Errors: unknown {type} → 400; non-numeric index → 400 Invalid annotation index; index out of range → 404 {Type} annotation index {index} not found; invalid connection id → 400; unknown connection → 404; missing Ticker → 400.

Clears all three annotation lists (lines, horizontal-lines, horizontal-rays) for the (connectionId, ticker) in one call — the same action the «clear all shapes» sidebar command performs.

Errors: invalid connection id → 400; unknown connection → 404; missing Ticker → 400.

Returns { count, templates[] }. Each template is { id, name, settings } where settings carries the whole configuration (columnSettings[], columnFilters[], marketFilters[], coinTags[], numberOfRows, activeFilter, the new-coin flags, …). The synthetic Default template (id -1) is always first.

Returns the single template { id, name, settings }.

Errors: non-numeric {templateId} → 400 Invalid template ID; unknown id (including the synthetic Default -1) → 404 Screener template {id} not found.

Body { name, settings? }. name is required; settings is optional — omit it and the template is created with the default configuration. The full settings blob (columns / filters / market selections) is persisted, so a template created here carries its filters and columns, not just its name. Returns the created { id, name, settings }.

Errors: missing / blank name → 400 Request body must carry a non-empty 'name'.; body that is not valid JSON → 400 Request body is not valid JSON.

Body { name?, settings? }. A null / omitted name keeps the stored name and a null / omitted settings keeps the stored blob (partial update). Returns the updated { id, name, settings }.

Errors: non-numeric {templateId} → 400; body that is not valid JSON → 400; unknown id → 404 Screener template {id} not found (checked before any write).

Removes the template. Returns { status: "ok" }.

Errors: non-numeric {templateId} → 400; unknown id (including the synthetic Default -1) → 404 Screener template {id} not found (checked before any write).

Returns ONE headless snapshot of the full row set of the given template — every row an open screener window on the same template would show — without opening a screener window. A fresh background screener socket is subscribed, the first complete frame captured, and the socket disposed; there is no streaming. The synthetic Default (id -1) is answered too (it resolves to the default configuration, exactly like an open window's fallback).

Response { templateId, count, rows[] }. Each row: { ticker, wireTicker, isNewCoin, exchange, listedExchanges[], columns[] } where exchange / listedExchanges are screener exchange keys ("binance_s", "bybit_f", "polymarket") and each columns[] entry is { type, timeFrame, time, metric, value }.

Errors: non-numeric {templateId} → 400 Invalid template ID; unknown id → 404 Screener template {id} not found (checked before any subscribe). If the screener backend produces no rows within the deadline, rows is an empty array (count = 0).

Builds a notification and adds it to the feed. All fields are optional. The eventType is an arbitrary string rendered verbatim in the Event Type column (no fixed enum). A field that is not sent leaves that column empty — price and size stay blank (no 0 / -1 sentinel).

Success → 200 { "status": "ok" }. The row is broadcast to subscribed WebSocket clients as a notification_update whose type is the supplied eventType (or, for native notifications, the notification-type name as before).

Notifications globally disabled still answers 200. This endpoint injects directly into the in-memory feed and its WebSocket broadcast; it does not consult the user's global «show notifications» toggle or the per-type settings checkboxes. A request therefore succeeds (and is delivered to subscribed WS clients) even when the desktop UI would suppress the equivalent native pop-up. Treat delivery as feed-level, not UI-visibility-level.

Errors: unknown connectionId → 404 Connection {id} not found.

Returns the whole open UI as { "windows": [ ... ], "standaloneCharts": [ ... ] }. Each window carries its geometry, monitor and tabs; each tab its documents (order books and charts); each document its identity, connection, ticker, link number and docking position, plus kind-specific fields.

Window

Tab

Document (common fields)

Order-book details (document.orderBook)

Chart details (document.chart)

standaloneCharts is a top-level array of chart documents (same document shape) for chart windows not attached to any tab (tabId == null); each includes its own chart.geometry and never appears under a tab.

Other open window families

Alongside windows and standaloneCharts, the inventory lists every OTHER open window family the open route (POST /api/ui/windows) can create. Every key is always present; where a value is absent it is null (never omitted), and a family that fails to read degrades to its own empty list / null object without blanking the rest.

Success → 200 with the object above.

Returns exactly the same single-window object as that window's entry in /api/ui/state — same geometry, tabs and documents.

Optional ?windowType= query. The window ids returned by POST /api/ui/windows are per-surface: a chart / watchlist / screener id is unique only within its own surface, not against the workspace Windows table this route reads by default. Supply ?windowType= with one of chart, tradingViewChart, watchlist or screener (case-insensitive) to resolve the id within that surface instead — letting a client read a window back at the very address the create route returned. The response is then { id, type, document | watchlist | screener } (exactly one of the three type blocks is populated). Omit the query for byte-for-byte today's Windows-table lookup.

Errors: a non-numeric windowId → 400 Invalid window ID; an unknown window (in the default table, or within the requested windowType surface, or an unrecognised windowType) → 404 Window {id} not found.

Sets the link (binding-group) number of one addressed panel — the same linkNumber reported by GET /api/ui/state (document.linkNumber). {externalId} is the document's GUID.

Request body:

{ "linkNumber": 3 }

Persisted immediately via the binding bus (a DB-backed write — no UI thread is used). The stored link changes at once; a panel already on screen may not fully re-wire its live link until it is reloaded. Affects only the addressed document.

Asynchronous w.r.t. the UI thread. Success → 200 { "status": "ok" }.

Errors: a non-GUID externalId → 400 Invalid document ID; a missing/omitted linkNumber → 400; a non-positive value → 400; an unknown document → 404 Document {externalId} not found (nothing is written).

Opens ONE terminal window of the requested type at an explicit position and size, on an explicit monitor. Geometry is entirely optional: omit top/left/ height/width and the window lands exactly where it lands today for that type — including MetaScalp's open-at-the-cursor placement where the app does that today (workspace, watchlist, screener, line-notifications, finres, user-trades). A supplied rect is clamped to fit the target monitor. Position is in virtual-desktop coordinates; monitor (0-based) selects the screen.

Request body:

{ "windowType": "watchlist", "top": 100, "left": 200, "height": 450, "width": 300, "monitor": 0 }

Response { windowId, windowType, top, left, height, width } — where the window actually landed (post-clamp). For the four singleton types (lineNotifications, finres, userTrades, listing) windowId is null: each has a single fixed row (id 1, which would collide with the main workspace) and its close/activate routes ignore the id entirely, so there is no addressable per-surface id to return. Every other type returns its real per-surface id.

Opening the screener on a template. For windowType: "screener" a supplied templateId is threaded onto the screener window so it loads that template exactly as picking it by hand would; because the choice is persisted with the window, it also becomes the window's template on the next launch. Omitting templateId is bit-for-bit today's behaviour (the app's Default view).

Errors: a malformed body → 400 Malformed request body.; a missing windowType → 400 with the supported list; an unknown or unsupported-standalone type (e.g. settings, which is modal, or the full-screen chart, which needs an existing chart) → 400 naming the supported list; an unknown screener templateId → 404 Screener template {templateId} not found — all validated before any window is opened.

Closes ONE terminal window through the app's OWN close path (the same path a manual X uses, so it inherits today's close-confirmation-popup behaviour). {windowId} is the id WITHIN the surface named by windowType — ids are not unique across surfaces (a workspace, a chart, a screener and a watchlist can all be id 1), so the body's windowType is what routes the id to the correct window. The singleton surfaces (lineNotifications, finres, userTrades, listing) ignore the path id. finres is HIDDEN rather than destroyed, matching its manual toggle.

Request body:

{ "windowType": "workspace" }

Response { windowType, windowId, closed, outcome }.

The main workspace can never be closed through the API — it would quit the terminal. A windowId that resolves to the main workspace → 400 The main workspace cannot be closed through the API. (+ supported list).

Errors: a non-numeric {windowId} → 400 Invalid window ID; a malformed body → 400 Malformed request body.; a missing / unknown / unsupported windowType → 400 naming the supported list; an unknown window id → 404 — all validated before any window is closed.

Brings ONE terminal window to the front on its own window thread. Same id-addressing as the close route: {windowId} is the id within the surface named by windowType; singletons ignore the id.

Request body:

{ "windowType": "chart" }

Response { windowType, windowId, activated, outcome }.

Errors: a non-numeric {windowId} → 400 Invalid window ID; a malformed body → 400; a missing / unknown / unsupported windowType → 400 naming the supported list; the main workspace → 400; an unknown window id → 404.

Re-points one addressed panel (order book or chart) to a different market. This targets only that panel — unlike POST /api/change-ticker, which drives the active window and a whole named link group. {externalId} is the document's GUID.

Request body:

{ "ticker": "ETHUSDT", "connectionId": 77 }

Asynchronous w.r.t. the UI thread. The API resolves the document and dispatches a change-ticker action to that panel's own live listener, which re-resolves the ticker and re-tickers itself on its own window dispatcher; the visible change and its persistence happen inside the panel. Success → 200 { "status": "ok" }.

Errors: a non-GUID externalId → 400 Invalid document ID; a missing ticker → 400; an unknown document → 404 Document {externalId} not found; a document with no current connection and no supplied connectionId → 400.

Opening/closing a panel and switching the active window or tab are not yet available. They require calling MetaScalp's own window-thread methods, and the local API layer has no reachable window‑id → dispatcher lookup to marshal onto (it does not reference the WPF UI project). Faking them by writing the database directly would diverge the on-screen layout from the saved model, so they are deliberately deferred to a dedicated follow-up rather than shipped fragile. The following routes therefore do not exist yet:

Connect via WebSocket to receive real-time updates for your exchange connections. Subscribe by connection ID for order, position, balance, and finres events. Subscribe by connection ID + ticker for real-time trade and order book market data.

Connection

The WebSocket server shares the same port as the HTTP API (17845–17855). Connect to ws://127.0.0.1:{port}/.

Message format

All messages (inbound and outbound) are JSON with this envelope:

{ "Type": "message_type", "Data": { ... } }

Inbound messages (client → server)

Connection-level — subscribe by connection ID for order, position, balance, and finres updates:

Market data — subscribe by connection ID + ticker for trade or order book updates:

Outbound messages (server → client)

Acknowledgements:

Connection-level updates:

Market data updates:

Trade aggregation: trade_update entries are aggregated server-side using the order book's AddingTicksForAPeriod setting (same value that drives the UI ticks section, default 200 ms; per-(connection, ticker)). Consecutive same-side trades within the window are merged into one entry — size is summed, price and time track the latest merged trade. A new entry is emitted when the side changes or the window expires. Each entry also carries highPrice and lowPrice — the highest and lowest price among the trades merged into that entry (the range the price travelled inside the tick), while price stays the latest merged trade. With AddingTicksForAPeriod = 0 aggregation is disabled and every entry has highPrice == lowPrice == price. Changes are picked up live by active subscriptions.

Signal levels — subscribe (globally, no data payload) to receive signal-level lifecycle events:

User levels — subscribe (globally, no data payload) to receive user-level lifecycle events. date is a nullable ISO-8601 timestamp:

Notifications — subscribe (globally, no data payload) to receive the notification feed (the «Line notifications» window). On subscribe the server acknowledges with notification_subscribed and pushes a one-shot notification_snapshot of the recent feed (inside the 200-row cap); after that every new row — native or injected via POST /api/notifications — is delivered live as notification_update. Without this subscribe a client never receives the notification_update the Notifications section documents:

Chart annotations — subscribe per (connectionId, ticker) to receive the current shapes. This family delivers a subscribe/unsubscribe ack and a one-shot snapshot only — there is no annotations_updated push. The annotation service exposes no change-notification / listener mechanism, so live deltas cannot be delivered without inventing one; a client that needs fresh state after an edit re-subscribes or re-issues GET .../annotations. Datetime fields are ISO-8601.

⚠ Snapshot prices are venue prices (from the Step 14 build). The y / y1 / y2 in annotations_snapshot are the instrument's real market price (e.g. 0.2 for ADAUSDT) — identical to what GET .../annotations returns — converted per (connectionId, ticker) from that instrument's own price increment. Earlier builds passed these fields through unconverted, exposing the chart's internal axis units (×10⁴ for ADAUSDT), so a hand-drawn ray read back at ≈1999.79 on the socket while REST already reported 0.2; the two channels now agree. The REST-side conversion shipped earlier in 1.0.2835-MC-400; the socket snapshot converts as of the Step 14 build. Timestamp fields (x1 / x2) are unchanged. If the Ticker is unknown on the connection or its price increment is ≤ 0, the server emits an error frame instead of the snapshot (a socket cannot answer 400) — it never silently returns raw axis units.

UI change events — subscribe (globally, no data payload) to observe the open UI. On subscribe the server acknowledges with ui_subscribed and immediately pushes a ui_snapshot whose Data is identical to GET /api/ui/state (same camelCase shape). After that, a ui_update is pushed per observed change. Read-only — the server never opens, closes or mutates any UI element here:

ui_update payloads by kind:

Coverage — MetaScalp.Api observes only Application-layer events (it does not reference the WPF UI project), so this rung delivers exactly the two ui_update kinds above. The following changes are not emitted yet (no reachable Application-layer event publishes them today, and no polling is used): order-book document opened, ticker changed, window opened/closed, tab removed/activated, document closed/moved, and link-number changes. Clients that need the current state after such a change can re-request GET /api/ui/state.

Lifecycle

Example payloads

// Subscribe
{ "Type": "subscribe", "Data": { "connectionId": 1 } }

// Server confirms
{ "Type": "subscribed", "Data": { "connectionId": 1 } }

// Order update pushed by server
{
  "Type": "order_update",
  "Data": {
    "connectionId": 1,
    "orderId": 98765,
    "ticker": "BTCUSDT",
    "side": "Buy",
    "type": "Limit",
    "price": 65000.0,
    "filledPrice": 0.0,
    "size": 0.01,
    "filledSize": 0.0,
    "fee": 0.0,
    "feeCurrency": "USDT",
    "status": "New",
    "time": "2026-03-13T10:30:00+00:00"
  }
}

// Position update pushed by server
{
  "Type": "position_update",
  "Data": {
    "connectionId": 1,
    "positionId": 4321,
    "ticker": "ETHUSDT",
    "side": "Buy",
    "size": 1.5,
    "avgPrice": 3200.00,
    "avgPriceFix": 3200.00,
    "avgPriceDyn": 3200.00,
    "status": "Open"
  }
}

// Balance update pushed by server
{
  "Type": "balance_update",
  "Data": {
    "connectionId": 1,
    "balances": [
      { "coin": "USDT", "total": 10000.0, "free": 8500.0, "locked": 1500.0 },
      { "coin": "BTC", "total": 0.5, "free": 0.5, "locked": 0.0 }
    ]
  }
}

// FinRes update pushed by server
{
  "Type": "finres_update",
  "Data": {
    "connectionId": 1,
    "finreses": [
      { "currency": "USDT", "result": 250.50, "fee": 12.30, "funds": 10000.0, "available": 8500.0, "blocked": 1500.0 },
      { "currency": "BTC", "result": 0.005, "fee": 0.0001, "funds": 0.5, "available": 0.5, "blocked": 0.0 }
    ]
  }
}

// Subscribe to trades for a specific ticker (zoomIndex is optional)
{ "Type": "trade_subscribe", "Data": { "connectionId": 1, "ticker": "BTCUSDT", "zoomIndex": 1 } }

// Server confirms trade subscription
{ "Type": "trade_subscribed", "Data": { "connectionId": 1, "ticker": "BTCUSDT", "zoomIndex": 1 } }

// Trade update pushed by server
{
  "Type": "trade_update",
  "Data": {
    "connectionId": 1,
    "ticker": "BTCUSDT",
    "trades": [
      { "price": 65123.50, "size": 0.15, "side": "Buy", "time": "2026-03-16T12:00:01.234+00:00", "highPrice": 65124.00, "lowPrice": 65123.00 },
      { "price": 65123.00, "size": 0.03, "side": "Sell", "time": "2026-03-16T12:00:01.235+00:00", "highPrice": 65123.00, "lowPrice": 65123.00 }
    ]
  }
}

// Subscribe to order book for a specific ticker (zoomIndex / depthLevels / depthPercent / fetchSnapshot are optional; fetchSnapshot defaults to true)
{ "Type": "orderbook_subscribe", "Data": { "connectionId": 1, "ticker": "BTCUSDT", "zoomIndex": 0, "depthLevels": 50, "depthPercent": 0.5, "fetchSnapshot": true } }

// Server confirms order book subscription (echoes any non-null depth params; fetchSnapshot only when false)
{ "Type": "orderbook_subscribed", "Data": { "connectionId": 1, "ticker": "BTCUSDT", "zoomIndex": 0, "depthLevels": 50, "depthPercent": 0.5 } }

// Order book snapshot (full state, sent once on subscribe)
{
  "Type": "orderbook_snapshot",
  "Data": {
    "connectionId": 1,
    "ticker": "BTCUSDT",
    "asks": [
      { "price": 65124.00, "size": 1.20, "type": "Ask" },
      { "price": 65125.00, "size": 0.85, "type": "Ask" }
    ],
    "bids": [
      { "price": 65123.00, "size": 2.50, "type": "Bid" },
      { "price": 65122.00, "size": 1.10, "type": "Bid" }
    ],
    "bestAsk": { "price": 65124.00, "size": 1.20, "type": "BestAsk" },
    "bestBid": { "price": 65123.00, "size": 2.50, "type": "BestBid" }
  }
}

// Order book incremental update
{
  "Type": "orderbook_update",
  "Data": {
    "connectionId": 1,
    "ticker": "BTCUSDT",
    "updates": [
      { "price": 65124.00, "size": 0.90, "type": "Ask" },
      { "price": 65126.00, "size": 0.50, "type": "Ask" },
      { "price": 65123.00, "size": 2.80, "type": "Bid" }
    ]
  }
}

// Subscribe to mark price for a specific ticker
{ "Type": "mark_price_subscribe", "Data": { "connectionId": 1, "ticker": "BTCUSDT" } }

// Server confirms mark price subscription
{ "Type": "mark_price_subscribed", "Data": { "connectionId": 1, "ticker": "BTCUSDT" } }

// Mark price update pushed by server
{ "Type": "mark_price_update", "Data": { "connectionId": 1, "ticker": "BTCUSDT", "markPrice": 65123.5 } }

// Subscribe to funding for a specific ticker (perpetual futures only)
{ "Type": "funding_subscribe", "Data": { "connectionId": 1, "ticker": "BTCUSDT" } }

// Server confirms funding subscription
{ "Type": "funding_subscribed", "Data": { "connectionId": 1, "ticker": "BTCUSDT" } }

// Funding update pushed by server
{ "Type": "funding_update", "Data": { "connectionId": 1, "ticker": "BTCUSDT", "fundingRate": 0.0001, "fundingTime": "2026-03-16T16:00:00+00:00" } }

// Unsubscribe from market data
{ "Type": "trade_unsubscribe", "Data": { "connectionId": 1, "ticker": "BTCUSDT" } }
{ "Type": "orderbook_unsubscribe", "Data": { "connectionId": 1, "ticker": "BTCUSDT" } }
{ "Type": "mark_price_unsubscribe", "Data": { "connectionId": 1, "ticker": "BTCUSDT" } }
{ "Type": "funding_unsubscribe", "Data": { "connectionId": 1, "ticker": "BTCUSDT" } }

// Unsubscribe from connection
{ "Type": "unsubscribe", "Data": { "connectionId": 1 } }

// Error (invalid connection)
{ "Type": "error", "Data": { "error": "Connection 999 not found or not active" } }