Account State Snapshots for Balances and Margin Tracking
Summary
The document explains an account-state object used to represent a snapshot of balances and margin information. Such snapshots can arrive from venue updates through an execution client or be calculated by a portfolio after a position change when calculation is enabled for a margin account. A flag distinguishes exchange-reported state from system-calculated state, and the portfolio consumes these events to track balances and exposure.
The listed fields include account identity and type, an optional base currency for multi-currency accounts, balances, margins, event identifiers and timestamps, and venue-specific untyped information. The account can be queried through the portfolio, and the returned value is detached: changing it does not alter the engine’s authoritative account. This is an interface and accounting explanation, not a trading strategy or performance study; it does not specify venue reconciliation behavior or how particular margin models calculate values.
Key ideas
- Account state captures account balances and margin information in a snapshot.
- Snapshots may come from venue reports or be calculated by the portfolio after position updates.
- A flag indicates whether a snapshot was reported by the venue or calculated by the system.
- The portfolio uses account-state events to maintain balance and exposure tracking.
- A queried account is detached, so mutating the returned value does not update the engine’s authoritative state.
Tags
Full text
# AccountState
# AccountState
`AccountState` carries a snapshot of an account's balances and margins. The system publishes it when
the venue reports an account update through the execution client, or when the `Portfolio`
recalculates account state after a position update (for margin accounts with
`calculate_account_state` enabled). The `Portfolio` subscribes to these events internally
to maintain exposure and balance tracking.
The `is_reported` flag distinguishes venue-reported snapshots from system-calculated ones.
## Fields
| Field | Python type | Required/default | Description |
| --------------- | ---------------------- | ---------------- | ------------------------------------------------------------------------- |
| `account_id` | `AccountId` | Required | The account ID (with the venue). |
| `account_type` | `AccountType` | Required | The account type (`CASH`, `MARGIN`, `BETTING`, or `WALLET`). |
| `base_currency` | `Currency` or `None` | `None` | The account base currency (`None` for multi-currency accounts). |
| `is_reported` | `bool` | Required | If the state is reported from the exchange (otherwise system-calculated). |
| `balances` | `list[AccountBalance]` | Required | The account balances (may be empty). |
| `margins` | `list[MarginBalance]` | Required | The margin balances (may be empty). |
| `event_id` | `UUID4` | Required | The event ID. |
| `ts_event` | `int` | Required | UNIX timestamp (nanoseconds) when the event occurred. |
| `ts_init` | `int` | Required | UNIX timestamp (nanoseconds) when the object was initialized. |
| `info` | `dict` | `None` | Venue-specific account data with no typed field (empty dict when unset). |
## Example
Account state is normally consumed through the `Portfolio` rather than a dedicated handler:
```python
from nautilus_trader.model import Venue
# Account state is tracked by the portfolio; query it by venue
account = self.portfolio.account(venue=Venue("BINANCE"))
self.log.info(f"Account state: {account}")
```
The result is detached from the Portfolio. Mutating the returned account does not change the
authoritative account held by the engine.
## Related guides
- [Events](index.md) - Event categories and dispatch.
- [Accounting](../accounting.md) - Account types, balances, and margin models.
- [Portfolio](../portfolio.md) - How account state feeds exposure and balance tracking.Shown in full with attribution under the source's licence. Licence: LGPL-3.0
This summary was written by Stratmill's research agent from the original; it is not a copy of the source.