TypeScript SDK

Terminal()Скопіювати посилання на розділ

new Terminal(options: TerminalOptions)

discover()Скопіювати посилання на розділ

static discover(options: DiscoverOptions = {}): Promise<Terminal>

Знайти термінал і перевірити його: токен — з options.token або SPECTRE_LOCAL_API_TOKEN (інакше TokenMissingError), порт — з options.port або instance.json (інакше 48180; LocalApiDisabledError, коли файл каже, що API вимкнено), потім один GET /v1/meta. api_version, відмінна від "1", — це IncompatibleTerminalError; відповідь unauthorized — це ApiError, повідомлення якої каже, що токен може бути застарілим або API вимкнено.

meta()Скопіювати посилання на розділ

meta(): Promise<Meta>

GET /v1/meta: версія API, збірка, права токена, ліміти, топіки стріму.

Операція HTTP: GET /v1/meta

health()Скопіювати посилання на розділ

health(): Promise<Health>

GET /v1/health.

Операція HTTP: GET /v1/health

connections()Скопіювати посилання на розділ

connections(): Promise<List<Connection>>

GET /v1/connections (connections:read).

Операція HTTP: GET /v1/connections

connection()Скопіювати посилання на розділ

connection(id: number): Promise<Connection>

GET /v1/connections/{id} (connections:read); not_found для невідомого id.

Операція HTTP: GET /v1/connections/{id}

instruments()Скопіювати посилання на розділ

instruments(options: InstrumentsOptions): Promise<InstrumentsPage>

GET /v1/instruments (market:read): одна сторінка довідника біржі й ринку, за connectionId або exchange + market. Ідіть за next_cursor вручну або використовуйте iterInstruments.

Операція HTTP: GET /v1/instruments

iterInstruments()Скопіювати посилання на розділ

iterInstruments(options: InstrumentsOptions): AsyncGenerator<Instrument, void, undefined>

Усі інструменти, що відповідають параметрам, сторінка за сторінкою.

intervals()Скопіювати посилання на розділ

intervals(): Promise<Intervals>

GET /v1/market/intervals (market:read): інтервали свічок і кластерів.

Операція HTTP: GET /v1/market/intervals

candles()Скопіювати посилання на розділ

candles(instrument: InstrumentAddress, options: CandlesOptions): Promise<Candles>

GET /v1/market/candles (market:read): історія свічок, від старих до нових.

Операція HTTP: GET /v1/market/candles

trades()Скопіювати посилання на розділ

trades(instrument: InstrumentAddress, options: TradesOptions = {}): Promise<Trades>

GET /v1/market/trades (market:read): останні угоди пари, від старих до нових. Пара без підписки відкривається на вимогу, і виклик може тривати до 3 с.

Операція HTTP: GET /v1/market/trades

snapshot()Скопіювати посилання на розділ

snapshot(instrument: InstrumentAddress, options: ConnectionOptions = {}): Promise<Snapshot>

GET /v1/market/snapshot (market:read): найкращі bid/ask, остання угода, ціна маркування, тікер.

Операція HTTP: GET /v1/market/snapshot

orderbook()Скопіювати посилання на розділ

orderbook(instrument: InstrumentAddress, options: OrderbookOptions = {}): Promise<Orderbook>

GET /v1/market/orderbook (market:read); unavailable, якщо повний стакан не надійшов за 3 с.

Операція HTTP: GET /v1/market/orderbook

clusters()Скопіювати посилання на розділ

clusters(instrument: InstrumentAddress, options: ConnectionOptions = {}): Promise<Clusters>

GET /v1/market/clusters (market:read): до десяти бакетів за інтервалом, вибраним у терміналі. Перший виклик для інструмента, не відкритого у вікні, може відповісти not_active (409); повтор за кілька секунд знаходить кластери.

Операція HTTP: GET /v1/market/clusters

accountOrders()Скопіювати посилання на розділ

accountOrders(connectionId: number): Promise<AccountOrders>

GET /v1/account/orders (account:read): відкриті заявки й тригерні заявки одного підключення, той самий зріз, який бачить вікно термінала. not_found для невідомого підключення.

Операція HTTP: GET /v1/account/orders

accountPositions()Скопіювати посилання на розділ

accountPositions(connectionId: number): Promise<AccountPositions>

GET /v1/account/positions (account:read): відкриті позиції одного підключення.

Операція HTTP: GET /v1/account/positions

accountBalances()Скопіювати посилання на розділ

