> ## 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.

# Receive a TradingView alert

> Use the hooks host, valid JSON and exactly one nonnull alert or command.

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

## Authorization

Restricted TradingView key in body token; ordinary API keys are invalid.

## Behavior

Use the hooks host, valid JSON and exactly one nonnull alert or command. No client-certificate setup is required. New durable acceptance returns 202; identical retry returns 200; temporary or inactive admission returns 503. The application admission budget is two seconds. Receipts are not execution feedback to Pine.

## 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}
{
  "token": "YOUR_RESTRICTED_TRADINGVIEW_KEY",
  "alert": {
    "fired_at": "{{timenow}}",
    "max_lag_seconds": 60,
    "action": "open",
    "target": "position",
    "exchange_link_id": 17,
    "instrument_id": "COPY_EXACT_CATALOG_ID",
    "source_instance_id": "55555555-5555-4555-8555-555555555555",
    "binding_revision": 1
  }
}
```

Send to `https://hooks.liftx.io/v1/tradingview/events`, not the API host. This example assumes a guided setup that already stores the OPEN request. TradingView substitutes `{{timenow}}`; a direct sender must supply the canonical UTC timestamp itself.

## 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](/integrations/tradingview/overview) for lifecycle, units and recovery semantics.


## OpenAPI

````yaml api/openapi.json POST /v1/tradingview/events
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/tradingview/events:
    post:
      summary: Receive a restricted-capability TradingView webhook
      description: >-
        Restricted TradingView body capability required. Use HTTPS on the hooks
        host with valid JSON; no client certificate configuration is required.
        The service remains unavailable until activation and delivery
        qualification. Durable admission has a two-second application deadline;
        temporary unavailability returns 503.
      operationId: post_v1_tradingview_events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TradingViewEvent'
      responses:
        '200':
          description: Identical accepted event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
              examples:
                open:
                  summary: Synthetic guided alert 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: alert:55555555-5555-4555-8555-555555555555:1893456000:open
                    action: open
                    state: accepted
                    position_id: 11111111-1111-4111-8111-111111111111
                    error_code: null
                    created_at: 1893456000
                    updated_at: 1893456000
                empty_exit:
                  summary: >-
                    Synthetic strategy EXIT captures no target; not flatness
                    proof
                  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: 99999999-9999-4999-8999-999999999999
                    client_command_id: signal-a:exit-001
                    action: terminate
                    state: execution_observed
                    position_id: null
                    error_code: null
                    created_at: 1893456000
                    updated_at: 1893456060
                    group:
                      target: strategy
                      target_count: 0
                      counts:
                        accepted: 0
                        dispatching: 0
                        execution_observed: 0
                        handed_off: 0
                        rejected: 0
                        expired: 0
                        operator_required: 0
        '202':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
              examples:
                open:
                  summary: Synthetic guided alert 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: alert:55555555-5555-4555-8555-555555555555:1893456000:open
                    action: open
                    state: accepted
                    position_id: 11111111-1111-4111-8111-111111111111
                    error_code: null
                    created_at: 1893456000
                    updated_at: 1893456000
                empty_exit:
                  summary: >-
                    Synthetic strategy EXIT captures no target; not flatness
                    proof
                  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: 99999999-9999-4999-8999-999999999999
                    client_command_id: signal-a:exit-001
                    action: terminate
                    state: execution_observed
                    position_id: null
                    error_code: null
                    created_at: 1893456000
                    updated_at: 1893456060
                    group:
                      target: strategy
                      target_count: 0
                      counts:
                        accepted: 0
                        dispatching: 0
                        execution_observed: 0
                        handed_off: 0
                        rejected: 0
                        expired: 0
                        operator_required: 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: []
      servers:
        - url: https://hooks.liftx.io
