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_USDTandBTC_USDC, orBTC_USDTandETH_BTC), the balance is their sum and cannot be split. So every strategy that may touch the account must declare itssymbols; one that does not counts as trading everything. The executors are not traders, and neither isBinanceOrderUpdatesfrom 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.
settlesecondscovers 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
maxattemptsis 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:
- the symbol is still degraded;
- no order of it is working;
asofis after the activation started, and after its last order or fill on the symbol;- 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
symbolsbut is not onStrategyWorkerBaseis 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
feeassetsconfig, not read from the venue.