accountBalances(connectionId: number): Promise<AccountBalances>

GET /v1/account/balances (account:read): для кожної валюти — останнє значення, яке біржа надіслала відтоді, як увімкнено API. Валюти, з якою відтоді нічого не відбувалося, немає.

Операція HTTP: GET /v1/account/balances

accountFills()Скопіювати посилання на розділ

accountFills(connectionId: number, options: AccountFillsOptions = {}): Promise<AccountFills>

GET /v1/account/fills (account:read): виконання підключення відтоді, як увімкнено API (остання тисяча), від старих до нових.

Операція HTTP: GET /v1/account/fills

placeOrder()Скопіювати посилання на розділ

placeOrder(options: PlaceOrderOptions): Promise<Accepted>

POST /v1/orders (trading:write): поставити лімітну або ринкову заявку тією самою командою, що й вікно. Відповідь означає «прийнято терміналом», а не біржею: стежте за account.orders у стрімі або за accountOrders, де заявка з’явиться під key. not_tradable (409) для вимкненого підключення, підключення лише для читання або без облікових даних, invalid_request (400) для чужого інструмента чи відхиленого розміру або ціни, rate_limited (429) понад limits.commands_per_second.

Операція HTTP: POST /v1/orders

cancelOrder()Скопіювати посилання на розділ

cancelOrder(options: CancelOrderOptions): Promise<Accepted>

DELETE /v1/orders/{id} (trading:write): скасувати одну заявку за ключем термінала (t-…) або ідентифікатором біржі. Скасування йде на біржу напряму; підтвердження надходить через стрім.

Операція HTTP: DELETE /v1/orders/{id}

cancelAll()Скопіювати посилання на розділ

cancelAll(options: InstrumentCommandOptions): Promise<Accepted>

POST /v1/orders/cancel-all (trading:write): скасувати всі заявки інструмента, як це робить пробіл.

Операція HTTP: POST /v1/orders/cancel-all

closePosition()Скопіювати посилання на розділ

closePosition(options: InstrumentCommandOptions): Promise<Accepted>

POST /v1/positions/close (trading:write): закрити позицію інструмента так, як це робить вікно — ринковою заявкою на розмір позиції на ф’ючерсах, «скасувати все й закрити» однією атомарною командою на споті. invalid_request без відкритої позиції.

Операція HTTP: POST /v1/positions/close

placeTrigger()Скопіювати посилання на розділ

placeTrigger(options: PlaceTriggerOptions): Promise<Accepted>

POST /v1/orders/trigger (trading:write): стоп-лос, тейк-профіт або стоп, поставлений тими самими сервісами, що й у вікні. stop_loss і take_profit ставляться на відкриту позицію (сторона, розмір і правило беруться з неї; без позиції — invalid_request); stop потребує side і notional. key у відповіді — це ключ тригера (sl_…, tp_…, stop_…), який з’являється як client_id тригера в accountOrders; скасування і зміна використовують числовий id звідти. unsupported (501) на біржі без тригерних заявок у терміналі.

Операція HTTP: POST /v1/orders/trigger

cancelTrigger()Скопіювати посилання на розділ

cancelTrigger(options: CancelTriggerOptions): Promise<Accepted>

DELETE /v1/orders/trigger/{id} (trading:write): скасувати один тригер за його числовим id.

Операція HTTP: DELETE /v1/orders/trigger/{id}

cancelAllTriggers()Скопіювати посилання на розділ

cancelAllTriggers(options: InstrumentCommandOptions): Promise<Accepted>

POST /v1/orders/trigger/cancel-all (trading:write): скасувати всі тригери інструмента; звичайні заявки лишаються.

Операція HTTP: POST /v1/orders/trigger/cancel-all

amendTrigger()Скопіювати посилання на розділ

amendTrigger(options: AmendTriggerOptions): Promise<Accepted>

PATCH /v1/orders/trigger/{id} (trading:write): перенести тригер на нову ціну — послідовна заміна, як у вікні: скасувати, потім поставити. kind обов’язковий; stop потребує ще й свого side. key дорівнює null.

Операція HTTP: PATCH /v1/orders/trigger/{id}

leverage()Скопіювати посилання на розділ

leverage(options: InstrumentCommandOptions): Promise<Leverage>

GET /v1/account/leverage (account:read): плече і режим маржі ф’ючерсного інструмента з кешу термінала. Інструмент, якого термінал ще не торкався, — це not_active (409): відкрийте його у вікні або викличте setLeverage — так він потрапляє в кеш.

