> ## 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.
# Look up a position
> Resolve an authorized canonical position UUID without inferring account or venue from the UUID.
Preview contract. Production availability remains subject to activation and release qualification. Examples are synthetic; the documentation cannot submit requests.
## Authorization
`read`, with exact scope checked against the looked-up position.
## Behavior
Resolve an authorized canonical position UUID without inferring account or venue from the UUID. The response keeps the standard Position publication envelope. An inaccessible position can be reported as absent.
## Request example
```http theme={null}
GET /v1/positions/lookup?id=11111111-1111-4111-8111-111111111111
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/lookup
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/lookup:
get:
summary: Look up an authorized exact position
description: >-
Returns the canonical Liftx response documented below. Preserve
fixed-point decimals and inspect HTTP status and Content-Type before
decoding errors.
operationId: get_v1_positions_lookup
parameters:
- name: id
in: query
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
$ref: '#/components/schemas/Position'
required:
- success
- data
additionalProperties: true
examples:
synthetic:
summary: >-
Synthetic pending unprotected position; independent
illustration
description: >-
Synthetic documentation data, not an account snapshot,
executable market configuration or production-availability
assertion. IDs, quantities, prices, times and values are
illustrative.
value:
success: true
data:
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
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:
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.
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
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.