BinancePortfolio
Observes one Binance spot account and publishes it as world-scoped portfolio
events (openspec pubsub-topics, Portfolio Events). Built on
Virtufin.Portfolio.DevKit. It never places, amends or cancels an order: its
REST client has one verb, GET, on two read-only paths.
Testnet only so far. It has never read a production account.
| Property | Value |
|---|---|
| Project | Virtufin.Worker.BinancePortfolio |
| Worker type | binanceportfolio |
| Base class | Virtufin.Portfolio.DevKit.PortfolioWorkerBase |
| Engine | application/x-dotnet-dll |
| Input topics | <world>.portfolio.binance.account.update.<account> (frames from a WebSocketFeed worker), wrk.binanceportfolio.command.{worker_id} (its trigger, the snapshot command), sys.workmanager.worker.lifecycle |
| Output topics | <world>.portfolio.binance.account.snapshot.<account>, ...balance.changed.<account>, ...openorder.changed.<account>, ...ledger.posted.<account> |
Behaviour
- Snapshot. On a trigger the worker schedules itself (first fire after 1 s,
then every
snapshotintervalseconds), on thesnapshotcommand, and when any WebSocketFeed reportsconnected(the event does not say which account a feed serves, so at most once per 10 s):GET /api/v3/openOrders, thenGET /api/v3/account.account.snapshotalways, then only what changed since the last one (saved in worker state, so a restart diffs instead of replaying). - Saved account. The account as last known (the snapshot, with each
balance and order change it publishes on top; an order that ended leaves it)
is saved at its public state key
<world>.portfolio.binance.account.<account>in thestateservice(defaultworkmanager), in the background, so a reader that starts later (the TUI's Portfolio pane) finds it.timeis that of the newest change. - What a snapshot promises.
timeis taken before the first read. Open orders are read before balances, so an order filling between the two reads is still listed as open.balancesholds every asset Binance lists, zero ones included: a zero proves the asset is flat, a missing asset proves nothing. Binance reports no holdings on spot, soholdingsis empty. - A failed read publishes nothing: the last snapshot stands, the status is
degraded, the next good read clears it. There is no partial snapshot. - Stream.
outboundAccountPositionpublishes the balances that changed, a frame up to the snapshot'supdateTimeis old and dropped.balanceUpdateposts a ledger entry (transfer: Binance does not say which it was).executionReportpublishes the order, whoever placed it, once per change. Other frames are skipped. Before the first snapshot nothing is published. - Envelope.
exchange=binance,portfolioworld,clocktype, venueeventtime,ingesttime, no scenario extensions (PortfolioEnvelope).
Config
| Name | Kind | Meaning |
|---|---|---|
account |
config, required | Logical account, lowercase. One worker per account. |
world |
config, required | hyp.<NAME> for the testnet, act for production. No default: testnet balances must never land in act. |
binancebaseurl |
config, required | REST base URL. No default: the code never names production. A testnet (or local) URL in act, or another URL in hyp.<NAME>, fails the start. |
snapshotintervalseconds |
config | Default 60. It is also how long a degraded strategy can wait for recovery. |
stateservice |
config | Default workmanager: the State service of the saved account. |
clocktype |
config | wall for a testnet account (the devkit's default in hyp is historical). |
binanceapikey, binanceapisecret |
worker secrets | By reference, resolved for every read. An HMAC key of the account, read permission is enough. |
Deploy
config/config.json is the testnet default (account: testnet, world:
hyp.TESTNET). The account stream is a WebSocketFeed worker with the preset
binance-account-testnet (market-data-devkit) and publishtopic the account's
update topic:
var topic = AccountTopics.Topic("hyp.TESTNET", "binance", "testnet", AccountTopics.Update);
var config = VenueFeeds.Config("binance-account-testnet",
new Dictionary<string, string> { ["publishtopic"] = topic }, "hyp.TESTNET");
// CreateWorker(config, secrets: { apikey: "<ed25519 key ref>", ed25519secret: "<private key ref>" })
The stream logs in with an Ed25519 key (Binance's WebSocket API); the REST reads sign with HMAC, so the account has two keys and both are worker secrets. The worker loses nothing but latency without the feed: the snapshots still run.
Not built (issue #1)
- The REST histories (
myTrades, deposits, withdrawals, dividends, dust): no ledger entry comes from them. - Ledger entries for fills:
executionReportcarriesBTCUSDT, and telling base from quote needsexchangeInfo, which nothing here reads. listStatus(OCO), theassetsallowlist, a database (none exists), thebalance/openorderstate keys of the spec's Portfolio state keys scenario: theaccountkey holds them all.BinanceHandshake: retired, the feed logs in itself.