| Next revision | Previous revision |
| developers:apiv2:accounts [2026/09/07 18:16] – created chad | developers:apiv2:accounts [2026/09/07 21:57] (current) – [Subscribe] chad |
|---|
| Subscribe to one or more accounts to receive their balances, positions, P&L and order status in real time. | Subscribe to one or more accounts to receive their balances, positions, P&L and order status in real time. |
| |
| **You must subscribe to an account before routing orders into it** — order submissions for an unsubscribed account are rejected. See [[developers:apiv2:orders|Order Routing]]. | <note tip>You must subscribe to an account before routing orders into it.</note> |
| | |
| | <note tip>You can auto-subscribe all accounts for your user with a single message.</note> |
| |
| ===== Subscribe ===== | ===== Subscribe ===== |
| |
| Send ''AccountSubscribe'': | Send [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L12|AccountSubscribe]] to subscribe an account, or all accounts: |
| |
| <code> | <code> |
| </code> | </code> |
| |
| The server replies with ''AccountSubscribeResponse'' (''success'', ''errors[]''). | |
| | Note: [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/common/enums.proto#L648|UPLMode]] allows you to save bandwidth by turning off real-time UP&L calculation and message delivery. (UP&L is updated in real-time as the market moves.) |
| | |
| | ^ Value ^ You receive ^ |
| | | ''UPL_MODE_NONE'' | Turns off UP&L calculation and message delivery | |
| | | ''UPL_MODE_AVERAGE'' | Computes UP&L as the average open price compared to the current market | |
| | |
| | |
| | The server replies with [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L18|AccountSubscribeResponse]], followed by one or more [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L161|AccountSnapshot]] messages if the subscription was successful. |
| |
| ===== Snapshot, then updates ===== | ===== Snapshot, then updates ===== |
| |
| On subscribe you receive an ''AccountSnapshot'' — the current state as a bundle of ''messages'': ''AccountDetails'', ''AccountUpdate'', ''AccountPosition'', ''AccountCurrency'', ''MarketDetails'', and open-order ''OrderUpdate''s. (A position's ''MarketDetails'' is always sent before the position.) | On subscribe you receive an [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L161|AccountSnapshot]] — the current state as a bundle of messages: [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L107|AccountDetails]], [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L78|AccountUpdate]], [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L34|AccountPosition]], [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L26|AccountCurrency]], [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L29|MarketDetails]], and open-order [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/orderrouting/orderrouting.proto#L155|OrderUpdate]] messages. |
| |
| After the snapshot, individual messages stream as things change: | |
| |
| ^ Message ^ Carries ^ | After the snapshot, update messages stream in real-time: |
| | ''AccountUpdate'' | Balance, margin (day/full/pre-trade), P&L rollups. | | |
| | ''AccountPosition'' | Per-market position: buys/sells, open volume, average price, margin. | | |
| | ''AccountProfit'' | Account-level UPL / RPL, working-order totals, alerting flags. | | |
| | ''AccountPositionProfit'' | Per-position UPL / RPL (incl. USD-converted). | | |
| | ''AccountCurrency'' | Currency conversion rates. | | |
| | ''OrderUpdate'' | Order status/fills for the account — see [[developers:apiv2:orders|Order Routing]]. | | |
| |
| ===== Reference ===== | ^ Message ^ Carries ^ |
| | | [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L78|AccountUpdate]] | Balance, margin (day/full/pre-trade), P&L rollups. | |
| | | [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L34|AccountPosition]] | Per-market position: buys/sells, open volume, average price, margin. | |
| | | [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L171|AccountProfit]] | Account-level UPL / RPL, working-order totals, alerting flags. | |
| | | [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/account/account.proto#L191|AccountPositionProfit]] | Per-position UPL / RPL (incl. USD-converted). | |
| | | [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/orderrouting/orderrouting.proto#L155|OrderUpdate]] | Order status updates — see [[developers:apiv2:orders|Order Routing]]. | |
| | | [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/orderrouting/orderrouting.proto#L258|OrderTrade]] | Order fills. | |
| |
| Messages and every field: ''proto/t4/v2/account/account.proto''. See the [[developers:apiv2:reference|Message Catalog]]. | |
| |