Position Action

Overview

Position Action includes 6 tools for this workflow area.

Available tools: cancel_trailing_stop, close_all_positions, get_trailing_status, reverse_position, set_breakeven, set_trailing_stop.

Use the parameter tables and examples below as the canonical request contract.

cancel_trailing_stop

Removes the trailing stop on a position. The stop-loss stays where the trail last put it; it simply stops moving. The server's copy is retired too, so the trail is not re-armed after a restart. NOT_FOUND means that ticket has no trail. MT5 only (EA with trailing_cancel support; an older EA is refused with ea_upgrade_required). Defaults to dry_run=true — set dry_run=false to cancel. Requires the trade capability.

Leases: if another agent holds a lease (see acquire_lease / get_leases) on this ticket or its symbol, the call is refused with code LEASED and current_state {resource, holder, expires_at} unless you pass that lease's lease_token. Nothing is changed when refused.

Parameters

Example Request

{
  "tool": "cancel_trailing_stop",
  "arguments": {
    "ticket": 123456,
    "dry_run": true
  }
}

Usage Notes

• Keep dry_run: true until you have validated symbol, lot size, and expected execution behavior.

close_all_positions

Closes all currently open positions, optionally filtered by symbol. The EA executes all closes in a single command to avoid N round-trips and partial-disconnect risk. Returns a results array with per-ticket success/failure. Defaults to dry_run=true — set dry_run=false to execute live. Requires the trade capability and inp_AllowTrading=true on the EA.

Leases: if another agent holds a lease (see acquire_lease / get_leases) on this ticket or its symbol, the call is refused with code LEASED and current_state {resource, holder, expires_at} unless you pass that lease's lease_token. Nothing is changed when refused. Because this touches every position (or every position of the symbol), a lease on any of them refuses the whole call. Emergency override: owner "guardian" with override=true closes the position even though it is leased (it never allows a modification), and the override is journalled.

Parameters

Example Request

{
  "tool": "close_all_positions",
  "arguments": {
    "dry_run": true
  }
}

Usage Notes

• Keep dry_run: true until you have validated symbol, lot size, and expected execution behavior.

get_trailing_status

Shows the trailing stops the EA is running: for each, mode and its parameters, whether it is armed (false while waiting for activate_at_r), current_r when an R basis exists, last_sl_update {time_utc, price} (null until the first move), candidate_sl (the stop the next evaluation would set, or null when it would not move: not armed, not better than the current stop, or no swing/indicator value yet) and failure_streak (consecutive broker rejections). restoring=true marks a trail loaded from the EA's saved state whose position the terminal has not listed yet. Prices are absolute, times are UTC ISO strings, trails are ordered by ticket. persisted=false means the EA could not write its state file and the trails would not survive a restart. Pass ticket for one position; NOT_FOUND means that ticket has no trail. MT5 only, with an EA that has persistent trailing (1.403 or later); MT4 is refused with NOT_SUPPORTED_ON_MT4.

Parameters

Example Request

{
  "tool": "get_trailing_status",
  "arguments": {}
}

reverse_position

Closes an open position and opens a market order in the opposite direction as ONE EA command (single trade-context acquisition — minimises the gap between the two fills vs separate close_position + place_order calls). volume defaults to the closed volume; optional stop_loss / take_profit apply to the new position. If the close succeeds but the open fails (margin, market closed), returns REVERSE_PARTIAL with the close details and leaves the account flat — the EA never retries the open on its own. Defaults to dry_run=true — set dry_run=false to execute live. Requires the trade capability and inp_AllowTrading=true on the EA.

Leases: if another agent holds a lease (see acquire_lease / get_leases) on this ticket or its symbol, the call is refused with code LEASED and current_state {resource, holder, expires_at} unless you pass that lease's lease_token. Nothing is changed when refused.

Parameters

Example Request

{
  "tool": "reverse_position",
  "arguments": {
    "ticket": 123456,
    "dry_run": true
  }
}

Usage Notes

• Keep dry_run: true until you have validated symbol, lot size, and expected execution behavior.

set_breakeven

Moves the stop loss of a position (or all positions) to its entry price. Optional buffer_points adds N points on the safe side of entry. Returns POSITION_NOT_IN_PROFIT if the position has not yet moved favourably. Defaults to dry_run=true — set dry_run=false to execute live. Requires the trade capability and inp_AllowTrading=true on the EA.

