Trading

Overview

Trading includes 3 tools for this workflow area.

Available tools: close_position, modify_position, place_order.

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

close_position

Closes an open position by ticket. 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.

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. 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_position",
  "arguments": {
    "ticket": 123456,
    "dry_run": true
  }
}

Usage Notes

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

modify_position

Modifies the stop_loss and/or take_profit of an open position (a ticket in get_positions). Distinct from modify_pending_order (order-management.ts), which modifies a not-yet-filled pending order (a ticket in get_orders) and also accepts price/expiry. At least one of stop_loss or take_profit must be provided. stop_loss and take_profit are prices (0 removes the level). 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.

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": "modify_position",
  "arguments": {
    "ticket": 123456,
    "dry_run": true
  }
}

Usage Notes

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

place_order

Places a market or pending order on MT5. Defaults to dry_run=true — set dry_run=false to execute live. Pending orders may set expiry (unix epoch seconds) for broker-side expiration; expiry is rejected on market orders. Requires the trade capability and inp_AllowTrading=true on the EA.

idempotency_key (optional, 8-64 chars of A-Z a-z 0-9 _ -) makes the live call safe to repeat: use one key per logical order, and any repeat with the same key within 24 hours places nothing and returns the original result with duplicate: true. Reusing a key for a different order (other symbol, volume, type, price, stop or target) is refused with code DUPLICATE and current_state describing the order the key is bound to. If the first attempt timed out, a repeat is refused as outcome_unknown — check get_positions and get_orders (the order comment starts with k:<10 hex characters> derived from the key) instead of retrying. A key is freed when the terminal definitively refuses the order, so a corrected retry can reuse it. Keys are per terminal. dry_run=true calls ignore the key and never consume it. Without idempotency_key, identical live calls within about 20 seconds are still de-duplicated, silently. The EA keeps the key marker as the first characters of the order comment, which shortens the comment you can set (brokers allow roughly 31 characters).

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. For place_order the resource is the order's symbol: a lease on "symbol:EURUSD" blocks new EURUSD orders from anyone without its token.

Parameters

Example Request

{
  "tool": "place_order",
  "arguments": {
    "symbol": "EURUSD",
    "volume": 1,
    "order_type": "BUY",
    "dry_run": true
  }
}

Usage Notes

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