Workspace

Reading the layout needs the workspace:read scope. Changing it needs workspace:write. A stack is an order book with its trade tape and clusters.

Read the layoutCopy Anchor Link

workspace = terminal.workspace()
for window in workspace.windows:
    for tab in window.tabs:
        print(window.id, tab.id, tab.name, [stack.instrument for stack in tab.stacks])

The answer lists every window with its tabs, and every tab with its stacks and charts. Every field is in the reference.

Ids are valid for one runCopy Anchor Link

A window and a tab have an id, a stack and a chart have a widget_id. Tabs are numbered inside each window, so a tab is addressed by window and tab together.

All ids are valid only for the current run of the terminal. After a restart, read the layout again.

Open a stackCopy Anchor Link

opened = terminal.open_stack("binance:futures:BTCUSDT", chart=True)
print(opened.window_id, opened.tab_id, opened.stacks, opened.charts)

The answer names the window, the tab and the widget ids of what was opened. Every command on this page answers in this shape.

Open a tab with several instrumentsCopy Anchor Link

from spectre_terminal import TabItem

opened = terminal.open_tab(
    [TabItem("binance:futures:BTCUSDT", chart=True), "binance:futures:ETHUSDT"],
    name="Majors",
)
print(opened.tab_id, opened.stacks, opened.charts)

Each item becomes a column, in the order of the list. A list holds from 1 to 50 items, and name is up to 64 characters. If one item is refused, nothing is opened.

target, window_id and activate work as in Open a stack.

Add stacks to a tabCopy Anchor Link

added = terminal.add_stacks(1, 2, ["binance:futures:SOLUSDT"])
print(added.stacks, added.charts)

The first two arguments are the window and the tab. The new columns go after the last one. The answer lists only the added widgets.

Open a coin on every exchangeCopy Anchor Link

opened = terminal.open_multiview("BTC", target="new_window")
print(opened.window_id, opened.stacks, opened.charts)

This is the Multiview button of the terminal: the coin opens on every exchange enabled in the "Exchange layout" setting. Pass a coin, BTC, or a pair, BTC/USDT. Without target the terminal follows its own Multiview setting.

Change the instrument of a stackCopy Anchor Link

terminal.set_stack_instrument(14, "binance:futures:ETHUSDT")

The first argument is the widget_id of a stack. Its charts switch too.

Close a stack, a tab or a windowCopy Anchor Link

terminal.close_stack(14)
terminal.close_tab(1, 2)
terminal.close_window(2)

There is no confirmation. The main window, marked main in the layout, and the only tab of a window cannot be closed: the call answers 400 invalid_request.

Bring a tab or a window to the frontCopy Anchor Link

terminal.activate_tab(1, 2)
terminal.activate_window(2)

The first call selects the tab without changing the focus of the window. The second brings the window to the front.

Follow changesCopy Anchor Link

import asyncio
from spectre_terminal import Event

async def main():
    async with terminal.stream() as stream:
        await stream.subscribe("workspace")
        async for frame in stream:
            if isinstance(frame, Event) and frame.topic == "workspace":
                for window in frame.data.windows:
                    print(window.id, [tab.name for tab in window.tabs])

asyncio.run(main())

The first frame is the current layout. Then a frame with the whole layout comes for every change. More in Streaming.

When a command failsCopy Anchor Link

What is not availableCopy Anchor Link

The API does not move stacks between tabs, change the widths of columns, or control other windows such as the screener.