Операція HTTP: GET /v1/account/leverage

setLeverage()Скопіювати посилання на розділ

setLeverage(options: SetLeverageOptions): Promise<Accepted>

POST /v1/account/leverage (trading:write): встановити плече так, як це робить вікно — рівно одне з leverage (ціле число ≥ 1) і mode (max, smart). Застосоване значення видно в leverage після відповіді біржі.

Операція HTTP: POST /v1/account/leverage

setMarginMode()Скопіювати посилання на розділ

setMarginMode(options: SetMarginModeOptions): Promise<Accepted>

POST /v1/account/margin-mode (trading:write): cross або isolated. Зміну з відкритою позицією біржа відхиляє, як і у вікні; відповідь accepted цього ще не знає.

Операція HTTP: POST /v1/account/margin-mode

workspace()Скопіювати посилання на розділ

workspace(): Promise<Workspace>

GET /v1/workspace (workspace:read): усі вікна з їхніми вкладками, стеками та графіками, зі знімка, який вікно публікує на кожну структурну зміну. Ідентифікатори внутрішні для цього запуску термінала.

Операція HTTP: GET /v1/workspace

workspaceWindow()Скопіювати посилання на розділ

workspaceWindow(options: WindowOptions): Promise<WorkspaceWindow>

GET /v1/workspace/windows/{id} (workspace:read): одне вікно; невідомий id — це not_found.

Операція HTTP: GET /v1/workspace/windows/{id}

openStack()Скопіювати посилання на розділ

openStack(options: OpenStackOptions): Promise<WorkspaceOutcome>

POST /v1/workspace/stacks (workspace:write): стек інструмента в новій вкладці або новому вікні, з графіком над ним, якщо задано chart. Відповідь називає вікно, вкладку й нові віджети. Інструмент, якого немає в довіднику термінала, — це invalid_request.

Операція HTTP: POST /v1/workspace/stacks

openTab()Скопіювати посилання на розділ

openTab(options: OpenTabOptions): Promise<WorkspaceOutcome>

POST /v1/workspace/tabs (workspace:write): вкладка з колонкою на кожен елемент — стек і, з chart, графік над ним — у новій вкладці або новому вікні. Без name назва — це єдиний інструмент або перший плюс кількість інших. Відмова називає елемент (items[1]: …), і до вікна не доходить нічого.

Операція HTTP: POST /v1/workspace/tabs

addStacks()Скопіювати посилання на розділ

addStacks(options: AddStacksOptions): Promise<WorkspaceOutcome>

POST /v1/workspace/windows/{id}/tabs/{tab}/stacks (workspace:write): ті самі колонки після останньої колонки вкладки; вкладка зберігає назву й ширини колонок. Відповідь перелічує лише додані віджети.

Операція HTTP: POST /v1/workspace/windows/{id}/tabs/{tab}/stacks

openMultiview()Скопіювати посилання на розділ

openMultiview(options: OpenMultiviewOptions): Promise<WorkspaceOutcome>

POST /v1/workspace/multiview (workspace:write): монета на всіх біржах «Розкладки бірж», той самий план, що й у кнопки «Мультив’ю» вікна. Жодної комірки для монети — not_found.

Операція HTTP: POST /v1/workspace/multiview

setStackInstrument()Скопіювати посилання на розділ

setStackInstrument(options: StackInstrumentOptions): Promise<WorkspaceOutcome>

PATCH /v1/workspace/stacks/{widget_id} (workspace:write): інший інструмент у стеку та його графіках.

Операція HTTP: PATCH /v1/workspace/stacks/{widget_id}

closeStack()Скопіювати посилання на розділ

closeStack(options: StackOptions): Promise<WorkspaceOutcome>

DELETE /v1/workspace/stacks/{widget_id} (workspace:write): закрити один стек, як це робить його кнопка закриття.

Операція HTTP: DELETE /v1/workspace/stacks/{widget_id}

closeTab()Скопіювати посилання на розділ

closeTab(options: TabOptions): Promise<WorkspaceOutcome>

DELETE /v1/workspace/windows/{id}/tabs/{tab} (workspace:write): єдина вкладка вікна — це invalid_request.

Операція HTTP: DELETE /v1/workspace/windows/{id}/tabs/{tab}

activateTab()Скопіювати посилання на розділ

activateTab(options: TabOptions): Promise<WorkspaceOutcome>

POST /v1/workspace/windows/{id}/tabs/{tab}/activate (workspace:write): вибрати вкладку; фокус вікна не змінюється.

