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.

Both shapes accept an optional activate boolean (default true) that decides whether the newly opened combo takes focus:

• activate: true or the field omitted — the combo opens and becomes the active/focused layout (unchanged default). On the tickers form, exactly one window (the last in the list) comes to the front, as today.
• activate: false — the combo opens in the background: whatever window/tab you were on stays active. On the tickers form, no element of the list steals focus.

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. Each time column holds bid/ask volumes at every price level; columns are ordered oldest first, newest last. Without Columns the response has the classic shape: 100 time columns of which only the newest 10 carry data (the cluster backend's default page), the rest are empty time slots. With Columns=N the response holds exactly N columns (the newest N), all filled from backend history.

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), ZoomStepMode (Linear, Logarithmic), SizeType (Coin, Usd).

Ticks section: ShowExecutedOrders (boolean, default true; absent behaves as true) paints the terminal's own executed-order overlay (fill chips + position-size chip) on the tape — set false to hide it.

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 }.

Column numbers (type) — the same in /data and in screener_frame; the value is the terminal's internal column id, so the list is re-issued whenever the terminal adds or removes a column (last change: MET-1827 removed Activity, the former 7, and every later column moved down by one — builds up to Beta 1.0.756 still send the old numbers). Current numbers (Dev 1.0.4357 and later, MET-1833): 2 Volume $ · 3 Trades · 4 Change % · 5 NATR % · 6 Spread % · 7 Funding % · 8 Next funding time (epoch seconds) · 9 Funding interval (seconds) · 10 Volume spike % · 11 Trades spike % · 12 OI change % · 13 OI change $ · 14 Δ volume % · 15 Δ volume $ · 16 Price. (0 Actions and 1 Ticker are window-only columns and carry no 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.

Closes the ONE tab addressed by {tabId} through the app's OWN tab-close path (the same teardown the tab's own × runs — every document in the tab is torn down and its DB rows deleted). {tabId} is the id a tab carries under GET /api/ui/state (Window → Tab). Tab ids are globally unique, so no window type is needed — the id alone addresses the tab, and the window it belongs to and its sibling tabs stay open.

No request body is required (an empty body or {} is accepted).

Response { tabId, closed, outcome }.

Unlike a hand-close, the API path raises NO confirmation prompt (a modal would block the HTTP response); the interactive prompt — and its «Show a warning when closing windows and tabs» setting — is unchanged.

A window's ONLY tab cannot be closed → 400 with a message (it would leave an empty workspace); there is no silent no-op.

Errors: a non-numeric {tabId} → 400 Invalid tab ID; a malformed body or an unknown body property → 400; an id no open window hosts → 404 Tab {tabId} not found. — all validated before any tab is closed.

Makes the tab addressed by {tabId} the selected one in its window, by driving the SAME header selection a user's tab click drives (which also persists it). Same id-addressing as the close route; no request body is required. Idempotent when the tab is already selected.

Response { tabId, activated, outcome }.

Errors: a non-numeric {tabId} → 400 Invalid tab ID; a malformed body or an unknown body property → 400; an id no open window hosts → 404 Tab {tabId} not found.

Closes the main workspace window's LAST tab through the tab's own close path (no confirmation prompt). It never closes the only remaining tab. This is a fixed-target convenience route (no id) — to close a SPECIFIC tab by id, use POST /api/ui/tabs/{tabId}/close.

No request body is required. Response { status } — "ok" when a tab was closed, "skipped" when only one tab remained.

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 an individual panel (a single order book or chart inside a tab) is not yet available. Whole-window lifecycle and per-tab close/activate ARE available (see the routes above); only the panel-level routes below remain deferred. 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: