States & Transitions

States and transitions are the core building blocks of your strategy's logic. This page covers everything you need to know about creating and connecting them.

tip

The Quick Start walks through creating a minimal two-state strategy end-to-end. This page goes deeper into the mechanics and options available.

Adding States

Every strategy needs at least two states (e.g., Idle, Scanning, InPosition).

1. Click the Gear icon (bottom center) to open the Strategy Toolbar.
2. Select Add New State, enter a unique State Name, and click Save State.
3. A new State node appears on the canvas.

State Controls

Each state node includes:

• Delete — remove the state and all its transitions.
• Edit — change the state's name.
• Minimize / Expand — collapse the node to save canvas space, or expand to see transition details.
• Add Transition — create a new outgoing transition from this state.
• Set as Initial State — mark this state as the starting point.

Drag the node header to reposition states anywhere on the canvas. Layout is purely for visual organization and does not affect behavior.

Setting the Initial State

One state must be designated as the Initial State — the state the strategy begins in when first enabled.

• On your chosen state node, click Set as Initial State.
• Only one state can be initial at a time; selecting a new one automatically deselects the previous.

Adding Transitions

Transitions define how the strategy moves between states. Each transition has a trigger that determines when it is evaluated, optional conditions that determine whether it fires, and optional actions that execute when it fires.

1. On a state node, click Add Transition.
2. In the Transition editor:
   • Target State — which state to move to.
   • Trigger Type — how the transition is triggered (see below).
   • Additional fields depending on the trigger type.
3. Click Save Transition.

Trigger Types

Every transition needs a trigger. There are three types:

Trigger	When It Evaluates	Requires Data Stream	Use Case
Event	Each time a new event arrives from a subscribed data stream (e.g., a New Candle or a Custom Event).	Yes	Most transitions — react to market data or external signals.
Always	Immediately on every state entry, without waiting for an external event.	No	Instant routing — e.g., check a condition and move to the correct state right away.
After	After a specified time delay (in milliseconds) from entering the state.	No	Time-based logic — e.g., exit a position if no signal arrives within 60 seconds.

Event Triggers and Data Streams

Event triggers are the most common trigger type. When you select Event as the trigger, you choose which data stream the transition listens to. This means your strategy must be subscribed to at least one data stream before you can create event-triggered transitions.

The event type depends on the stream's series kind:

• Candle series streams deliver New Candle events containing OHLCV data.
• Event series streams deliver Custom Events from a webhook, and you specify the event type name to listen for.

If your strategy isn't subscribed to any data stream yet, navigate to the Strategy Toolbar → Data Subscriptions first, then return to add your transitions. See Data Streams for the full walkthrough.

Always and After Triggers

Always and After transitions do not require a data stream — they are evaluated based on state entry, not incoming events. However, conditions on these transitions can still reference the most recent event data and indicator values from the last event your strategy processed.

Building a Valid Loop

Every state must have at least one outgoing transition. For a minimal strategy, create transitions that form a loop — for example, Watching → Active on New Candle and Active → Watching on New Candle.

Refining Transitions Later

The initial transitions you create can be bare-bones. You can add conditions and actions to any transition at any time:

• Conditions — rules that must be true for the transition to fire (e.g., RSI < 30, tradeCount < 3).
• Actions — effects executed when the transition occurs (e.g., execute a trade, update a variable, trigger an alert).
• Transitions Manager — a centralized view for managing all transitions across your strategy.

Checklist Progress

As you build, the Creation Checklist updates automatically:

• At Least Two States Configured — satisfied when two or more states exist.
• Initial State Configured — satisfied when one state is marked as initial.
• All States Have Transitions — satisfied when every state has at least one outgoing transition.

---