Strategy Synchronization

Sync any TradingView strategy with NinjaTrader 8

Overview

The sync_strategy functionality is an advanced safety feature available for the PLACE command. Its purpose is to prevent "state drift" between your external signaling system (e.g., a TradingView strategy) and the actual market position held in your NinjaTrader 8 account.

Automated strategies are stateful; they "know" whether they are currently long, short, or flat. However, situations can arise where the trading software becomes different from what the strategy expects. This can happen due to manual interventions, connection issues, or partial fills.

When state drift occurs, a signal to "add to a long position" might be sent when you are actually flat, or a signal to "reverse from long to short" might be sent when you are already short. These scenarios can lead to unintended trades and significant risk.

The sync_strategy feature acts as a gatekeeper, comparing your strategy's expected state with NinjaTrader's actual state before placing an order. If they don't align, it can prevent the order and take a pre-defined action.


How It Works

When you enable sync_strategy, the add-on performs a series of checks before submitting the order. This process can be broken down into three steps: Activation, State Comparison, and Action.

Activation & Required Parameters

To activate the feature, you must include sync_strategy=true; in your PLACE command payload. When this parameter is present, three additional parameters become essential:

Parameter
Required?
Description
Valid Values

sync_strategy

Yes

Enables or disables the synchronization check.

true

market_position

Yes

The target market position your strategy wants to be in after this order is executed.

long, short, flat

prev_market_position

Yes

The market position your strategy was in before this signal was generated.

long, short, flat

out_of_sync

Optional

Defines the behavior if a state mismatch is detected. Defaults to wait if not provided.

wait, flatten, ignore

If sync_strategy=true is provided but market_position or prev_market_position are missing or invalid, the command will fail with an error.

State Comparison

The core of the logic compares the Remote Expected State Transition (provided by you) with the Local NT8 State Transition (calculated by the add-on).

  1. Remote State: Defined by your prev_market_position and target_market_position.

  2. Local State: The add-on checks the current actual position in NinjaTrader and then calculates what the position would be after executing the requested order (action and quantity).

An order is considered "in-sync" if the local state transition perfectly matches one of the five valid remote state transitions:

  1. Opening a Position: Remote flat -> long/short matches Local flat -> long/short.

  2. Adding to Position: Remote long -> long matches Local long -> long (with increased quantity).

  3. Reversing a Position: Remote long -> short matches Local long -> short.

  4. Closing to Flat: Remote long/short -> flat matches Local long/short -> flat.

  5. Staying Flat: Remote flat -> flat matches Local flat -> flat.

The Critical "New Entry" Rule

There is an overriding safety constraint: You cannot open a new position in NinjaTrader if your remote strategy believes it was already in a position. If the add-on detects that the local NT8 account is flat but your prev_market_position was long or short, it will always consider this an out-of-sync condition, regardless of other rules. This prevents accidental entries when your strategy has lost its state.

Handling Mismatches (out_of_sync Behavior)

If the state comparison fails, the out_of_sync parameter determines the outcome.

  • out_of_sync=wait; (Default)

    • Action: The requested order is rejected.

    • Result: The system returns a success: true response with a warning message detailing the mismatch and stating that it is waiting. No trade is placed.

    • Use Case: This is the safest option. It prevents any action and alerts you to the discrepancy, allowing for manual intervention or waiting for a safe re-entry condition (e.g., both remote and local state are flat).

  • out_of_sync=flatten;

    • Action: The requested order is rejected. If the NinjaTrader account is currently not flat, a Flatten command is immediately issued for the instrument.

    • Result: The system returns a success: true response with a warning message. The goal is to reset the local position to flat to prepare for a clean entry on the next signal.

    • Use Case: An automated "reset button." Use this if your strategy is designed to re-establish its position from a flat state after a detected error.

  • out_of_sync=ignore;

    • Action: The synchronization check is bypassed. The requested order is placed regardless of the state mismatch.

    • Result: The system returns a response containing a warning message about the mismatch, but proceeds with the order placement.

    • Use Case: For advanced users who understand the risks and want to force an order through despite a detected state discrepancy. Use with caution.


Practical Example

Example Alert Payload: Trading In-Sync Between TradingView and NT8

A single alert payload can now run a fully automated strategy without the need for human intervention. The following payload will match the strategy orders. If the strategy ever gets out of sync, the NT8 account is flattened until we reach new entry criteria, e.g., NT8 account is flat and the prev_market_position of the TV strategy is also flat and we're now opening a new position.

key=your-secret-key;
command=PLACE;
account=Sim101;
instrument=NQ1!;
action={{strategy.order.action}};
qty={{stratety.order.contracts}};
order_type=MARKET;
tif=DAY;
sync_strategy=true;
market_position={{strategy.market_position}};
prev_market_position={{strategy.prev_market_position}};
out_of_sync=flatten;

Last updated