ADR 0011: Close-all and cancel-all default to the trader's own magic¶
- Status: accepted (3.0.0). Decided by the package owner on 2026-11-09.
Context¶
close_positions() and cancel_pending_orders() without a magic acted on
the whole account, manual trades and other bots included. The README warned
about it in bold, but a bot that forgets magic once closes everything. MT5
gives trades opened by hand magic 0.
Decision¶
- Own by default. Without
magic, both calls act only on items whose magic equals the trader's (connect(..., magic=...)). With asymboltoo:close_positions("EURUSD")closing someone's manual EURUSD trade is the same hazard. This goes beyond the owner's question, which named only the no-argument call. - The whole account is spelled
ANY_MAGIC. An explicitmagic=Noneis still "own". We chose a named value instead ofNonebecause aNoneread from a missing config key would otherwise widen the call to the whole account, the exact accident this change removes. - A
ticketis closed whatever its magic. The caller named the position. Filtering it out would returnOk([])with the position still open. An explicitmagicstill applies to a ticket. - Reads are unchanged.
positions()andpending_orders()still list everything by default; they also acceptANY_MAGIC. A read cannot close anything, and narrowing it would hide positions from a status screen. - A magic outside MT5's ulong is refused as
INVALID_ARGUMENT("42",True,1.5,-1,2**64)."42"would match nothing and report an empty success with every position still open. - The trader's own magic must be an integer from 0 to 2**64-1 (MT5's
ulong).
connect()returnsErr(INVALID_ARGUMENT)andTrader(...)raisesValueErrorforNone,ANY_MAGIC,"1001"orTrue. Without this check,connect(magic=cfg.get("magic"))with the key missing made "own" mean "every magic" (found in review). Brokerkeeps 2.x.Close(symbol)andCancelOrders(symbol)closed every magic in 2.x, so the facade passesANY_MAGIC.
Consequences¶
- A trader connected with the default
magic=0shares that magic with manual trades, so its close-all still closes them. The protection only works once a bot sets its ownmagic. Makingmagicrequired inconnect()was offered before release; the owner chose to keepmagic=0as the default (2026-11-09). Residual risk: a bot that never setsmagicstill closes manual positions and cancels manual pending orders. A defaulted close/cancel on a magic-0 trader that matches something logs a warning that manual trades are included; an explicitmagic=0acknowledges it and logs nothing. - On a netting account one position per symbol collects every deal, and
it keeps the magic of the deal that opened it. A bot's deal that merges
into a manual position is then not "own", and a manual deal that merges
into the bot's position is. The magic filter cannot separate them; this is
a property of netting, not of this default. So that
Ok([])never reads as "flat" in silence, a defaulted close/cancel that matches nothing while items with other magics are in scope logs a warning naming how many were left open (one extra listing, only on that path). If that listing fails, the warning says so instead of dropping the error; the close/cancel staysOk, because it did what was asked and anErrwould invite a retry of an action that already ran. We did not detect the account's margin mode: it would add a port call for a case the warning already surfaces. application/magic_scope.pyholds the rule and its warnings, apart fromTrader.close_positions()ported from 2.xClose()now leaves positions of other magics open. MIGRATION.md mapsClose(s)toclose_positions(s, magic=ANY_MAGIC)for an exact equivalent.- The read/write asymmetry (
None= all for reads, own for closes) is deliberate. The parameter docstrings state it.