> For the complete documentation index, see [llms.txt](https://docs.ndax.in/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ndax.in/v3/private-socket-feed/balances.md).

# Balances

The balance feed provides real-time updates when the balance is updated for any accounts that match the subscription filters.

#### Initial Subscription <a href="#initial-subscription" id="initial-subscription"></a>

In order to subscribe to the balance feed, a message of type `subscribe` must be sent.

<table><thead><tr><th width="142">Parameter</th><th width="501.3333333333333">Description</th><th>Type</th></tr></thead><tbody><tr><td>body{}</td><td>An object used to restrict what is returned in the subscription. This must be included but can be empty.</td><td>object</td></tr><tr><td>messageType</td><td>Subscription message type - <code>subscribe</code></td><td>string</td></tr><tr><td>topic</td><td>Topic to subscribe to - <code>balances</code> for the balance feed. Can be omitted.</td><td>string</td></tr><tr><td>useMultiChainAssetFormat</td><td>Include chain in asset names, e.g. <code>POLYGON</code> vs. <code>AAVE</code> for the balance feed. Can be omitted. Default is <code>false</code></td><td>boolean</td></tr><tr><td>key</td><td>Your public key</td><td>string</td></tr><tr><td>passphrase</td><td>Your passphrase</td><td>string</td></tr><tr><td>timestamp</td><td>Time in seconds since Unix Epoch</td><td>string</td></tr><tr><td>signature</td><td>your hmac signature</td><td>string</td></tr></tbody></table>

**Subscription Filters**

Optional filters you can include within the `body` to restrict which balance updates will be sent by the WebSocket:

<table><thead><tr><th width="155.33333333333331">Parameter</th><th width="306">Description</th><th>Type</th></tr></thead><tbody><tr><td>filter{}</td><td>A filter object used to specify account characteristics</td><td>object</td></tr></tbody></table>

The `filter{}` object can include:

<table><thead><tr><th width="202">Parameter</th><th width="405.3333333333333">Description</th><th>Type</th></tr></thead><tbody><tr><td>account_owner</td><td>The participant code for the specific participant you want updates for</td><td>string</td></tr><tr><td>account_group</td><td>The group that you want updates for</td><td>string</td></tr><tr><td>account_type</td><td>The type that you want updates for - <code>available</code>, <code>collateral</code>, <code>payable</code>, <code>receivable</code> or <code>collateral_deficiency</code></td><td>string</td></tr><tr><td>asset</td><td>The asset code you would like updates for</td><td>string</td></tr></tbody></table>

**Subscription Response**

> Subscription Response

```
{
    "messageType": "initial-balance",
    "body": [
        {
            "account_id": "12345",
            "participant_code": "ABC123",
            "account_group": "XXX456",
            "account_label": "general",
            "account_type": "available",
            "asset": "BTC",
            "balance": "1.00",
            "run_id": 1,
            "run_type": "unknown"
        }
    ]
}
```

Upon successfully subscribing you will receive an `initial-balance` message which includes a snapshot of all current account balances that meet your subscription criteria.

<table><thead><tr><th width="203.33333333333331">Parameter</th><th width="414">Description</th><th>Type</th></tr></thead><tbody><tr><td>account_id</td><td>Unique ID of the specific account</td><td>string</td></tr><tr><td>participant_code</td><td>The code of the participant that owns the account</td><td>string</td></tr><tr><td>account_group</td><td>The group that the account is a part of</td><td>string</td></tr><tr><td>account_label</td><td>The account label to filter the response by</td><td>string</td></tr><tr><td>account_type</td><td><code>available</code>, <code>collateral</code>, <code>payable</code>, <code>receivable</code> or <code>collateral_deficiency</code></td><td>string</td></tr><tr><td>asset</td><td>The asset code for the specific account, e.g. e₹</td><td>string</td></tr><tr><td>balance</td><td>The balance in the account</td><td>string</td></tr><tr><td>run_id</td><td>A unique ID for the particular run</td><td>int</td></tr><tr><td>run_type</td><td>The type of run</td><td>string</td></tr></tbody></table>

#### Balance Update <a href="#balance-update" id="balance-update"></a>

> Sample Response

```
{
    "messageType": "balance-updated",
    "body": {
        "participant_code": "ABC123",
        "account_group": "XXX456",
        "account_label": "general",
        "account_type": "available",
        "asset": "BTC",
        "balance": "1.01",
        "run_id": 1,
        "run_type": "settlement",
        "movements": [
            {
                "movement_timestamp": "2022-11-04T02:50:16.202915702Z",
                "movement_id": "EFG456",
                "movement_type": "final_settlement",
                "deposit_reference_id": "deposit 123",
                "change": "123.123",
                "source": "deposit 123 sending address",
                "received_address": "deposit 123 received address"
            }
        ],
        "run_timestamp": "2022-11-04T02:51:16.202911633Z"
    }
}
```

After receiving the `initial-balance` message, you will be sent incremental `balance-updated` messages, which show any balance changes to accounts that meet your subscription criteria.

<table><thead><tr><th width="196.33333333333331">Parameter</th><th width="422">Description</th><th>Type</th></tr></thead><tbody><tr><td>participant_code</td><td>The code of the participant that owns the account</td><td>string</td></tr><tr><td>account_group</td><td>The group that the account is a part of</td><td>string</td></tr><tr><td>account_label</td><td>The account label to filter the response by</td><td>string</td></tr><tr><td>account_type</td><td><code>available</code>, <code>collateral</code>, <code>payable</code>, <code>receivable</code> or <code>collateral_deficiency</code></td><td>string</td></tr><tr><td>asset</td><td>The asset code for the specific account, e.g. e₹</td><td>string</td></tr><tr><td>balance</td><td>Updated balance value</td><td>string</td></tr><tr><td>run_id</td><td>A unique ID for the particular run</td><td>string</td></tr><tr><td>run_type</td><td>The type of run</td><td>string</td></tr><tr><td>run_timestamp</td><td>Timestamp when the account balance was updated</td><td>timestamp</td></tr><tr><td>movements[ ]</td><td>An array of movements related to the specific account update<br>Refer to the GET /accounts/:account_id/movements section for field definitions</td><td>array</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ndax.in/v3/private-socket-feed/balances.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.