Submit a trading command

POST

https://api.liftx.io

commands

Durably admit a trading command

curl --request POST \
  --url https://api.liftx.io/v1/commands \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_command_id": "<string>",
  "issued_at": 123,
  "expires_at": 123,
  "exchange_link_id": 4503599627370496,
  "instrument_id": "<string>"
}
'

import requests

url = "https://api.liftx.io/v1/commands"

payload = {
    "client_command_id": "<string>",
    "issued_at": 123,
    "expires_at": 123,
    "exchange_link_id": 4503599627370496,
    "instrument_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_command_id: '<string>',
    issued_at: 123,
    expires_at: 123,
    exchange_link_id: 4503599627370496,
    instrument_id: '<string>'
  })
};

fetch('https://api.liftx.io/v1/commands', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "22222222-2222-4222-8222-222222222222",
  "client_command_id": "demo-controller:cycle-001:open",
  "action": "open",
  "state": "accepted",
  "position_id": "11111111-1111-4111-8111-111111111111",
  "error_code": null,
  "created_at": 1893456000,
  "updated_at": 1893456000
}

Preview contract. Production availability remains subject to activation and release qualification. Examples are synthetic; the documentation cannot submit requests.

Authorization

positions:open, positions:modify or positions:terminate, selected by the action.

Behavior

A new intent returns 202 with a durable receipt; an identical retry returns 200 with the original receipt. OPEN allocates one position UUID; MODIFY requires a fresh expected_revision; TERMINATE omits request. Reusing an identity with different intent conflicts. Acceptance does not certify a fill or flatness.

JSON body example

The following shows the request shape, not live credentials or executable market defaults. Replace timestamps only when creating a new reviewed intent; never mutate them on a command retry.

{
  "client_command_id": "demo-controller:cycle-001:open",
  "issued_at": 1893456000,
  "expires_at": 1893456060,
  "action": "open",
  "exchange_link_id": 17,
  "instrument_id": "COPY_EXACT_CATALOG_ID",
  "request": {
    "action": 1,
    "exchange_link_id": 17,
    "instrument_id": "COPY_EXACT_CATALOG_ID",
    "quantity_asset": "BTC",
    "position_side": 1,
    "open_order_type": 1,
    "open_prices_atomic": [
      "70000"
    ],
    "open_prices_scale": [
      0
    ],
    "open_quantities_atomic": [
      "1"
    ],
    "open_quantities_scale": [
      4
    ],
    "order_grid_enabled": false,
    "margin_mode": 1,
    "leverage": 2,
    "sl_enabled": true,
    "sl_type": 1,
    "sl_step_percent": 2000000,
    "sl_price_atomic": "68600",
    "sl_price_scale": 0,
    "sl_price_rearrangement": true,
    "sl_order_type": 2,
    "slx_enabled": true,
    "slx_tp_trailing_enabled": false,
    "slx_each_tp_trailing": false,
    "slx_sl_trigger_price_trailing_enabled": true,
    "slx_sl_trigger_price_trailing_pl_percent_activation": 1000000,
    "slx_sl_trigger_price_trailing_indent_percent": 500000,
    "slx_sl_trigger_price_trailing_step": 250000,
    "slx_sl_trailing_breakeven_enabled": false,
    "tp_enabled": true,
    "tp_price_rearrangement": true,
    "tp_grid_enabled": false,
    "tp_order_type": 1,
    "tp_prices_atomic": [
      "72100"
    ],
    "tp_prices_scale": [
      0
    ],
    "tp_quantities_atomic": [
      "0"
    ],
    "tp_quantities_scale": [
      0
    ],
    "tp_quantity_percents": [
      1000000
    ],
    "tp_pnls": [
      3000000
    ]
  }
}

Response and errors

