Skip to content

Position recovery

How a strategy that lost track of its holdings gets them back, end to end. The decision rules are option A of openspec behaviour, Automatic Position Recovery; the reconciler's checks in detail are on BinancePositionReconciler, and the strategy's side in strategy-devkit's author guide.

The one rule behind every step: a wrong holding is worse than a stopped strategy. A strategy trading on a holding it does not have sells coins that are not its own, or buys twice. So every doubt ends in no event, an alert, and an operator.

When a strategy is degraded

A strategy built on StrategyWorkerBase keeps its holdings in its own fold, from its own fills, and saves them with its decision state. Three things make it lose track of a symbol. It then reports status degraded and names the symbols:

Cause Status says Trading
Its saved record is missing, unreadable, or of another version position unknown Every order is withheld, for every symbol
An order got no answer within ordertimeoutseconds (default 300 s) position unknown for <symbols> Orders for those symbols are withheld
A fill came without its fee fee unknown for <symbols> Keeps trading: the holding may be a little too high

It leaves that state for a symbol only on an absolute position event (opened, updated, flipped or closed) that sets it. Nothing else, including a restart, clears it.

Two ways back

Automatic Operator
Who publishes BinancePositionReconciler A person, through the API gateway
Source of the holding The venue's balance, from BinancePortfolio's account snapshot Whatever the operator has established
Marked by Extension asof: the time of the venue read No asof
Accepted by the strategy Only under the guard below Always, as a normal absolute event
Can raise a holding Never Yes

The automatic path

sequenceDiagram
    participant BP as BinancePortfolio
    participant R as BinancePositionReconciler
    participant WM as WorkManager
    participant S as Strategy
    BP->>R: account.snapshot (balances, open orders, read time)
    R->>WM: ListWorkers
    R->>S: positionstatus command
    S-->>R: degraded symbols, holdings, last activity
    R->>WM: ListWorkers again
    alt every check passes
        R->>R: save the attempt
        R->>S: position.opened / closed with asof
        S->>S: guard, then fold
        S-->>WM: status ok
    else any check fails
        R-->>R: status degraded, error event, log (once per change)
    end

Each snapshot (every snapshotintervalseconds, default 60 s) starts one pass. A pass decides per degraded symbol, and stops at the first question answered "no":

flowchart TD
    A["Degraded symbol"] --> B{"Strategy's scenario<br/>on this account?"}
    B -->|no / unclear| X(["No event, alert"])
    B -->|yes| C{"Sole trader of the asset?<br/>base or quote, any strategy,<br/>stopped ones too"}
    C -->|no / unclear| X
    C -->|yes| D{"Snapshot fresh, asset listed,<br/>no order open or working?"}
    D -->|no| X
    D -->|yes| E{"Read after activation and<br/>last order or fill + settle?"}
    E -->|no| X
    E -->|yes| F{"Venue holding at or below<br/>the last known holding?"}
    F -->|"no, or none known"| X
    F -->|yes| G{"Cooldown over,<br/>attempts left?"}
    G -->|"cooldown"| W(["Wait, no alert"])
    G -->|"attempts used up"| X
    G -->|yes| P(["Publish the venue's holding"])

Why each question

  • On the account, sole trader. A venue reports one balance per asset per account. If two strategies can move BTC on it (BTC_USDT and BTC_USDC, or BTC_USDT and ETH_BTC), the balance is their sum and cannot be split. So every strategy that may touch the account must declare its symbols; one that does not counts as trading everything. The executors are not traders, and neither is BinanceOrderUpdates from the org feed, which only turns the venue's execution reports into order events.
  • Fresh and still. An order open on the venue, or working in the strategy, can fill between the read and the event. Then the read is already wrong.
  • After the last activity. A read taken before the strategy's last fill misses that fill. settleseconds covers the venue's own delay.
  • The cap. The venue cannot say whose coins it holds: a deposit, a manual buy or a deleted strategy's leftovers look the same as the strategy's own. So a recovery may lower a holding to the venue's, never raise it. The last known holding is the one the strategy reports in positionstatus, from its fold.
  • Cooldown and attempts. The event needs time to arrive and be folded. A recovery that does not clear the degradation after maxattempts is a sign of something this worker cannot see.

What the cap decides

Why it is degraded Last known holding Venue holds Result
Fee unknown 1.000 0.999 Recovers to 0.999
Unanswered sell that filled 1.0 0.0 Recovers: closed
Unanswered order that never filled 1.0 1.0 Recovers to 1.0
Unanswered buy that filled 0.0 0.5 Refused: looks like a deposit
A deposit or manual buy 1.0 1.5 Refused
Saved record lost none any, even 0 Refused, always

Below the cap, foreign coins can still count: a strategy that last knew 1, sold 0.6 unseen and shares the balance with a deposit of 0.4 recovers to 0.8. It can never end above what it last knew.

The strategy checks again

The reconciler's read and the strategy's next input are apart in time. So the strategy repeats the decisive checks when the event arrives, and folds an asof event only if:

  1. the symbol is still degraded;
  2. no order of it is working;
  3. asof is after the activation started, and after its last order or fill on the symbol;
  4. the event's holding is at or below its last known holding.

Otherwise it drops the event, logs why, and stays degraded. This also protects it from any other publisher of an asof event: the cap holds even if the reconciler were wrong.

Alerts and what to do

The reconciler reports a refusal as status degraded with the reason, an error event on wrk.binancepositionreconciler.error, and a log line, each once per change. The strategy's own status stays degraded until it is recovered.

Reason (excerpt) Meaning What to do
exclusivity unknown: scenario … is not shown to trade on this account No executor of the scenario references this account's key, or they disagree Fix the executors' binanceapikey, or recover by hand
exclusivity unknown: … declares no config 'symbols' A strategy does not say what it trades Set symbols on every strategy on the account
shared: … moves <asset> Another strategy, or another of its own symbols, moves the asset Recover by hand
order … is open, it has an order working, the snapshot does not reach past its last order or fill, the snapshot is … s old Something may still fill, or the read is old Usually clears on a later snapshot
no last known holding to cap the venue's The saved record is lost Recover by hand
the venue holds …, above its last known … The venue holds more than the strategy knew Find out whose coins they are, then recover by hand
… recoveries did not clear it: giving up Published events did not land Check the strategy's log for dropped events, then recover by hand

The exact wording of each reason is in the checks table.

Recovering by hand

Establish the strategy's real holding first: the venue's balance minus coins that are not its own. Then publish an absolute position event without asof to its scenario, through the API gateway's Pubsub service:

Field Value
Topic sc.<scenarioid>.position.opened, or .closed for zero
ce-subject position/<PAIR>, e.g. position/BTC_USDT
Extensions the strategy's scenarioid and worlds, as on its other inputs
{"symbol": "BTC_USDT", "quantity": 0.25, "avgEntry": 0, "source": "External", "openedAt": "2026-11-08T10:00:00Z"}

For zero: {"symbol": "BTC_USDT", "closedAt": "2026-11-08T10:00:00Z", "realizedPnL": 0}.

The strategy folds it like any absolute event, sets the holding, and reports ok once no symbol is left unknown. The alternative is to delete and recreate the strategy, which starts it flat.

Limits

  • Binance spot testnet only, and nothing is deployed yet.
  • A trader outside WorkManager (the exchange UI, another cluster) is invisible unless it has an order open at the snapshot.
  • A worker that sets symbols but is not on StrategyWorkerBase is believed.
  • An order still in flight on an executor's inbox when the state was lost can fill after the read; its fill is then not folded.
  • Whether fees are paid in BNB is the feeassets config, not read from the venue.