# 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>