The generated response schema below is the wire contract. Preserve fixed-point strings, nullable fields and endpoint-specific envelopes. Inspect HTTP status and Content-Type before decoding failures; reused trading routes may return JSON or plain text. Authentication, entitlement and exact link/instrument restrictions apply in addition to endpoint validation. See errors and recovery. Do not automatically repeat a mutation after transport ambiguity. Trading commands reuse the exact immutable identity; credential issuance and template writes require their documented metadata/read reconciliation. Read the related guide for lifecycle, units and recovery semantics.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Immutable namespace+client ID; lifespan <=300s. Open omits position_id; modify/terminate require it. Modify requires expected_revision; terminate omits request. Open/modify require request. Identical retries return original receipt, changed payload is 409.

client_command_id

string

required

Unique immutable namespace event identity; liftx-group: prefix is reserved.

Required string length: 1 - 128

issued_at

integer<int64>

required

expires_at

integer<int64>

required

action

enum<string>

required

Available options:

open,

modify,

terminate

exchange_link_id

integer

required

Required range: 1 <= x <= 9007199254740991

instrument_id

string

required

position_id

string<uuid>

expected_revision

integer

Required range: x >= 1

request

object

Existing PositionRequest codec, also used by advanced TradingView. Paired row arrays must have equal lengths. Adapter batch limits and 256 KiB command body apply below the post-decode row ceiling. Creation and enabled protections require their operational fields. API modify requires outer expected_revision and fresh exact slot/order identities. TV modify must preserve OPEN rows. See position-request.md for all fields and units.

Show child attributes

target

string

Optional explicit exact-position target; group selectors are TradingView-only.

Allowed value: "position"

Response

Identical existing command

Durable command receipt, never a fill/completion assertion. Terminal request fields correlate a durable termination owner handoff. Terminal arm writes kind/sequence while retaining dispatching; owner return or startup canonical evidence advances handed_off. Group parent position_id is null. Precedence is operator_required, dispatching, accepted, then homogeneous resolved state or partial. Zero-target parent is execution_observed. Counts and child states do not prove exposure is flat.

string<uuid>

required

client_command_id

string

required

action

string

required

state

enum<string>

required

Available options:

accepted,

dispatching,

handed_off,

execution_observed,

rejected,

expired,

operator_required,

partial

position_id

string<uuid> | null

required

error_code

string | null

required

created_at

integer<int64>

required

updated_at

integer<int64>

required

terminal_request_kind

enum<integer>

Available options:

1,

2

terminal_request_seq

integer<int64>

Required range: x >= 1

group_id

string<uuid>

Parent group on a child termination receipt.

group

object

Counts sum to the immutable target_count. Zero targets records an observed empty selection, not market flatness.

Show child attributes

targets

object[]

Group detail only: at most 64 frozen ordinary termination receipts. Targets cannot contain nested groups or target arrays. Omitted on list responses and zero-target groups.

Maximum array length: 64

Show child attributes

Durably admit a trading command

curl --request POST \
  --url https://api.liftx.io/v1/commands \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_command_id": "<string>",
  "issued_at": 123,
  "expires_at": 123,
  "exchange_link_id": 4503599627370496,
  "instrument_id": "<string>"
}
'

import requests

url = "https://api.liftx.io/v1/commands"

payload = {
    "client_command_id": "<string>",
    "issued_at": 123,
    "expires_at": 123,
    "exchange_link_id": 4503599627370496,
    "instrument_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_command_id: '<string>',
    issued_at: 123,
    expires_at: 123,
    exchange_link_id: 4503599627370496,
    instrument_id: '<string>'
  })
};

fetch('https://api.liftx.io/v1/commands', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "22222222-2222-4222-8222-222222222222",
  "client_command_id": "demo-controller:cycle-001:open",
  "action": "open",
  "state": "accepted",
  "position_id": "11111111-1111-4111-8111-111111111111",
  "error_code": null,
  "created_at": 1893456000,
  "updated_at": 1893456000
}

Discovery and account data

Positions and history

Templates

Commands and streams

TradingView webhook

Session-only Settings

Submit a trading command

Authorization

Behavior

JSON body example

Response and errors

Authorizations

Body

Response

​Authorization

​Behavior

​JSON body example

​Response and errors

Authorizations

Body

Response

Authorization

Behavior

JSON body example

Response and errors