Getting started

This page takes you from a running terminal to live data in your own program. Your program talks only to 127.0.0.1, and the terminal talks to the exchanges.

Switch the API onCopy Anchor Link

Open Settings App → General in the terminal and switch Local API on. No restart is needed.

The row shows the port. It is 48180 unless the terminal was started with the SPECTRE_LOCAL_API_PORT environment variable. Switching the API off later closes open streams with code 1001.

Get the tokenCopy Anchor Link

Press Copy token in the same row and put the token into the environment of your program. The value below is a sample.

export SPECTRE_LOCAL_API_TOKEN=spt_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

On Windows, setx works for command windows opened after it.

The token allows everything the terminal window can do, including placing orders. Do not commit it or paste it into a bug report. Reissue token in the same row replaces it at once.

Install a clientCopy Anchor Link

pip install spectre-terminal

Make the first requestCopy Anchor Link

from spectre_terminal import Terminal

terminal = Terminal.discover()
meta = terminal.meta()
print(meta.app_version, meta.scopes, meta.topics)

discover() finds the port, reads the token from the environment and makes one test request. A wrong token or a terminal that is not running fails here, not on the first data call. See When discovery fails.

Read somethingCopy Anchor Link

for connection in terminal.connections():
    print(connection.id, connection.exchange, connection.market, connection.status.state)

book = terminal.orderbook("binance:futures:BTCUSDT", depth=5)
for price, size in book.bids:
    print(price, size)

An instrument has an address: exchange:market:symbol. The symbol is written the way the exchange writes it. See Market data.

Follow live dataCopy Anchor Link

import asyncio

async def main():
    async with terminal.stream() as stream:
        await stream.subscribe("trades", "binance:futures:BTCUSDT")
        async for frame in stream:
            print(frame)

asyncio.run(main())

The loop prints trades as they arrive. See Streaming.

What is not availableCopy Anchor Link

The answer of a trading call does not tell what the exchange did. accepted means the terminal took the command. Read the outcome from the account, see Trading.

The Moscow Exchange (MOEX) is not served: no market data and no trading.

Requests from browser pages are refused.