Skip to Content
Spectre Docs
ManualDevelopers
HTTP APISettings

Change settings

Build your request

Change the values and the command follows. The token is never typed here: the command reads it from the SPECTRE_LOCAL_API_TOKEN environment variable. Run it in your own terminal.

Command
curl -X PATCH 'http://127.0.0.1:48180/v1/settings' \
  -H "Authorization: Bearer $SPECTRE_LOCAL_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "changes": [
    {
      "category": "multiview",
      "key": "stack_width_px",
      "value": 300
    },
    {
      "instrument": "binance:futures:XRPUSDT",
      "connection_id": 25,
      "category": "trading",
      "key": "slippage",
      "value": {
        "value": "0.1",
        "type": "percent"
      }
    },
    {
      "scope": "order_book",
      "connection_id": 25,
      "category": "general",
      "key": "auto_scroll",
      "value": true
    },
    {
      "category": "appearance",
      "key": "theme",
      "value": {
        "stack": "dark"
      }
    },
    {
      "category": "hotkeys_orderbook",
      "key": "close_position",
      "value": {
        "code": "KeyX",
        "modifiers": []
      }
    }
  ]
}'
PATCH
/settings

Up to 100 changes in a request. All of them are checked first, then applied in order. If a change fails to apply, the list stops there and the answer names its number: changes[2]: …. Changes already applied are not rolled back.

A change is addressed like this:

  • scope is global by default. With instrument it is always order_book.
  • instrument addresses the row of a pair. connection_id is then chosen by the common rule.
  • For order_book without instrument, connection_id addresses the default of that connection. Without it the change goes to the global default.
  • connection_id is not accepted for global.

Some keys are handled in their own way. appearance/theme takes an object with any subset of stack, graphic and interface. Each value is a theme name, and graphic and interface accept only light and dark. hotkeys_* take { "code", "modifiers" } or null. A combination taken by another action is refused. appearance/font_family and localization/current_language are handled in their own way too.

The limit is 5 requests a second for all clients together.

Authorization

bearerToken settings:write
headerAuthorizationBearer <token>

The Local API token: spt_ and 64 hex characters. Copy it from Settings App → General → Local API. It is accepted only in the Authorization header. The names listed with an operation are the scopes it requires. The token of the terminal carries all of them.

Scope: settings:write

Request Body

application/json
  1. body
changes*array<>
Items1 <= items <= 100

Response Body

How many changes were applied.

application/json
  1. response
applied*integer

The number of changes applied.

Example Request
curl -X PATCH 'http://127.0.0.1:48180/v1/settings' \  -H "Authorization: Bearer $SPECTRE_LOCAL_API_TOKEN" \  -H 'Content-Type: application/json' \  -d '{  "changes": [    {      "category": "multiview",      "key": "stack_width_px",      "value": 300    },    {      "instrument": "binance:futures:XRPUSDT",      "connection_id": 25,      "category": "trading",      "key": "slippage",      "value": {        "value": "0.1",        "type": "percent"      }    },    {      "scope": "order_book",      "connection_id": 25,      "category": "general",      "key": "auto_scroll",      "value": true    },    {      "category": "appearance",      "key": "theme",      "value": {        "stack": "dark"      }    },    {      "category": "hotkeys_orderbook",      "key": "close_position",      "value": {        "code": "KeyX",        "modifiers": []      }    }  ]}'
Example Response
{  "applied": 5}

Settings rows GET

Rows as they are stored, with no defaults filled in, ordered by `scope`, `scope_id`, `category`, `key`. `global` rows belong to the whole terminal, and `order_book` rows hold the order-book settings of an instrument or their defaults. `writable` is `false` for leverage, `trading/leverage_mode`, and for service rows of the window.

Order-book settings of an instrument GET

The order-book settings of an instrument as a stack of this connection sees them, by category and key. A value comes from the first place that has it: the row of the pair on the connection, the default of the connection, the row of the pair without a connection, the global default. `resolved_from` names that place.