components:
  schemas:
    TradingViewEvent:
      type: object
      properties:
        token:
          type: string
          writeOnly: true
        command:
          $ref: '#/components/schemas/TradingViewCommand'
        alert:
          $ref: '#/components/schemas/TradingViewAlert'
      required:
        - token
      additionalProperties: false
      oneOf:
        - required:
            - command
          not:
            required:
              - alert
        - required:
            - alert
          not:
            required:
              - command
      description: >-
        Exactly one non-null command or alert object. The restricted body token
        authenticates either transport; both converge on the same canonical
        command admission.
    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
    TradingViewCommand:
      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
            - cancel
            - close
        exchange_link_id:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        instrument_id:
          type: string
        expected_revision:
          type: integer
          minimum: 1
        request:
          $ref: '#/components/schemas/PositionRequest'
        client_position_id:
          type: string
          minLength: 1
          maxLength: 128
        position_started_at:
          type: integer
          minimum: 1
        source_instance_id:
          type: string
          format: uuid
        sequence:
          type: integer
          minimum: 1
        binding_revision:
          type: integer
          minimum: 1
        target:
          type: string
          enum:
            - position
            - strategy
            - market
          description: >-
            Omitted/position requires exact lifecycle reference. Strategy or
            market selects termination groups only; market requires the
            immutable grant.
      required:
        - client_command_id
        - issued_at
        - expires_at
        - action
        - exchange_link_id
        - instrument_id
        - source_instance_id
        - sequence
        - binding_revision
      additionalProperties: false
      description: >-
        Immutable source/revision and exact market. Each new OPEN uses a new
        lifecycle reference and sequence above the source watermark.
        Known-position termination remains per-reference ordered; groups freeze
        at most 64 targets and never reselect on retry. Advanced OPEN and MODIFY
        use the existing PositionRequest; capped MODIFY preserves OPEN rows.
        Pine has no execution-feedback channel.
      allOf:
        - if:
            properties:
              target:
                enum:
                  - strategy
                  - market
            required:
              - target
          then:
            properties:
              action:
                enum:
                  - terminate
                  - cancel
                  - close
            not:
              anyOf:
                - required:
                    - client_position_id
                - required:
                    - position_started_at
                - required:
                    - expected_revision
                - required:
                    - request
          else:
            required:
              - client_position_id
              - position_started_at
        - if:
            properties:
              action:
                const: modify
            required:
              - action
          then:
            required:
              - request
        - if:
            properties:
              action:
                enum:
                  - terminate
                  - cancel
                  - close
            required:
              - action
          then:
            not:
              required:
                - request
    TradingViewAlert:
      type: object
      properties:
        fired_at:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
          description: >-
            TradingView {{timenow}} after substitution. UTC whole-second trigger
            time; no offset or fractions.
        action:
          type: string
          enum:
            - open
            - terminate
        target:
          type: string
          enum:
            - position
            - strategy
            - market
        exchange_link_id:
          type: integer
          format: int64
          minimum: 1
        instrument_id:
          type: string
          minLength: 1
          maxLength: 128
        source_instance_id:
          type: string
          format: uuid
        binding_revision:
          type: integer
          format: int64
          minimum: 1
        max_lag_seconds:
          type: integer
          minimum: 1
          maximum: 300
        request:
          $ref: '#/components/schemas/PositionRequest'
      required:
        - fired_at
        - action
        - target
        - exchange_link_id
        - instrument_id
        - source_instance_id
        - binding_revision
        - max_lag_seconds
      additionalProperties: false
      allOf:
        - if:
            properties:
              action:
                const: open
          then:
            properties:
              target:
                const: position
          else:
            properties:
              target:
                enum:
                  - strategy
                  - market
            not:
              required:
                - request
      description: >-
        Ordinary OPEN/EXIT alert pair. Guided OPEN omits request; advanced OPEN
        requires full canonical request. OPEN identity/reference are derived
        from source and fired second. Sequence is Unix milliseconds with
        termination ranked +1. One distinct OPEN and EXIT per second per setup;
        identical payload duplicates return original receipt, changed payload
        conflicts. EXIT has no exact lifecycle reference. Source authority,
        permissions, quantity cap, receipt and trading execution remain
        canonical. Do not mix this pair with a Pine producer.
    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
    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
    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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.