Entry

[[entry]] creates an order to open a position or add to an existing position. If an unfilled order already exists with the same id, a new call does not create a second order. It updates the order associated with that id.

For the global sizing logic, default values, and multipliers, refer to Using Margin and Leverage in Whale‑E. This page only describes the [[entry]] block semantics.

Order type#

The order type depends on whether the limit and stop parameters are provided. Without limit or stop, the command creates a market order, executed on the next available price update. With limit only, it places a limit order, executed when the market reaches limit or a better price (lower for buys, higher for sells). With stop only, it places a stop order, executed after stop is reached, with execution potentially at a worse price if the market continues (higher for buys, lower for sells). With both limit and stop, it creates a stop-limit order: when the market reaches stop in the trigger direction, a limit order at the limit price is then placed.

Effect of the pyramiding parameter#

Orders created by this block, unlike those produced by the [[order]] block, depend on the pyramiding parameter defined in [backtest]. The pyramiding parameter sets the maximum number of simultaneous entries allowed for a position. With pyramiding = 3, the strategy can keep up to three entries open, and the command cannot open additional entries until at least one existing entry is closed.

Automatic position reversal#

By default, if an order is executed in the opposite direction of the current position, the strategy reverses the position.

Chaining after an [[entry]] block#

An [[entry]] block submits an order request. That request is then processed by the engine through its order pipeline, and the position state is updated on the next candle cycle. Depending on when the strategy evaluates the next block, some position information may not be up to date yet.

You control when the [[entry]] block chains to the next block with the wait_candles key:

• With wait_candles = 1, after an entry signal on a candle, the engine waits for the next candle before evaluating the next block. Chaining is therefore delayed to the next cycle, which matches the moment when the engine has refreshed the position state, including the position itself, the average entry price, and other derived fields.
• With wait_candles = 0, the next block is evaluated on the same candle as the entry signal. Chaining becomes immediate, with no one‑cycle delay.

In all cases, wait_candles does not change how the order is executed. It only shifts when the strategy moves on to the next block.

Block declaration#

A strategy can contain multiple [[entry]] blocks. Each block specifies the trade direction and optionally the quantity to commit. Each block must also define an order_id. This value is the engine-level identifier for the entry. It is notably used by [[close]], [[cancel]], and by the from_entry filter in [[exit]].

Examples#

Long with an equity percentage#

This example opens a long position by committing 50% of equity, then moves to the set_take_profit block.

[[entry]]
id            = "open_long"
order_id      = "open_long"
direction     = "long"
qty_percent   = 50
next_block_id = "set_take_profit"

Short with a fixed quantity#

This example opens a short position with a fixed quantity of 2 units, then moves to the monitor_exit block.

[[entry]]
id            = "open_short"
order_id      = "open_short"
direction     = "short"
qty           = 2
next_block_id = "monitor_exit"

Long with a stop-limit order#

This example places a long stop-limit order: when the market reaches stop, a limit order at the limit price is placed, then the strategy moves to the confirm_entry block. stop and limit are absolute prices (symbol price units). Example: on BTCUSDT, if high = 100000, then high + 10 is 100010 (+10 USDT).

[[entry]]
id            = "open_long_stop_limit"
order_id      = "open_long_stop_limit"
direction     = "long"
qty_percent   = 50
stop          = "high + 10"
limit         = "high + 10"
next_block_id = "confirm_entry"

Long with an equity percentage and zero delay#

This example opens a long position by committing 60% of equity and moves immediately to the confirm_entry block. With wait_candles = 0, the next block is evaluated on the same candle as the entry signal, without waiting for the next candle. The order is still executed normally, but the position state may not yet be updated when the next block is evaluated.

[[entry]]
id            = "open_long_fast"
order_id      = "open_long_fast"
direction     = "long"
qty_percent   = 60
wait_candles  = 0
next_block_id = "confirm_entry"

Block parameters#

Local sizing priority#

In [[entry]], the engine always follows the same priority:

1. if qty is defined, that absolute quantity is used
2. otherwise, if qty_percent is defined, that equity percentage is used
3. otherwise, the engine falls back to the global [backtest] configuration

In other words, qty and qty_percent make the global sizing inactive for that order.

Meaning of qty_percent#

In [[entry]], qty_percent always means a percentage of equity.

This remains true at runtime even if [backtest].default_qty_type is fixed or cash. In that case, qty_percent forces a percent-of-equity behaviour for that order only.

Sizing price versus execution price#

When entry sizing depends on a budget or on a reference price, the engine can use a sizing price that differs from the real fill price.

This matters especially for non-trivial orders, including stop, limit, or stop-limit orders:

• quantity can be computed from a sizing price
• the order is then executed at the real fill price
• the final notional can therefore differ from the initial estimate

For the general rule about sizing price and execution price, refer to Using Margin and Leverage in Whale‑E.

Important (Grid Search): Using qty or qty_percent inside a block makes the volume for that order static from the point of view of global parameters. That order will therefore not be affected by default_qty_value, long_size_multiplier, or short_size_multiplier during grid search.