Операція HTTP: POST /v1/workspace/windows/{id}/tabs/{tab}/activate

closeWindow()Скопіювати посилання на розділ

closeWindow(options: WindowOptions): Promise<WorkspaceOutcome>

DELETE /v1/workspace/windows/{id} (workspace:write): головне вікно — це invalid_request.

Операція HTTP: DELETE /v1/workspace/windows/{id}

activateWindow()Скопіювати посилання на розділ

activateWindow(options: WindowOptions): Promise<WorkspaceOutcome>

POST /v1/workspace/windows/{id}/activate (workspace:write): відновити, якщо згорнуте, і вивести на передній план.

Операція HTTP: POST /v1/workspace/windows/{id}/activate

settings()Скопіювати посилання на розділ

settings(options: SettingsOptions = {}): Promise<Settings>

GET /v1/settings (settings:read): рядки так, як вони зберігаються, без підставлених типових значень. Без параметрів — глобальні рядки без підключення. Кожен рядок каже, чи він writable через updateSettings.

Операція HTTP: GET /v1/settings

orderbookSettings()Скопіювати посилання на розділ

orderbookSettings(options: InstrumentCommandOptions): Promise<OrderbookSettings>

GET /v1/settings/orderbook (settings:read): налаштування стека інструмента такими, як їх бачить його стек на підключенні — рядок пари, типове значення підключення, рядок пари без підключення, глобальне типове значення — з resolved_from у кожного ключа.

Операція HTTP: GET /v1/settings/orderbook

updateSettings()Скопіювати посилання на розділ

updateSettings(changes: SettingChange[]): Promise<SettingsApplied>

PATCH /v1/settings (settings:write): записати налаштування так, як це робить Settings App. Кожна зміна спершу перевіряється за словником термінала (invalid_request із назвою changes[i], нічого не записується; плече тут — unsupported, використовуйте setLeverage), потім зміни застосовуються по порядку: той самий рядок, подія вікну й службові кеші, що й у Settings App. Перша зміна, яку не вдалося застосувати, відхиляє виклик; попередні лишаються застосованими.

Операція HTTP: PATCH /v1/settings

stream()Скопіювати посилання на розділ

stream(options: StreamOptions = {}): Promise<Stream>

Відкрити /v1/stream. Лише в Node: токен передається в заголовку рукостискання.

nextRequestId()Скопіювати посилання на розділ

nextRequestId(): string

Новий request_id, унікальний у межах цього стріму.

expect()Скопіювати посилання на розділ

expect(requestId: string): Promise<ReplyFrame>

Зареєструвати запит і отримати проміс, який завершить його відповідь.

pendingCountСкопіювати посилання на розділ

pendingCount: number

Запити, які ще чекають на відповідь.

route()Скопіювати посилання на розділ

route(raw: unknown): StreamFrame | undefined

Класифікувати декодований кадр. Відповіді на наші запити завершують відповідний проміс і повертають undefined; event, gap і помилки підписок повертаються споживачу; все невідоме або пошкоджене відкидається.

abortAll()Скопіювати посилання на розділ

abortAll(error: Error): void

Відхилити всі запити, що чекають, наприклад коли сокет закривається.

connect()Скопіювати посилання на розділ

static connect(options: StreamConnectOptions): Promise<Stream>

Відкрити WebSocket і завершити рукостискання. Відхиляється з TerminalUnreachableError, коли термінал його не приймає: WebSocket Node повідомляє про відхилене рукостискання (термінал не запущено, API вимкнено, токен відхилено) однією загальною помилкою, тож ці три випадки не розрізняються.

urlСкопіювати посилання на розділ

url: string

URL стріму (ніколи не містить токена).

closedСкопіювати посилання на розділ

closed: boolean

true, щойно сокет закрито, хоч би хто його закрив.

closeCodeСкопіювати посилання на розділ

closeCode: number | undefined

Код закриття WebSocket, після закриття.

closeReasonСкопіювати посилання на розділ

closeReason: string | undefined

Причина закриття WebSocket, після закриття.

subscribe()Скопіювати посилання на розділ

subscribe(options: SubscribeOptions): Promise<Subscribed>

