Exit Plan

Overview

Exit Plan includes 3 tools for this workflow area.

Available tools: cancel_exit_plan, get_exit_plan, set_exit_plan.

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

cancel_exit_plan

Stops an active exit plan on a ticket. Stages that already fired are not undone and the position itself is not touched; the plan stays readable with status cancelled and its remaining stages as not_fired, and the cancellation is journalled. NOT_FOUND means the ticket has no active plan. Cancelling removes automatic protection, so dry_run defaults to 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_exit_plan",
  "arguments": {
    "ticket": 123456,
    "dry_run": true
  }
}

Usage Notes

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

get_exit_plan

Shows the exit plan on a ticket: its status (active, completed, cancelled) and completion_reason (position_closed, all_stages_fired, completed_with_failures, closed_by_plan, cancelled), the R basis (r_basis_sl and risk_distance, a price distance), and every stage in the order it will fire with its status (pending, fired, failed, or not_fired once the plan has ended), trigger, trigger_price (the price a r_multiple or price trigger sits at, otherwise null), fired_at (UTC) and fired_price once fired (first_attempt_at while a stage that started firing waits for a retry), attempts and last_error, and each action's own status (pending, done, skipped, failed) with a note saying why one was skipped (for example a stop that would have loosened). Also current_r and current_price while the plan is active and the terminal is connected, next_stage (the stage waiting to fire and where its trigger is), and ticket_history. After the position closes this still returns the finished plan. NOT_FOUND means no plan has ever been set on that ticket. Requires the read capability.

Parameters

Example Request

{
  "tool": "get_exit_plan",
  "arguments": {
    "ticket": 123456
  }
}

set_exit_plan

Attaches a staged exit plan to an open position (a ticket in get_positions) so that partial profits, break-even moves and trailing stops happen on time even if no agent is running. An exit plan is an ordered list of stages attached to one open position, executed by the platform without any agent running. Each stage has an id (letters, digits, _ and -, unique in the plan), a trigger and one to five actions.

Triggers: {type:"r_multiple", value} fires when profit reaches that many R (R = distance from entry to the original stop, fixed when the plan is set; later stop moves never change it); {type:"price", value} fires when the exit-side price (bid for buys, ask for sells) reaches that price, which must be on the profit side of entry; {type:"time", value} fires at an ISO UTC time (or epoch seconds) in the future; {type:"bars_elapsed", value, timeframe} fires after that many closed bars of M1..MN1 since the position opened (only bars that exist, so market-closed hours do not count; value up to 4998; while the market is closed the last bar counts once the next one opens).

Actions: {type:"partial_close", percent} closes that percent of the ORIGINAL volume (or {volume} in lots; rounded down to the symbol's lot step; when the partials add up to 100%, the last one closes whatever is left, and a partial that would leave less than the minimum lot is skipped); {type:"move_sl", to:"breakeven", buffer_points?} puts the stop at entry plus buffer_points on the safe side; {type:"move_sl", to:"lock_r", r} puts it r×R in profit (r must be below the stage's own r_multiple trigger); {type:"move_sl", price} puts it at an absolute price; {type:"start_trail", trail:{...}} starts a trailing stop with the same fields as set_trailing_stop (mode, trailing_points, atr_period, atr_multiplier, timeframe, buffer_points, activate_at_r, step_points, bar_close_only); {type:"close"} closes what is left (it must be the last action of the last stage). Distances ending in _points are POINTS, not pips.

Rules: stages fire strictly in the order given, each at most once; if price gaps through several triggers they fire one after another. Stage triggers of type r_multiple and price must not go back towards entry from one stage to the next. Partial closes may add up to at most 100% of the original volume. A move_sl never loosens a stop: if the requested stop is not strictly better than the current one, or price has already moved back through it, that action is skipped (the stage still counts as fired) and the skip is recorded in the journal. A plan that is not valid returns code INVALID_PLAN with the reason.

On MT5 a partial close keeps the position's ticket (the plan keeps following it; if a terminal ever reports a different ticket the plan follows that and lists the old one in ticket_history). Rejected actions are retried after 2 s, 10 s and 30 s, then the stage is marked failed and later stages carry on. The plan completes when the position closes or every stage has been handled. Every fired, skipped and failed action is written to the journal (role system, tag exit-plan).

Limits: executed by the server about every 1.5 seconds, not on every tick, and only while the terminal is connected to the server; a fast spike can pass a level between checks (the stage then fires on the next check). A trailing stop started by a plan keeps running in the EA even if the connection drops.

A ticket can have one active plan; setting another returns DUPLICATE with the existing plan in current_state (cancel_exit_plan first). idempotency_key (8-64 chars) makes a repeated call return the plan it created with duplicate: true. Returns the plan with each stage's trigger_price (where one exists), current_r and next_stage. Defaults to dry_run=true, which validates and shows the plan without saving it — set dry_run=false to arm it. Requires the trade capability.

Optional preconditions: 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, no plan is created and the call returns code PRECONDITION_FAILED with current_state {ticket, symbol, sl, tp, volume}.

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. Once created, the plan's own actions run as its creator and do not need the token again.

Parameters

Example Request

{
  "tool": "set_exit_plan",
  "arguments": {
    "ticket": 123456,
    "stages": [],
    "dry_run": true
  }
}

Usage Notes

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