> ## 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.
# List positions
> Returns a canonical positions page for one exact link.
Preview contract. Production availability remains subject to activation and release qualification. Examples are synthetic; the documentation cannot submit requests.
## Authorization
`read`; link aggregates require an unrestricted instrument policy.
## Behavior
Returns a canonical positions page for one exact link. status defaults to active; offset defaults to 0, limit to 50 and maximum limit is 200. Respect has\_more, incomplete and endpoint errors. Do not infer zero exposure from an incomplete page.
## Request example
```http theme={null}
GET /v1/positions/list?exchange_link_id=17
Authorization: Bearer YOUR_API_KEY_FROM_PRIVATE_STORAGE
```
All IDs and dates are illustrative. URL-encode opaque query values and supply each allowed key once. Optional filters and their types appear in the generated schema below.
## 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).
Read the [related guide](/api/accounts-and-instruments) for lifecycle, units and recovery semantics.
## OpenAPI
````yaml api/openapi.json GET /v1/positions/list
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/positions/list:
get:
summary: Read exact-link canonical positions page
operationId: get_v1_positions_list
parameters:
- name: exchange_link_id
in: query
required: true
schema:
type: integer
minimum: 1
maximum: 9007199254740991
- name: status
in: query
required: false
schema:
type: string
enum:
- active
- inactive
default: active
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 200
default: 50
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PositionsPage'
examples:
page:
summary: Synthetic complete active page
description: >-
Synthetic documentation data, not an account snapshot,
executable market configuration or production-availability
assertion. IDs, quantities, prices, times and values are
illustrative.
value:
status: active
exchange_link_id: 17
offset: 0
limit: 50
has_more: false
positions:
- id: 11111111-1111-4111-8111-111111111111
user_id: 1
status: 1
revision: 7
instrument_id: COPY_EXACT_CATALOG_ID
instrument_type: 2
instrument_topology: 2
position_side: 1
base: BTC
quote: USDT
exchange_link_id: 17
margin_mode: 1
leverage: 2
order_grid_enabled: false
open_orders:
- row_id: 1
created_at_ms: 1893456000000
price_atomic: '70000'
price_scale: 0
quantity_atomic: '1'
quantity_scale: 4
executed: []
projected_order_status: 1
order_fsm_state: 2
exchange_submitted: true
slot_id: SYNTHETIC_CURRENT_OPEN_SLOT
order_id: 33333333-3333-4333-8333-333333333333
open_order_type: 1
sl_enabled: false
slx_enabled: false
tp_enabled: false
position_fsm_state: 2
created_at: 1893456000
updated_at: 1893456000
tick_step_atomic: '1'
tick_step_scale: 1
lot_step_base_atomic: '1'
lot_step_base_scale: 4
min_size_base_atomic: '1'
min_size_base_scale: 4
contract_value_atomic: '1'
contract_value_scale: 2
funding_fee_quote_atomic: '0'
funding_fee_quote_scale: 0
alloc_open_executed_atomic: '0'
alloc_open_executed_scale: 0
alloc_close_executed_atomic: '0'
alloc_close_executed_scale: 0
alloc_net_exposure_atomic: '0'
alloc_net_exposure_scale: 0
executed_cost_quote_atomic: '0'
executed_cost_quote_scale: 0
next_funding_fee_quote_atomic: '0'
next_funding_fee_quote_scale: 0
next_funding_time: 0
empty:
summary: Synthetic complete empty active page
description: >-
Synthetic documentation data, not an account snapshot,
executable market configuration or production-availability
assertion. IDs, quantities, prices, times and values are
illustrative.
value:
status: active
exchange_link_id: 17
offset: 0
limit: 50
has_more: false
positions: []
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:
PositionsPage:
type: object
properties:
status:
type: string
exchange_link_id:
type: integer
minimum: 1
maximum: 9007199254740991
request_id:
type: integer
format: int64
offset:
type: integer
format: int64
limit:
type: integer
format: int64
total:
type: integer
format: int64
has_more:
type: boolean
positions:
type: array
items:
$ref: '#/components/schemas/Position'
incomplete:
type: boolean
error:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
- message
additionalProperties: false
required:
- has_more
- positions
additionalProperties: false
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
Position:
type: object
properties:
id:
type: string
format: uuid
user_id:
type: integer
format: int64
status:
type: integer
format: int64
revision:
type: integer
format: int64
instrument_id:
type: string
instrument_type:
type: integer
format: int64
instrument_topology:
type: integer
format: int64
position_side:
type: integer
format: int64
base:
type: string
quote:
type: string
exchange:
anyOf:
- type: integer
format: int64
- type: 'null'
public_feed_id:
anyOf:
- type: integer
format: int64
- type: 'null'
exchange_link_id:
type: integer
format: int64
exchange_position_id:
type: string
margin_mode:
anyOf:
- type: integer
format: int64
- type: 'null'
leverage:
anyOf:
- type: integer
format: int64
- type: 'null'
order_grid_enabled:
type: boolean
num_open_orders:
anyOf:
- type: integer
format: int64
- type: 'null'
open_orders:
type: array
items:
$ref: '#/components/schemas/PositionOrder'
open_order_type:
type: integer
format: int64
close_orders:
type: array
items:
$ref: '#/components/schemas/PositionOrder'
sl_enabled:
type: boolean
stop_loss_orders:
type: array
items:
$ref: '#/components/schemas/PositionOrder'
slx_enabled:
anyOf:
- type: boolean
- type: 'null'
tp_enabled:
type: boolean
tp_price_rearrangement:
anyOf:
- type: boolean
- type: 'null'
tp_grid_enabled:
anyOf:
- type: boolean
- type: 'null'
num_tp_orders:
anyOf:
- type: integer
format: int64
- type: 'null'
take_profit_orders:
type: array
items:
$ref: '#/components/schemas/PositionOrder'
tp_order_type:
anyOf:
- type: integer
format: int64
- type: 'null'
terminal_request_kind:
type: integer
format: int64
terminal_request_phase:
type: integer
format: int64
terminal_request_queue_index:
anyOf:
- type: integer
format: int64
- type: 'null'
terminal_request_queue_size:
anyOf:
- type: integer
format: int64
- type: 'null'
position_fsm_state:
type: integer
format: int64
created_at:
type: integer
format: int64
updated_at:
type: integer
format: int64
tick_step_atomic:
type: string
tick_step_scale:
type: integer
format: int64
lot_step_base_atomic:
type: string
lot_step_base_scale:
type: integer
format: int64
min_size_base_atomic:
type: string
min_size_base_scale:
type: integer
format: int64
contract_value_atomic:
type: string
contract_value_scale:
type: integer
format: int64
funding_fee_quote_atomic:
type: string
funding_fee_quote_scale:
type: integer
format: int64
alloc_open_executed_atomic:
type: string
alloc_open_executed_scale:
type: integer
format: int64
alloc_close_executed_atomic:
type: string
alloc_close_executed_scale:
type: integer
format: int64
alloc_net_exposure_atomic:
type: string
alloc_net_exposure_scale:
type: integer
format: int64
executed_cost_quote_atomic:
type: string
executed_cost_quote_scale:
type: integer
format: int64
next_funding_fee_quote_atomic:
type: string
next_funding_fee_quote_scale:
type: integer
format: int64
next_funding_rate_atomic:
anyOf:
- type: string
- type: 'null'
next_funding_rate_scale:
anyOf:
- type: integer
format: int64
- type: 'null'
next_funding_time:
type: integer
format: int64
liquidation_price_atomic:
anyOf:
- type: string
- type: 'null'
liquidation_price_scale:
anyOf:
- type: integer
format: int64
- type: 'null'
required:
- id
- user_id
- status
- revision
- instrument_id
- instrument_type
- instrument_topology
- position_side
- base
- quote
- exchange_link_id
- order_grid_enabled
- open_orders
- open_order_type
- sl_enabled
- tp_enabled
- position_fsm_state
- created_at
- updated_at
- tick_step_atomic
- tick_step_scale
- lot_step_base_atomic
- lot_step_base_scale
- min_size_base_atomic
- min_size_base_scale
- contract_value_atomic
- contract_value_scale
- funding_fee_quote_atomic
- funding_fee_quote_scale
- alloc_open_executed_atomic
- alloc_open_executed_scale
- alloc_close_executed_atomic
- alloc_close_executed_scale
- alloc_net_exposure_atomic
- alloc_net_exposure_scale
- executed_cost_quote_atomic
- executed_cost_quote_scale
- next_funding_fee_quote_atomic
- next_funding_fee_quote_scale
- next_funding_time
additionalProperties: false
description: >-
Canonical owner publication. Fixed-point coefficients and scales;
revision is used for modify preconditions. Lifecycle fields and attached
orders are observations, not command receipt completion.
PositionOrder:
type: object
properties:
row_id:
type: integer
format: int64
created_at_ms:
type: integer
format: int64
price_atomic:
type: string
price_scale:
type: integer
format: int64
quantity_atomic:
type: string
quantity_scale:
type: integer
format: int64
executed_qty_sum_atomic:
anyOf:
- type: string
- type: 'null'
executed_qty_sum_scale:
anyOf:
- type: integer
format: int64
- type: 'null'
executed_fee_sum_atomic:
anyOf:
- type: string
- type: 'null'
executed_fee_sum_scale:
anyOf:
- type: integer
format: int64
- type: 'null'
executed_avg_fill_price_atomic:
anyOf:
- type: string
- type: 'null'
executed_avg_fill_price_scale:
anyOf:
- type: integer
format: int64
- type: 'null'
executed:
type: array
items:
$ref: '#/components/schemas/ExecutedOrder'
projected_order_status:
type: integer
format: int64
order_fsm_state:
type: integer
format: int64
exchange_submitted:
type: boolean
slot_id:
type: string
order_id:
anyOf:
- type: string
format: uuid
- type: 'null'
sl_step_percent:
anyOf:
- type: integer
format: int64
- type: 'null'
tp_step_percent:
anyOf:
- type: integer
format: int64
- type: 'null'
tp_quantity_percent:
anyOf:
- type: integer
format: int64
- type: 'null'
sl_type:
anyOf:
- type: integer
format: int64
- type: 'null'
sl_order_type:
anyOf:
- type: integer
format: int64
- type: 'null'
sl_price_rearrangement:
anyOf:
- type: boolean
- type: 'null'
slx_tp_trailing_enabled:
anyOf:
- type: boolean
- type: 'null'
slx_each_tp_trailing:
anyOf:
- type: boolean
- type: 'null'
slx_sl_trailing_breakeven_enabled:
anyOf:
- type: boolean
- type: 'null'
slx_sl_trigger_price_trailing_enabled:
anyOf:
- type: boolean
- type: 'null'
slx:
anyOf:
- type: boolean
- type: 'null'
activation_price_atomic:
anyOf:
- type: string
- type: 'null'
activation_price_scale:
anyOf:
- type: integer
format: int64
- type: 'null'
activation_price_triggered:
anyOf:
- type: boolean
- type: 'null'
activation_tp_trigger:
anyOf:
- type: integer
format: int64
- type: 'null'
slx_tp_breakeven:
anyOf:
- type: integer
format: int64
- type: 'null'
slx_sl_trigger_price_trailing_pl_percent_activation:
anyOf:
- type: integer
format: int64
- type: 'null'
slx_sl_trigger_price_trailing_indent_percent:
anyOf:
- type: integer
format: int64
- type: 'null'
slx_sl_trigger_price_trailing_step:
anyOf:
- type: integer
format: int64
- type: 'null'
slx_sl_trailing_breakeven_indent_percent:
anyOf:
- type: integer
format: int64
- type: 'null'
trailing_peak_price_atomic:
anyOf:
- type: string
- type: 'null'
trailing_peak_price_scale:
anyOf:
- type: integer
format: int64
- type: 'null'
required:
- price_atomic
- price_scale
- quantity_atomic
- quantity_scale
- executed
- projected_order_status
- order_fsm_state
- exchange_submitted
additionalProperties: false
ExecutedOrder:
type: object
properties:
price_atomic:
type: string
price_scale:
type: integer
format: int64
quantity_atomic:
type: string
quantity_scale:
type: integer
format: int64
fee_atomic:
type: string
fee_scale:
type: integer
format: int64
required:
- price_atomic
- price_scale
- quantity_atomic
- quantity_scale
- fee_atomic
- fee_scale
additionalProperties: false
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.