Skip to content

Actions#

Each TP level (and custom event) is an ordered list of actions. Actions execute sequentially within a level — if one is skipped, the rest still run.

Action Params Effect Writes a TradeLeg?
move_sl_be — Move SL to break-even (entry fill price). No
move_sl_pct percent (0–100) Move SL to a % offset from current price. No
reduce_position percent (0–100) Market-close N% of remaining qty. Yes (*_reduce)
add_to_position percent (0–1000) Market-add N% of current qty. Yes (*_add)
close_position — Market-close 100% of remaining qty. Yes (tp1/tp2/tpN)
activate_trail — Arm the trailing stop. No
cancel_algo_orders — Cancel resting SL/TP algos on the exchange. No

move_sl_be#

Moves the stop-loss and trailing-stop reference to the actual fill price (or the requested entry price if fill details could not be confirmed), then modifies the resting SL order on Binance.

{ "type": "move_sl_be" }
  • "Break-even" means the entry price, not entry + commission. Per-side fees still apply if the SL hits.
  • Sets both the stop-loss and trailing-stop reference to the same value, so any subsequent trail update ratchets only from BE forward.
  • In-the-money safety guard: if the proposed BE stop is already through the current mark price (a long where mark < entry, or a short where mark > entry), the action is skipped with warning sl_already_in_the_money rather than submitted. Subsequent actions in the same level still run. This prevents an instant stop-out when the platform feed hasn't yet reached the level the webhook fired from — typical for paper trades receiving mainnet-derived TV alerts.

move_sl_pct#

Moves the SL to percent % below the current market price (longs) or above it (shorts). Also updates the trailing-stop reference and modifies the resting Binance SL order.

{ "type": "move_sl_pct", "percent": 0.5 }
  • percent is interpreted as a percentage of current price.
  • If the current price can't be fetched, the action logs a warning and is skipped.
  • The same in-the-money safety guard as move_sl_be applies.

reduce_position#

Closes percent % of the remaining position via a market order. HookTrader updates the tracked position size by the amount actually closed (after lot-size rounding).

{ "type": "reduce_position", "percent": 50 }
  • percent is of current qty, not original.
  • If qty rounds down to 0 (very small remaining vs symbol's LOT_SIZE step), the action is skipped and no leg is written.
  • The exchange call uses cancel_algo_orders=False so the resting SL stays in place.

Phase recorded: tpN_reduce.

add_to_position#

Places a new market order in the same direction as the trade, sized at percent % of current qty.

{ "type": "add_to_position", "percent": 50 }
  • percent can go up to 1000 (10× scale-in).
  • Phase recorded: tpN_add.

Scale-ins don't update the resting SL

The Binance SL/TP algos are sized to the original entry qty. After a scale-in, the resting SL still only protects the original position; the added qty is exposed until the next move_sl_* action runs. Always pair add_to_position with a move_sl_* action in the same TP level so the SL covers the new total.

Scale-ins don't realise PnL

Scale-ins have no realised PnL (Binance reports zero for opens). Commission is captured, so scale-in fees are included in the trade's total commission.

close_position#

Market-closes 100% of the remaining qty. Sets state.qty = 0. After this runs the position is gone and the trade is treated as exited.

{ "type": "close_position" }

Phase recorded: tpN.

Edge case — exchange already closed the position: if Binance's own take-profit order closes the position before this action runs, the close request may be rejected. HookTrader detects this, records the trade as closed, and continues. To avoid this race, you can use cancel_algo_orders at the TP level where you want your strategy to control the close.

activate_trail#

Arms the trailing stop. Until activated, HookTrader's autonomous trail watcher is dormant — trail_update events are still accepted, but the price watcher won't act on a trail-cross.

{ "type": "activate_trail" }

This action does not move the SL. Pair it with move_sl_be / move_sl_pct if you want to tighten at the same moment.

See SL / TP / Trailing → Trailing stop for the full lifecycle.

cancel_algo_orders#

Cancels all resting algo (SL/TP) orders for the trade's symbol on the exchange.

{ "type": "cancel_algo_orders" }

Use when you want strategy-driven closes to be authoritative without racing the exchange's algo TP — for example, cancel algo orders at TP1 so the rest of the trade is managed entirely by webhook events and the autonomous monitor.

Trade-off: after this runs, the position has no exchange-side stop until the next move_sl_* action places a new one. If HookTrader is briefly unavailable between the cancel and the next SL placement, the position is unprotected.

See also#