Advanced webhook command format

Advanced senders use the same durable command model as the API. The TradingView envelope adds its restricted token and setup-bound source information. Send exactly one command or alert; they are distinct authoring formats for the same trading owners.

Examples use synthetic identifiers, an invalid key and fixed illustrative timestamps. They describe shape and must not be replayed as current events. Generate live times and use the private values from Liftx. Execution remains gated by availability.

Guided OPEN

{
  "token": "REPLACE_WITH_RESTRICTED_TRADINGVIEW_KEY",
  "command": {
    "client_command_id": "example-strategy:cycle-47:open",
    "issued_at": 1893456000,
    "expires_at": 1893456060,
    "action": "open",
    "target": "position",
    "exchange_link_id": 17,
    "instrument_id": "COPY_EXACT_CATALOG_ID",
    "client_position_id": "example-strategy:cycle-47",
    "position_started_at": 1893456000,
    "source_instance_id": "11111111-1111-4111-8111-111111111111",
    "sequence": 101,
    "binding_revision": 1
  }
}

Guided OPEN omits request because Liftx saved it during setup. Advanced OPEN adds the complete canonical request below. Do not send a second order model based on TradingView’s broker-emulator fields.

Advanced OPEN with OPEN, SL, SLx and TP

This illustrative derivative request uses base-asset quantity, one limit OPEN, a rearranged SL, price-trigger SLx and a rearranged TP. The complete payload is intentionally nonoperational. Export a valid draft for the selected account and catalog instrument instead of assuming the shown prices, limits or combination fit a venue.

{
  "token": "REPLACE_WITH_RESTRICTED_TRADINGVIEW_KEY",
  "command": {
    "client_command_id": "example-strategy:cycle-47:open",
    "issued_at": 1893456000,
    "expires_at": 1893456060,
    "action": "open",
    "target": "position",
    "exchange_link_id": 17,
    "instrument_id": "COPY_EXACT_CATALOG_ID",
    "client_position_id": "example-strategy:cycle-47",
    "position_started_at": 1893456000,
    "source_instance_id": "11111111-1111-4111-8111-111111111111",
    "sequence": 101,
    "binding_revision": 1,
    "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]
    }
  }
}

The nested numeric action: 1 is part of PositionRequest; it is distinct from the outer command’s string action. position_side: 1 selects long; 2 selects short where the account and adapter support it. Spot, perpetual, dated or inverse execution comes from the canonical instrument, not a client spot/futures switch. The exact field rules, SLx alternatives, TP weight conventions and array pairing live in PositionRequest. OPEN/TP grids and rearrangement examples are in protections and grids. Preserve the builder’s exported TP weights; a single-row full-TP value and grid percentages must not be reinterpreted as interchangeable raw percentages.

Exact termination

Reuse the lifecycle reference and immutable start, increment the sequence, allocate a new command ID and omit request:

{
  "token": "REPLACE_WITH_RESTRICTED_TRADINGVIEW_KEY",
  "command": {
    "client_command_id": "example-strategy:cycle-47:terminate",
    "issued_at": 1893456120,
    "expires_at": 1893456180,
    "action": "terminate",
    "target": "position",
    "exchange_link_id": 17,
    "instrument_id": "COPY_EXACT_CATALOG_ID",
    "client_position_id": "example-strategy:cycle-47",
    "position_started_at": 1893456000,
    "source_instance_id": "11111111-1111-4111-8111-111111111111",
    "sequence": 103,
    "binding_revision": 1
  }
}

For a strategy group, change target to strategy and omit both client_position_id and position_started_at. For a market group, use market only with its explicit permission. Group commands also omit request. See frozen group membership.

Modification: full current state, one exact position

Advanced modify requires modify scope, the exact lifecycle reference, a fresh intent ID and sequence, and a complete canonical request. If supplied, outer expected_revision must match the current owner revision. Direct API modification requires that revision. The safe preparation sequence is:

An API controller reads get-for-modification and current position state.
It maps that position publication into the complete PositionRequest, retaining current rows, slot identities and immutable fields. The read response is not itself a ready-to-submit request.
It changes only the intended supported protection configuration. TradingView capped modification must preserve every OPEN row, including exact slot identities; same-size replacements still count as OPEN changes.
It emits an exact-position modify intent with the resulting complete request and, preferably, the observed revision.
It follows the receipt and resulting state. A conflict requires a fresh read and a deliberate new intent; an uncertain outcome requires review, not whole-request replay.

Pine cannot perform step 1 or consume execution results. Therefore the supplied examples do not schedule automatic modify calls. A historical OPEN JSON is unsafe after fills, manual edits or slot-generation changes. Use the direct API for OPEN-order changes. Never broadcast one full modification request to a heterogeneous group of positions.

Envelope rules

Field	Contract
`client_command_id`	Nonempty, at most 128 UTF-8 bytes; unique intent within integration namespace; preserve exactly on retry; reserved `liftx-group:` prefix is unavailable
`issued_at`	Positive integer Unix seconds; unseen identities must be within five minutes of issuance, with at most 30 seconds of future clock allowance, and still before their own deadline
`expires_at`	Integer Unix seconds, after issuance and no more than 300 seconds later; generated helpers use 60 seconds
`action`	`open`, `modify`, `terminate`; canonical TV aliases `cancel` and `close` normalize to termination
`target`	Omitted/`position` for exact commands; explicit `strategy`/`market` only for termination
`exchange_link_id`, `instrument_id`	Must match the authenticated immutable setup and nested request when present
`source_instance_id`, `binding_revision`	Exact configured values, not user-selected per event
`sequence`	Positive integer source ordering, assigned once per intent
`client_position_id`, `position_started_at`	Exact lifecycle reference for position targeting; reference length 1–128 UTF-8 bytes; immutable positive start no later than issuance; absent for groups
`expected_revision`	Optional TV modify fence; when present must match current state
`request`	Complete canonical position request where required; absent for termination

Use integer Unix seconds for times and decimal coefficient strings for money. Strict decoding rejects unknown keys, duplicate keys, incorrect casing, trailing JSON, oversized bodies and invalid unions. One body is limited to 256 KiB. The token authenticates admission and is not part of the persisted command payload. Identical retries return the original receipt; the same identity with changed content conflicts. Receipt evidence is explained in delivery and troubleshooting.

​Guided OPEN

​Advanced OPEN with OPEN, SL, SLx and TP

​Exact termination

​Modification: full current state, one exact position

​Envelope rules

Guided OPEN

Advanced OPEN with OPEN, SL, SLx and TP

Exact termination

Modification: full current state, one exact position

Envelope rules