Balances

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

Initial Subscription

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

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

Subscription Filters

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

Parameter	Description	Type
filter{}	A filter object used to specify account characteristics	object

The filter{} object can include:

Parameter	Description	Type
account_owner	The participant code for the specific participant you want updates for	string
account_group	The group that you want updates for	string
account_type	The type that you want updates for - available, collateral, payable, receivable or collateral_deficiency	string
asset	The asset code you would like updates for	string

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.

Parameter	Description	Type
account_id	Unique ID of the specific account	string
participant_code	The code of the participant that owns the account	string
account_group	The group that the account is a part of	string
account_label	The account label to filter the response by	string
account_type	available, collateral, payable, receivable or collateral_deficiency	string
asset	The asset code for the specific account, e.g. e₹	string
balance	The balance in the account	string
run_id	A unique ID for the particular run	int
run_type	The type of run	string

Balance Update

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.

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