Підписатися на топік інструмента або на топік рахунку підключення. Виконується з кадром subscribed сервера (плюс запитаний topic і, для ринкових топіків, instrument) і відхиляється зі StreamRequestError на відповідь error сервера; події інших підписок тим часом надходять далі. Зважайте на ліміт термінала на нові підписки на біржах на секунду (/v1/meta); топіки рахунку не звертаються до біржі й не надсилають кадру зі знімком — спершу прочитайте поточний стан операціями /v1/account/*.

unsubscribe()Скопіювати посилання на розділ

unsubscribe(subscription: Subscribed | SubscribedFrame | string): Promise<void>

Зняти підписку негайно. Приймає значення, з яким виконався subscribe, або сам ідентифікатор sub. Виконується на unsubscribed сервера.

close()Скопіювати посилання на розділ

close(code: number = CLOSE_NORMAL, reason?: string): Promise<void>

Закрити стрім. Сервер завершує рукостискання закриття кодом клієнта; проміс виконується, коли це сталося, або після короткої паузи, якщо цього так і не сталося. Повторний виклик безпечний.

instancePath()Скопіювати посилання на розділ

function instancePath(options: DiscoveryEnvironment = {}): string

Шлях до instance.json термінала, за ОС:

• Linux: $XDG_DATA_HOME/spectre-terminal/instance.json, інакше ~/.local/share/spectre-terminal/instance.json;
• macOS: ~/Library/Application Support/spectre-terminal/instance.json;
• Windows: %LOCALAPPDATA%\spectre-terminal\instance.json, інакше %USERPROFILE%\AppData\Local\....

Це повторює власний каталог даних термінала (dirs::data_local_dir).

readPort()Скопіювати посилання на розділ

function readPort(options: ReadPortOptions = {}): Promise<number | undefined>

Порт Local API, опублікований в instance.json.

Повертає undefined, коли файлу немає або його не вдалося прочитати (термінал не запущено, або термінал не публікує це поле): тоді той, хто викликав, бере DEFAULT_PORT. Кидає LocalApiDisabledError, коли файл є, але local_api_port дорівнює null або відсутній — термінал запущено, а API вимкнено. Читає лише це одне поле.

tokenFromEnv()Скопіювати посилання на розділ

function tokenFromEnv(env: Record<string, string | undefined> = process.env): string | undefined

Токен зі SPECTRE_LOCAL_API_TOKEN або undefined, якщо змінну не задано чи вона порожня.

SpectreTerminalErrorСкопіювати посилання на розділ

class SpectreTerminalError extends Error

Базовий клас усіх помилок, які кидає цей пакет.

ApiErrorСкопіювати посилання на розділ

class ApiError extends SpectreTerminalError

Термінал відповів статусом не 2xx.

code — стабільний код із конверта помилки контракту (unauthorized, not_found, rate_limited, …); status — HTTP-статус. Тіло не 2xx, яке не є конвертом, дає код "unknown".

TerminalUnreachableErrorСкопіювати посилання на розділ

class TerminalUnreachableError extends SpectreTerminalError

HTTP-відповіді немає взагалі: з’єднання відхилено, запит перевищив тайм-аут, несподіване перенаправлення або рукостискання WebSocket не завершилося. Початкова помилка — у cause.

LocalApiDisabledErrorСкопіювати посилання на розділ

class LocalApiDisabledError extends SpectreTerminalError

instance.json існує, але не публікує порту Local API: термінал запущено з вимкненим API, або файл лишився від термінала, який не завершив роботу штатно. У будь-якому разі порту для підключення немає, поки API не ввімкнено в Settings App (Загальні → Local API).

TokenMissingErrorСкопіювати посилання на розділ

class TokenMissingError extends SpectreTerminalError

Ні параметр token, ні SPECTRE_LOCAL_API_TOKEN не дали токена.

IncompatibleTerminalErrorСкопіювати посилання на розділ

class IncompatibleTerminalError extends SpectreTerminalError

/v1/meta повідомив версію API, якою цей клієнт не говорить.

StreamRequestErrorСкопіювати посилання на розділ

class StreamRequestError extends SpectreTerminalError

Стрім відповів на запит subscribe або unsubscribe кадром error. code — код помилки з контракту (not_found, rate_limited, invalid_request, …). Інші підписки надходять далі.

StreamClosedErrorСкопіювати посилання на розділ

class StreamClosedError extends SpectreTerminalError

Сервер закрив стрім із причини, на яку споживач має відреагувати: 1001 — API вимкнено або токен перевипущено; 4008 — цей клієнт читав надто повільно; 4029 — ліміт з’єднань на токен. Також кидається для 1006, коли з’єднання обірвалося без кадру закриття, і з subscribe / unsubscribe на вже закритому стрімі.