Optional preconditions for safe concurrent use: expect_sl and expect_tp (prices; 0 = none set), expect_volume (lots) and tolerance_points (price slack in points, default 0). If the position no longer matches, nothing is changed and the call returns code PRECONDITION_FAILED with current_state {ticket, symbol, sl, tp, volume} so you can re-read and decide. With dry_run=true a mismatch is reported the same way and a match adds preconditions_ok. Requires an up-to-date EA build; an older build is refused with ea_upgrade_required rather than skipping the check. Preconditions need a ticket (they describe one position), so combining expect_* with no ticket is rejected.

Leases: if another agent holds a lease (see acquire_lease / get_leases) on this ticket or its symbol, the call is refused with code LEASED and current_state {resource, holder, expires_at} unless you pass that lease's lease_token. Nothing is changed when refused. Without a ticket this touches every open position, so a lease on any of them refuses the call.

Parameters

Example Request

{
  "tool": "set_breakeven",
  "arguments": {
    "dry_run": true
  }
}

Usage Notes

• Keep dry_run: true until you have validated symbol, lot size, and expected execution behavior.

set_trailing_stop

Registers a trailing stop on an open position. The EA moves the stop-loss behind price as the position profits, and NEVER loosens it: a candidate stop that is not strictly better than the current one (by at least step_points, and at least one point) is skipped. Setting a trail on a ticket that already has one replaces it.

Modes (mode, default fixed_points): fixed_points = trailing_points behind price; atr = atr_multiplier × ATR(atr_period) behind price; chandelier = highest high (lowest low for sells) over atr_period bars minus (plus) atr_multiplier × ATR(atr_period); structure = behind the most recent confirmed swing low (swing high for sells) on timeframe, minus buffer_points. A swing needs two later closed bars to be confirmed, and the indicator modes read closed bars only. Distances are in POINTS (not pips; 10 points = 1 pip on 5-digit symbols), levels are prices, and timeframe is one of M1 M5 M15 M30 H1 H4 D1 W1 MN1.

Options: activate_at_r waits until the position is that many R in profit (R = distance from entry to the original stop, or to r_basis_sl; later stop moves never change it); step_points sets the minimum improvement per move; bar_close_only evaluates once per new bar of timeframe instead of on every EA timer tick (200 ms by default). The response reports trail_mode (the trail's mode; mode is the session trading mode), armed (false while waiting for activate_at_r) and persisted.

On MT5, trails are saved by the EA and re-armed automatically when the EA or terminal restarts, and a copy kept by the server restores them if the terminal lost its saved state. They keep running while the terminal is disconnected from the server, since they only tighten stops already registered. Every stop move is recorded in the journal (role system, tag trailing-stop). Use get_trailing_status to see what is running and cancel_trailing_stop to remove one. The modes and options need EA 1.403 or later; an older EA is refused with ea_upgrade_required. MT4 supports only a fixed trailing_points trail, which is not saved and ends when the EA restarts; anything else is refused with NOT_SUPPORTED_ON_MT4.

Defaults to dry_run=true — set dry_run=false to register live. Requires the trade capability and inp_AllowTrading=true on the EA.

Optional preconditions for safe concurrent use: expect_sl and expect_tp (prices; 0 = none set), expect_volume (lots) and tolerance_points (price slack in points, default 0). If the position no longer matches, nothing is changed and the call returns code PRECONDITION_FAILED with current_state {ticket, symbol, sl, tp, volume} so you can re-read and decide. With dry_run=true a mismatch is reported the same way and a match adds preconditions_ok. Requires an up-to-date EA build; an older build is refused with ea_upgrade_required rather than skipping the check.

Leases: if another agent holds a lease (see acquire_lease / get_leases) on this ticket or its symbol, the call is refused with code LEASED and current_state {resource, holder, expires_at} unless you pass that lease's lease_token. Nothing is changed when refused.

Parameters

Example Request

{
  "tool": "set_trailing_stop",
  "arguments": {
    "ticket": 123456,
    "timeframe": "M1",
    "dry_run": true
  }
}

Usage Notes

• Use one timeframe for quick checks and multiple timeframes only when you need cross-timeframe analysis.
• Keep dry_run: true until you have validated symbol, lot size, and expected execution behavior.