MCP tools
Every tool of the spectre-terminal-mcp server: what it does, what it takes and whether it changes anything.
All tools
| Tool | Access | What it does |
|---|---|---|
account_overview | read-only | Balances, open positions with PnL and how many orders are open, for one connection. |
leverage | read-only | Leverage, its maximum, the terminal's leverage mode and the margin mode of an instrument. |
open_orders | read-only | Open orders and trigger orders of a connection, with the key and exchange id of each. |
recent_fills | read-only | The latest fills of a connection, oldest first, with buy and sell volume totals. |
find_instrument | read-only | Find the exact instrument address for a coin or symbol. |
market_snapshot | read-only | Last price, best bid and ask with the spread, mark price and 24h change and volume. |
order_book_top | read-only | The top levels of the order book with volume per side and the imbalance. |
recent_trades_summary | read-only | Buy and sell volume, delta, VWAP, price range and the largest print of recent trades. |
cluster_summary | read-only | Volume clusters per bucket. |
candles | read-only | OHLCV bars for an interval, newest limit bars, oldest first. |
settings | read-only | Settings rows as stored, with whether each is writable through update_settings. |
orderbook_settings | read-only | The stack settings of one instrument as its stack on the connection sees them. |
update_settings | changes state | Write settings the way the terminal's settings window does. |
terminal_status | read-only | Check that Spectre Terminal is running and list its exchange connections. |
place_order | changes state | Place a limit or market order on a connection. |
cancel_order | changes state | Cancel one order by the terminal's key or the exchange's id. |
cancel_all_orders | changes state | Cancel every open order of the instrument on this connection. |
close_position | changes state | Close the instrument's position the way the terminal window does. |
place_trigger | changes state | Place a stop loss, take profit or stop the way the window does. |
cancel_trigger | changes state | Cancel one trigger order by its numeric id from open_orders. |
cancel_all_triggers | changes state | Cancel every trigger order of the instrument; plain orders stay. |
amend_trigger | changes state | Move a trigger to a new price (cancel, then place). |
set_leverage | changes state | Set the leverage of a futures instrument the way the window does. |
set_margin_mode | changes state | Set the margin mode of a futures instrument. |
workspace | read-only | Every window of the terminal with its tabs, stacks (order books) and charts. |
open_stack | changes state | Open a stack of the instrument in a new tab or a new window, optionally with a chart. |
open_tab | changes state | Open one tab with several instruments. |
add_stacks | changes state | Add instruments to an existing tab. |
open_multiview | changes state | Open a coin on every venue of «Exchange layout», as the Multiview button does. |
set_stack_instrument | changes state | Switch a stack (and the charts that follow it) to another instrument. |
close_stack | changes state | Close one stack, as its close button does. |
close_tab | changes state | Close a tab of a window. |
activate_tab | changes state | Select a tab in its window; the window's focus is untouched (see activate_window). |
close_window | changes state | Close a window. |
activate_window | changes state | Restore a window if it is minimised and bring it to the front. |
Account
account_overview
read-only
Balances, open positions with PnL and how many orders are open, for one connection.
The cheapest way to answer "what is this account holding". Balances and fills are what the terminal has accumulated since its API was switched on; positions and orders are live state.
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
leverage
read-only
Leverage, its maximum, the terminal's leverage mode and the margin mode of an instrument.
Read from the terminal's cache: an instrument the terminal has not
touched yet answers not_active — open it in the terminal or set
the leverage with set_leverage.
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Futures instrument address exchange:market:symbol |
open_orders
read-only
Open orders and trigger orders of a connection, with the key and exchange id of each.
Use the key (t-…) to cancel an order placed through the API,
and to recognise it after place_order.
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentoptional | str | None | Only this instrument (exchange:market:symbol); all when omitted |
recent_fills
read-only
The latest fills of a connection, oldest first, with buy and sell volume totals.
Fills are kept by the terminal since its API was switched on (the last 1000 per connection); older history is not available here.
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
limitoptional | int | Newest fills to return Default: 20. |
since_tsoptional | int | None | Only fills at or after this UTC millisecond timestamp |
Instruments
find_instrument
read-only
Find the exact instrument address for a coin or symbol.
Searches the catalogue of the terminal's connections — one connection,
one exchange, or all of them — and returns matches best first: an
exact symbol or base coin, then the same base behind a numeric prefix
(1000PEPE), then prefixes. Use the instrument field of a match in
every other tool.
| Parameter | Type | Description |
|---|---|---|
queryrequired | str | Coin or symbol fragment, case-insensitive: BTC, ETHUSDT, SOL-USDT |
exchangeoptional | str | None | Exchange in lower case: binance, bybit, okx, …; all when omitted |
marketoptional | str | None | spot or futures; both when omitted |
connection_idoptional | int | None | Search one connection only (from terminal_status) |
limitoptional | int | Matches to return Default: 10. |
Market data
market_snapshot
read-only
Last price, best bid and ask with the spread, mark price and 24h change and volume.
The cheapest way to answer "where is X trading right now". Fields the terminal has not received yet are null; for an instrument that is not open in the terminal the tool waits briefly once to fill them.
| Parameter | Type | Description |
|---|---|---|
instrumentrequired | str | Instrument address exchange:market:symbol |
connection_idoptional | int | None | Connection id from terminal_status; it must trade (keys, enabled) |
order_book_top
read-only
The top levels of the order book with volume per side and the imbalance.
imbalance is (bid volume - ask volume) / (bid volume + ask volume)
over the returned levels: +1 is all bids, -1 is all asks. Levels are
[price, size] pairs, bids from the best price down, asks from the best
price up.
| Parameter | Type | Description |
|---|---|---|
instrumentrequired | str | Instrument address exchange:market:symbol |
depthoptional | int | Levels per side Default: 10. |
connection_idoptional | int | None | Connection id from terminal_status; it must trade (keys, enabled) |
recent_trades_summary
read-only
Buy and sell volume, delta, VWAP, price range and the largest print of recent trades.
Summarises the latest limit trades the terminal has for the
instrument (it keeps the last 1000). The trades themselves are not
returned; span_ms says how much time the batch covers.
| Parameter | Type | Description |
|---|---|---|
instrumentrequired | str | Instrument address exchange:market:symbol |
limitoptional | int | How many of the latest trades to summarise Default: 200. |
connection_idoptional | int | None | Connection id from terminal_status; it must trade (keys, enabled) |
cluster_summary
read-only
Volume clusters per bucket: volume by side, delta, VWAP, range, busiest price levels.
Buckets are at the interval the trader selected in the terminal for
this instrument (5m by default); the newest bucket is usually still
open (completed false). An instrument the terminal was not
computing yet is started on request and seeded with history; the tool
waits once for the seed.
| Parameter | Type | Description |
|---|---|---|
instrumentrequired | str | Instrument address exchange:market:symbol |
bucketsoptional | int | Newest buckets to return Default: 3. |
top_levelsoptional | int | Price levels per bucket, by volume Default: 5. |
connection_idoptional | int | None | Connection id from terminal_status; it must trade (keys, enabled) |
candles
read-only
OHLCV bars for an interval, newest limit bars, oldest first.
Rows are compact arrays under columns. ts is the bar open;
closed false marks the bar still forming. Page backwards by
passing the first row's ts as end.
| Parameter | Type | Description |
|---|---|---|
instrumentrequired | str | Instrument address exchange:market:symbol |
intervaloptional | str | Bar interval: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w, 1M Default: '1m'. |
limitoptional | int | Newest bars to return Default: 50. |
endoptional | int | None | Right boundary as UTC milliseconds; now when omitted |
connection_idoptional | int | None | Connection id from terminal_status; it must trade (keys, enabled) |
Settings
settings
read-only
Settings rows as stored, with whether each is writable through update_settings.
Without arguments: the terminal-wide rows (multiview, chart, sounds,
hotkeys, …). The settings of one stack, resolved the way the stack
sees them, are orderbook_settings.
| Parameter | Type | Description |
|---|---|---|
scopeoptional | str | None | global (default) or order_book |
categoryoptional | str | None | Category filter |
keyoptional | str | None | Key filter |
connection_idoptional | int | None | The connection's rows; else app-wide |
instrumentoptional | str | None | The pair's rows (scope order_book) |
orderbook_settings
read-only
The stack settings of one instrument as its stack on the connection sees them.
Every key names the level it was resolved from: the pair's own row, the connection's default, the pair's row without a connection, or the global default.
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status |
instrumentrequired | str | Instrument address exchange:market:symbol |
update_settings
changes state
Write settings the way the terminal's settings window does.
A change with instrument writes the pair's row; scope
order_book with connection_id the connection's default; neither
the global default. Every change is checked first — unknown key,
wrong type, out of range, wrong shape — and refused by index with
nothing written; leverage is refused (use set_leverage). The
first failed change stops the list; earlier ones stay applied.
| Parameter | Type | Description |
|---|---|---|
changesrequired | list[dict[str, Any]] | Changes in order; each has category, key, value and optionally scope (global or order_book), instrument and connection_id |
Status
terminal_status
read-only
Check that Spectre Terminal is running and list its exchange connections.
Returns the terminal version, API health, the stream topics it serves, the limits that matter for an agent, and every connection with its id, exchange, market and state. Call this first when a session starts or when another tool reports the terminal unreachable.
Trading
place_order
changes state
Place a limit or market order on a connection. Answers "accepted", not "filled".
Give exactly one of size (base coin) or notional (quote
amount). Prices and amounts are decimal strings; the terminal checks
the venue's minimums and steps before sending and refuses with the
reason. Watch open_orders for the returned key.
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Instrument address exchange:market:symbol |
siderequired | str | buy or sell |
order_typerequired | str | limit (needs price) or market (no price) |
client_keyrequired | str | Your idempotency key for this intent, e.g. 'rebalance-2026-11-03-1'. A retry with the same key returns the previous answer and places nothing. |
priceoptional | str | None | Limit price as a decimal string |
sizeoptional | str | None | Amount in the base coin as a decimal string |
notionaloptional | str | None | Amount in the quote currency as a decimal string |
reduce_onlyoptional | bool | Only reduce an existing position Default: False. |
post_onlyoptional | bool | Reject instead of taking liquidity Default: False. |
time_in_forceoptional | str | None | gtc, ioc, fok or post_only; the venue's default when omitted |
cancel_order
changes state
Cancel one order by the terminal's key or the exchange's id. Answers "accepted".
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Instrument address exchange:market:symbol |
order_idrequired | str | The terminal key (t-…) from open_orders or the exchange's order id |
cancel_all_orders
changes state
Cancel every open order of the instrument on this connection. Answers "accepted".
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Instrument address exchange:market:symbol |
close_position
changes state
Close the instrument's position the way the terminal window does. Answers "accepted".
Futures: a market order for the whole position. Spot: cancel all and sell as one atomic command. Refused when there is no open position.
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Instrument address exchange:market:symbol |
place_trigger
changes state
Place a stop loss, take profit or stop the way the window does. Answers "accepted".
The returned key (sl_…, tp_…, stop_…) shows up as
client_id of the trigger in open_orders; cancel or move it by
the numeric id from there. Refused without an open position for
stop_loss/take_profit, and with unsupported on a venue
without trigger orders in the terminal.
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Instrument address exchange:market:symbol |
kindrequired | str | stop_loss or take_profit (placed on the open position: its side, size and rule come from the position) or stop (your own side and notional) |
trigger_pricerequired | str | Trigger price as a decimal string |
client_keyrequired | str | Your idempotency key for this intent. A retry with the same key returns the previous answer and places nothing. |
sideoptional | str | None | stop only: buy or sell |
notionaloptional | str | None | stop only: amount in the quote currency, decimal string |
ruleoptional | str | None | stop only: price_above_or_equal or price_below_or_equal; omitted means above the market for a buy, below for a sell |
cancel_trigger
changes state
Cancel one trigger order by its numeric id from open_orders. Answers "accepted".
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Instrument address exchange:market:symbol |
trigger_idrequired | str | The numeric id of the trigger from open_orders |
cancel_all_triggers
changes state
Cancel every trigger order of the instrument; plain orders stay. Answers "accepted".
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Instrument address exchange:market:symbol |
amend_trigger
changes state
Move a trigger to a new price (cancel, then place). Answers "accepted".
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Instrument address exchange:market:symbol |
trigger_idrequired | str | The numeric id of the trigger from open_orders |
kindrequired | str | stop_loss, take_profit or stop — the trigger's type |
trigger_pricerequired | str | New trigger price as a decimal string |
sideoptional | str | None | stop only: buy or sell |
ruleoptional | str | None | stop only: price_above_or_equal or price_below_or_equal |
set_leverage
changes state
Set the leverage of a futures instrument the way the window does. Answers "accepted".
Exactly one of leverage and mode. Read the applied value with
leverage after the exchange answered.
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Instrument address exchange:market:symbol |
leverageoptional | int | None | Leverage as an integer of at least 1; or give mode |
modeoptional | str | None | max or smart (the terminal's modes); or give leverage |
set_margin_mode
changes state
Set the margin mode of a futures instrument. Answers "accepted".
The exchange refuses the change while a position is open, as in the window; the accepted answer does not know that yet.
| Parameter | Type | Description |
|---|---|---|
connection_idrequired | int | Connection id from terminal_status; it must trade (keys, enabled) |
instrumentrequired | str | Instrument address exchange:market:symbol |
margin_moderequired | str | cross or isolated |
Workspace
workspace
read-only
Every window of the terminal with its tabs, stacks (order books) and charts.
The main window cannot be closed; tabs are numbered per window; stack and chart widget ids are global. Read this before any workspace command: the ids change with every run of the terminal.
open_stack
changes state
Open a stack of the instrument in a new tab or a new window, optionally with a chart.
Answers the window, the new tab and the new widget ids. An instrument
the terminal's catalogue does not know is invalid_request.
| Parameter | Type | Description |
|---|---|---|
instrumentrequired | str | Instrument address exchange:market:symbol |
connection_idoptional | int | None | Connection; the general rule picks one |
chartoptional | bool | Open a chart over the stack Default: False. |
targetoptional | str | new_tab (in window_id, or the focused window) or new_window Default: 'new_tab'. |
window_idoptional | int | None | Window for the new tab |
activateoptional | bool | False opens the tab in the background; a new window always takes focus Default: True. |
open_tab
changes state
Open one tab with several instruments: a column per item, in a new tab or window.
Each item is a stack and, with chart, a chart over it. One to
fifty items. Answers the window, the new tab and the new widget ids
in column order. A refusal names the item (items[1]: …) and
nothing is opened.
| Parameter | Type | Description |
|---|---|---|
itemsrequired | list[dict[str, Any]] | Columns in order; each has instrument (exchange:market:symbol) and optionally connection_id and chart (true opens a chart over the stack) |
nameoptional | str | None | Tab name, up to 64 characters; None names it after the instruments |
targetoptional | str | new_tab (in window_id, or the focused window) or new_window Default: 'new_tab'. |
window_idoptional | int | None | Window for the new tab |
activateoptional | bool | False opens the tab in the background; a new window always takes focus Default: True. |
add_stacks
changes state
Add instruments to an existing tab: a column per item after the tab's last column.
The tab keeps its name and its column widths. Answers only the
added stack and chart widget ids. No such window or tab is
not_found.
| Parameter | Type | Description |
|---|---|---|
window_idrequired | int | Window id from the workspace tool |
tab_idrequired | int | Tab id from the workspace tool; tabs are numbered per window |
itemsrequired | list[dict[str, Any]] | Columns in order; each has instrument (exchange:market:symbol) and optionally connection_id and chart (true opens a chart over the stack) |
open_multiview
changes state
Open a coin on every venue of «Exchange layout», as the Multiview button does.
not_found when no enabled row of the layout lists the coin.
| Parameter | Type | Description |
|---|---|---|
baserequired | str | Coin (BTC) or pair (BTC/USDT) |
targetoptional | str | None | new_tab or new_window; None follows the terminal setting |
window_idoptional | int | None | Window for the new tab |
activateoptional | bool | False opens the tab in the background; a new window always takes focus Default: True. |
set_stack_instrument
changes state
Switch a stack (and the charts that follow it) to another instrument.
| Parameter | Type | Description |
|---|---|---|
widget_idrequired | int | Stack widget_id from the workspace tool |
instrumentrequired | str | Instrument address exchange:market:symbol |
connection_idoptional | int | None | Connection; the general rule picks one |
close_stack
changes state
Close one stack, as its close button does. A chart widget id is invalid_request.
| Parameter | Type | Description |
|---|---|---|
widget_idrequired | int | Stack widget_id from the workspace tool |
close_tab
changes state
Close a tab of a window. The only tab of a window cannot be closed.
| Parameter | Type | Description |
|---|---|---|
window_idrequired | int | Window id from the workspace tool |
tab_idrequired | int | Tab id from the workspace tool; tabs are numbered per window |
activate_tab
changes state
Select a tab in its window; the window's focus is untouched (see activate_window).
| Parameter | Type | Description |
|---|---|---|
window_idrequired | int | Window id from the workspace tool |
tab_idrequired | int | Tab id from the workspace tool; tabs are numbered per window |
close_window
changes state
Close a window. The main window is refused: closing it would quit the terminal.
| Parameter | Type | Description |
|---|---|---|
window_idrequired | int | Window id from the workspace tool |
activate_window
changes state
Restore a window if it is minimised and bring it to the front.
| Parameter | Type | Description |
|---|---|---|
window_idrequired | int | Window id from the workspace tool |
Generated from the code of spectre-terminal-mcp at commit 2d1c324.