> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liftx.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit a trading command
> A new intent returns 202 with a durable receipt; an identical retry returns 200 with the original receipt.
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.
```json theme={null}
{
"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](/api/errors-and-limits).
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](/api/commands-and-receipts) for lifecycle, units and recovery semantics.
## OpenAPI
````yaml api/openapi.json POST /v1/commands
openapi: 3.1.0
info:
title: Liftx integrations
version: 1.0.0
description: >-
Preview contract for the Liftx API, TradingView webhook and session-owned
integration settings. Production availability is pending activation and
release qualification. External access requires Pro or trial entitlement and
is unmetered within bounded resource limits. Receipt acceptance does not
confirm execution completion. MCP is not active.
servers:
- url: https://api.liftx.io
security: []
paths:
/v1/commands:
post:
summary: Durably admit a trading command
operationId: post_v1_commands
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Command'
responses:
'200':
description: Identical existing command
content:
application/json:
schema:
$ref: '#/components/schemas/Receipt'
examples:
open:
summary: Synthetic OPEN receipt; identical retry
description: >-
Synthetic documentation data, not an account snapshot,
executable market configuration or production-availability
assertion. IDs, quantities, prices, times and values are
illustrative.
value:
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
modify:
summary: Synthetic MODIFY receipt; not execution completion
description: >-
Synthetic documentation data, not an account snapshot,
executable market configuration or production-availability
assertion. IDs, quantities, prices, times and values are
illustrative.
value:
id: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
client_command_id: demo-controller:cycle-001:modify
action: modify
state: accepted
position_id: 11111111-1111-4111-8111-111111111111
error_code: null
created_at: 1893456000
updated_at: 1893456000
terminate:
summary: Synthetic TERMINATE receipt; not flatness confirmation
description: >-
Synthetic documentation data, not an account snapshot,
executable market configuration or production-availability
assertion. IDs, quantities, prices, times and values are
illustrative.
value:
id: bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb
client_command_id: demo-controller:cycle-001:terminate
action: terminate
state: accepted
position_id: 11111111-1111-4111-8111-111111111111
error_code: null
created_at: 1893456000
updated_at: 1893456000
'202':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Receipt'
examples:
open:
summary: Synthetic OPEN receipt; new acceptance
description: >-
Synthetic documentation data, not an account snapshot,
executable market configuration or production-availability
assertion. IDs, quantities, prices, times and values are
illustrative.
value:
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
modify:
summary: Synthetic MODIFY receipt; not execution completion
description: >-
Synthetic documentation data, not an account snapshot,
executable market configuration or production-availability
assertion. IDs, quantities, prices, times and values are
illustrative.
value:
id: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
client_command_id: demo-controller:cycle-001:modify
action: modify
state: accepted
position_id: 11111111-1111-4111-8111-111111111111
error_code: null
created_at: 1893456000
updated_at: 1893456000
terminate:
summary: Synthetic TERMINATE receipt; not flatness confirmation
description: >-
Synthetic documentation data, not an account snapshot,
executable market configuration or production-availability
assertion. IDs, quantities, prices, times and values are
illustrative.
value:
id: bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb
client_command_id: demo-controller:cycle-001:terminate
action: terminate
state: accepted
position_id: 11111111-1111-4111-8111-111111111111
error_code: null
created_at: 1893456000
updated_at: 1893456000
default:
description: >-
Integration errors use Error; existing trading handlers retain their
own JSON or text/plain error codec. Inspect status and content type.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
text/plain:
schema:
type: string
security:
- ApiKey: []
components:
schemas:
Command:
type: object
properties:
client_command_id:
type: string
minLength: 1
maxLength: 128
description: >-
Unique immutable namespace event identity; liftx-group: prefix is
reserved.
issued_at:
type: integer
format: int64
expires_at:
type: integer
format: int64
action:
type: string
enum:
- open
- modify
- terminate
exchange_link_id:
type: integer
minimum: 1
maximum: 9007199254740991
instrument_id:
type: string
position_id:
type: string
format: uuid
expected_revision:
type: integer
minimum: 1
request:
$ref: '#/components/schemas/PositionRequest'
target:
type: string
const: position
description: >-
Optional explicit exact-position target; group selectors are
TradingView-only.
required:
- client_command_id
- issued_at
- expires_at
- action
- exchange_link_id
- instrument_id
additionalProperties: false
description: >-
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.
allOf:
- if:
properties:
action:
const: open
then:
required:
- request
not:
required:
- position_id
- if:
properties:
action:
const: modify
then:
required:
- request
- position_id
- expected_revision
- if:
properties:
action:
const: terminate
then:
required:
- position_id
not:
required:
- request
Receipt:
type: object
properties:
id:
type: string
format: uuid
client_command_id:
type: string
action:
type: string
state:
type: string
enum:
- accepted
- dispatching
- handed_off
- execution_observed
- rejected
- expired
- operator_required
- partial
position_id:
anyOf:
- type: string
format: uuid
- type: 'null'
error_code:
anyOf:
- type: string
- type: 'null'
created_at:
type: integer
format: int64
updated_at:
type: integer
format: int64
terminal_request_kind:
type: integer
enum:
- 1
- 2
terminal_request_seq:
type: integer
format: int64
minimum: 1
group_id:
type: string
format: uuid
description: Parent group on a child termination receipt.
group:
$ref: '#/components/schemas/GroupProgress'
targets:
type: array
maxItems: 64
items:
$ref: '#/components/schemas/GroupTargetReceipt'
description: >-
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.
required:
- id
- client_command_id
- action
- state
- position_id
- error_code
- created_at
- updated_at
additionalProperties: false
description: >-
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.
dependentRequired:
terminal_request_kind:
- terminal_request_seq
terminal_request_seq:
- terminal_request_kind
targets:
- group
allOf:
- if:
required:
- group
then:
properties:
position_id:
type: 'null'
action:
const: terminate
not:
anyOf:
- required:
- group_id
- required:
- terminal_request_kind
- required:
- terminal_request_seq
Error:
type: object
properties:
success:
const: false
error:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
- message
additionalProperties: false
required:
- success
- error
additionalProperties: false
PositionRequest:
type: object
properties:
action:
type: integer
const: 1
instrument_id:
type: string
description: >-
Opaque canonical catalog ID on the exact exchange link. Determines
spot/derivative/inverse topology; never derive from chart ticker.
trading_currency:
type: string
description: >-
Eligible spot settlement currency; preserve canonical currency on
modification.
quantity_asset:
type: string
description: >-
Catalog base or quote asset for input quantities. Normalization and
venue contract conversion remain adapter-owned.
position_side:
type: integer
enum:
- 1
- 2
description: >-
1 long; 2 short. Immutable after creation; exact catalog/account
eligibility applies.
open_order_type:
type: integer
format: int64
enum:
- 1
- 2
- 3
description: >-
1 limit, 2 market, 3 virtual limit. Supported combinations depend on
the typed adapter and order role.
exchange_link_id:
type: integer
format: int64
minimum: 1
open_slot_ids:
type: array
items:
type: string
maxItems: 65535
order_amendments:
type: array
items:
$ref: '#/components/schemas/OrderAmendment'
margin_mode:
anyOf:
- type: integer
format: int64
enum:
- 1
- 2
- type: 'null'
description: >-
Derivatives: 1 cross, 2 isolated. Required on creation and immutable
thereafter.
leverage:
anyOf:
- type: integer
format: int64
minimum: 1
maximum: 32767
- type: 'null'
description: >-
Required positive derivative creation leverage within the exact
catalog/adapter limit; omit unchanged leverage on modify to avoid
unnecessary preflight.
order_grid_enabled:
type: boolean
num_open_orders:
anyOf:
- type: integer
format: int64
minimum: 0
maximum: 65535
- type: 'null'
sl_enabled:
type: boolean
sl_type:
anyOf:
- type: integer
format: int64
enum:
- 1
- 2
- type: 'null'
description: 1 from position, 2 from average.
sl_step_percent:
anyOf:
- type: integer
format: int64
- type: 'null'
description: >-
Percentage points multiplied by 1,000,000; trading owner validates
applicability.
sl_price_rearrangement:
type: boolean
sl_order_type:
type: integer
format: int64
enum:
- 1
- 2
- 3
description: >-
1 limit, 2 market, 3 virtual limit. Supported combinations depend on
the typed adapter and order role.
slx_enabled:
type: boolean
slx_tp_trailing_enabled:
type: boolean
slx_tp_breakeven:
anyOf:
- type: integer
format: int64
- type: 'null'
slx_each_tp_trailing:
type: boolean
slx_sl_trailing_breakeven_enabled:
type: boolean
slx_sl_trailing_breakeven_indent_percent:
anyOf:
- type: integer
format: int64
- type: 'null'
description: >-
Percentage points multiplied by 1,000,000; trading owner validates
applicability.
slx_sl_trigger_price_trailing_enabled:
type: boolean
slx_sl_trigger_price_trailing_pl_percent_activation:
anyOf:
- type: integer
format: int64
- type: 'null'
description: >-
Percentage points multiplied by 1,000,000; trading owner validates
applicability.
slx_sl_trigger_price_trailing_indent_percent:
anyOf:
- type: integer
format: int64
- type: 'null'
description: >-
Percentage points multiplied by 1,000,000; trading owner validates
applicability.
slx_sl_trigger_price_trailing_step:
anyOf:
- type: integer
format: int64
- type: 'null'
description: >-
Percentage points multiplied by 1,000,000; trading owner validates
applicability.
tp_enabled:
type: boolean
tp_price_rearrangement:
type: boolean
tp_grid_enabled:
type: boolean
num_tp_orders:
anyOf:
- type: integer
format: int64
minimum: 0
maximum: 65535
- type: 'null'
tp_quantity_percents:
type: array
items:
type: integer
format: int32
minimum: 1
maximum: 2147483647
maxItems: 65535
description: >-
Required for enabled TP. Preserve builder weights: single full TP
uses 1000000; grid weights use percentage points times 1000000.
Canonical protection normalization handles both.
tp_pnls:
type: array
items:
type: integer
format: int64
maxItems: 65535
description: >-
Required for enabled TP. Rearranged TP: positive price-distance
percent from fee-aware breakeven times 1000000, maximum 100000000;
not leveraged ROI. Static unused entries may be zero.
tp_slot_ids:
type: array
items:
type: string
maxItems: 65535
tp_order_type:
type: integer
format: int64
enum:
- 1
- 2
- 3
description: >-
1 limit, 2 market, 3 virtual limit. Supported combinations depend on
the typed adapter and order role.
open_prices_atomic:
type: array
items:
type: string
pattern: ^-?[0-9]{1,128}$
maxItems: 65535
open_prices_scale:
type: array
items:
type: integer
minimum: 0
maximum: 30
maxItems: 65535
open_quantities_atomic:
type: array
items:
type: string
pattern: ^-?[0-9]{1,128}$
maxItems: 65535
open_quantities_scale:
type: array
items:
type: integer
minimum: 0
maximum: 30
maxItems: 65535
tp_prices_atomic:
type: array
items:
type: string
pattern: ^-?[0-9]{1,128}$
maxItems: 65535
tp_prices_scale:
type: array
items:
type: integer
minimum: 0
maximum: 30
maxItems: 65535
tp_quantities_atomic:
type: array
items:
type: string
pattern: ^-?[0-9]{1,128}$
maxItems: 65535
description: >-
Builder may use zero placeholders; canonical protection owner sizes
from actual exposure and TP weights.
tp_quantities_scale:
type: array
items:
type: integer
minimum: 0
maximum: 30
maxItems: 65535
sl_price_atomic:
type: string
pattern: ^-?[0-9]{1,128}$
sl_price_scale:
type: integer
minimum: 0
maximum: 30
slx_activation_price_atomic:
type: string
pattern: ^-?[0-9]{1,128}$
slx_activation_price_scale:
type: integer
minimum: 0
maximum: 30
slx_price_atomic:
type: string
pattern: ^-?[0-9]{1,128}$
slx_price_scale:
type: integer
minimum: 0
maximum: 30
required:
- action
- instrument_id
- exchange_link_id
- quantity_asset
- position_side
- open_order_type
- order_grid_enabled
- open_prices_atomic
- open_prices_scale
- open_quantities_atomic
- open_quantities_scale
- sl_enabled
- slx_enabled
- tp_enabled
additionalProperties: false
description: >-
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.
allOf:
- if:
properties:
sl_enabled:
const: true
required:
- sl_enabled
then:
required:
- sl_price_rearrangement
- sl_order_type
- if:
properties:
tp_enabled:
const: true
required:
- tp_enabled
then:
required:
- tp_price_rearrangement
- tp_grid_enabled
- tp_order_type
- tp_prices_atomic
- tp_prices_scale
- tp_quantities_atomic
- tp_quantities_scale
- tp_quantity_percents
- tp_pnls
GroupProgress:
type: object
properties:
target:
type: string
enum:
- strategy
- market
target_count:
type: integer
minimum: 0
maximum: 64
counts:
type: object
properties:
accepted:
type: integer
minimum: 0
maximum: 64
dispatching:
type: integer
minimum: 0
maximum: 64
execution_observed:
type: integer
minimum: 0
maximum: 64
handed_off:
type: integer
minimum: 0
maximum: 64
rejected:
type: integer
minimum: 0
maximum: 64
expired:
type: integer
minimum: 0
maximum: 64
operator_required:
type: integer
minimum: 0
maximum: 64
required:
- accepted
- dispatching
- execution_observed
- handed_off
- rejected
- expired
- operator_required
additionalProperties: false
required:
- target
- target_count
- counts
additionalProperties: false
description: >-
Counts sum to the immutable target_count. Zero targets records an
observed empty selection, not market flatness.
GroupTargetReceipt:
type: object
description: >-
One captured termination target in a group receipt. Targets are ordinary
command receipts, never nested groups. Each identifies its frozen
position and parent group. Its state and durable terminal-request fields
do not prove exposure is flat.
properties:
id:
type: string
format: uuid
client_command_id:
type: string
action:
type: string
const: terminate
description: Every captured group target is an ordinary termination command.
state:
type: string
enum:
- accepted
- dispatching
- handed_off
- execution_observed
- rejected
- expired
- operator_required
position_id:
type: string
format: uuid
description: Exact position UUID frozen into this group target at admission.
error_code:
anyOf:
- type: string
- type: 'null'
created_at:
type: integer
format: int64
updated_at:
type: integer
format: int64
terminal_request_kind:
type: integer
enum:
- 1
- 2
terminal_request_seq:
type: integer
format: int64
minimum: 1
group_id:
type: string
format: uuid
description: Exact parent group UUID; always present on a captured target.
required:
- id
- client_command_id
- action
- state
- position_id
- error_code
- created_at
- updated_at
- group_id
additionalProperties: false
dependentRequired:
terminal_request_kind:
- terminal_request_seq
terminal_request_seq:
- terminal_request_kind
OrderAmendment:
type: object
properties:
slot_id:
type: string
order_id:
type: string
format: uuid
description: Exact current Liftx physical order UUID, not an exchange order ID.
price_atomic:
type: string
pattern: ^-?[0-9]{1,128}$
price_scale:
type: integer
format: int64
minimum: 0
maximum: 30
quantity_atomic:
type: string
pattern: ^-?[0-9]{1,128}$
quantity_scale:
type: integer
format: int64
minimum: 0
maximum: 30
required: []
additionalProperties: false
description: >-
Existing amendment decoder accepts optional exact slot/order identity
and optional paired price/quantity fields; trading owner validates
applicability. Preserve identities from the current modification
snapshot.
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: lx_api_.<256-bit secret>
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.