Skip to content

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 the snapshot command, and when any WebSocketFeed reports connected (the event does not say which account a feed serves, so at most once per 10 s): GET /api/v3/openOrders, then GET /api/v3/account. account.snapshot always, 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 the stateservice (default workmanager), in the background, so a reader that starts later (the TUI's Portfolio pane) finds it. time is that of the newest change.
  • What a snapshot promises. time is taken before the first read. Open orders are read before balances, so an order filling between the two reads is still listed as open. balances holds 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, so holdings is 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. outboundAccountPosition publishes the balances that changed, a frame up to the snapshot's updateTime is old and dropped. balanceUpdate posts a ledger entry (transfer: Binance does not say which it was). executionReport publishes the order, whoever placed it, once per change. Other frames are skipped. Before the first snapshot nothing is published.
  • Envelope. exchange=binance, portfolioworld, clocktype, venue eventtime, 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: executionReport carries BTCUSDT, and telling base from quote needs exchangeInfo, which nothing here reads.
  • listStatus (OCO), the assets allowlist, a database (none exists), the balance/openorder state keys of the spec's Portfolio state keys scenario: the account key holds them all.
  • BinanceHandshake: retired, the feed logs in itself.