Account streams
Keep account state scoped, current and consistent across your integration.
Load the approved account’s initial state
Read the account snapshot, open positions and live open orders once for the account bound to the approved key. Mint a realtime ticket, authenticate the socket, wait for auth_ok and subscribe with its accountId. Keep data associated with both account and environment, and clear that association when the active identity changes.
GET /v1/accounts/{accountId}/orders/open returns live working orders. GET /v1/accounts/{accountId}/orders returns order history, which can lag live account updates. A history row is not evidence that an order remains open. The open-orders response is bounded: inspect truncated and openOrderCount, and use its resync metadata only when truncated is false.
Account state
Use one account-scoped state model for positions, PnL, margin, orders and fills. Apply validated private events directly so every view uses the same account identity and freshness rules.
Validate completeness. A message may update only part of an account. Preserve the freshness state of fields the message does not establish; do not replace missing values with zero.
Separate command feedback. An HTTP response reports the order command’s outcome. Confirm working orders, fills and position changes through the corresponding account events.
Recover deliberately. After a gap, follow the channel’s replay or snapshot recovery instruction. If replay or payload coverage is insufficient, keep that scope stale until it can be reconciled. Reconnecting alone does not prove that missed changes have been recovered.
Account channel reference
All account channels require ticket authentication. The channel contract assigns each channel an availability label. Read the current catalogue when connecting rather than treating every declared channel as an active source.
| Channel | What it reports | Source status |
|---|---|---|
| account.orders | Order lifecycle updates | live |
| account.fills | Executed account fills | live |
| account.durability | Saved-through progress for accepted events | live |
| account.positions | Position changes | live |
| account.pnl | Realized/unrealized PnL state and changes | live |
| account.margin | Margin, maintenance, health, liquidation-candidate and bad-debt updates | digest |
| account.balance | Balance updates | live |
| account.withdrawals | Withdrawal-state events; not withdrawal authority | live |
| account.earnings | Affiliate earnings projection | projection |
| account.reconciliation | Declared reconciliation information | unavailable |
| account.alerts | Declared account alerts | unavailable |
Read liquidation and auto-deleveraging fields
Account and position payloads report the values behind liquidation and auto-deleveraging. Treat an absent field as unavailable, not as zero. CCXT v2 balance, position, order and trade responses carry the same fields under info.
A liquidation fee or an insurance fund cover is not sent as a separate event; each appears only as a change in the cash balance reported on account.margin.
Order ids that start with ord_liquidation_ or ord_adl_ are reserved for orders the venue places during liquidation and auto-deleveraging. A client order whose clientOrderId uses either prefix is rejected with invalid_order_id.
| Field | Where | Meaning |
|---|---|---|
| maintenanceRequirementAtoms | account.margin, GET /v1/accounts/{accountId} | The maintenance margin the account must hold across all of its positions, in settlement-asset atoms. |
| marginHealthBps | account.margin, GET /v1/accounts/{accountId} | Equity divided by the maintenance requirement, in basis points. 10000 is exactly at maintenance and is also reported when nothing is at risk. Signed; absent when it cannot be computed. |
| liquidationCandidate | account.margin, GET /v1/accounts/{accountId} | True while equity is below the maintenance requirement or the account holds bad debt. A candidate cannot withdraw or add risk. |
| badDebtAtoms | account.margin, GET /v1/accounts/{accountId} | A liquidation loss that the order book, the insurance fund and auto-deleveraging did not cover. The account stays blocked while it is above 0. |
| adlIndicator | account.positions, GET /v1/accounts/{accountId}/positions | The position's place in the market's auto-deleveraging queue, from 1 to 5; 5 is reduced first. Display only, refreshed on each liquidation pass and absent until the market has been ranked. |
| origin | account.orders, account.fills, order and fill history | liquidation for a liquidation close or auto_deleverage for an auto-deleveraging leg. Present only on orders and fills the venue placed. |
Track order, fill and durability events
An order response reports command feedback. Order updates track lifecycle changes, fills record execution, and durability updates report saved-through progress. Correlate them using the order and sequence fields in each payload. Durability confirms persistence, while Canton settlement has its own confirmation.
A cancel affects only the unfilled remainder, and fills can arrive while cancellation is pending. Reconcile fills and positions before calculating a replacement quantity or treating exposure as zero. Keep an unknown outcome visible until the order read and streams resolve it.
Reconcile after a gap or dropped private session
Mark affected account state stale when authentication or continuity is lost. Restore the correct ticket and accepted channel scopes, then follow the channel’s supported recovery procedure. Complete position frames can update size, entry, mark, PnL and closure directly; a partial payload must not be treated as a complete account snapshot.
Seed and live sequence values are not universally interchangeable. Use only the replay and recovery rules defined for the channel. Routine live updates should not trigger account GETs, and a healthy socket alone must not make last-known balances appear fresh.
Confirm that the received fields cover the view or decision you are updating. Orders placed by another client, financial changes without an open position and owner funding activity may require information beyond a position update. If the available data cannot establish current state, keep the affected view stale or snapshot-only. See WebSocket recovery.
Read paginated account history
Order history, fill history and position history return one page with nextCursor and projection freshness. Their default page size is 50 and maximum is 100. Pass back the returned cursor and preserve your filters; stop when nextCursor is null. All support marketId; order and position history also support their documented status filters.
fundingPaidAtoms in a position episode is cumulative funding for that episode. It is not a separate funding-payment ledger. The public API and edel_funding tool do not provide per-payment funding rows. Do not synthesize those rows from successive snapshots or count cumulative funding repeatedly.