Subscription Filters

By default, the balance subscription returns balances for all accounts you can access — both in the initial-balance snapshot and in ongoing balance-updated messages. To narrow that stream, pass a filter object inside the message body when you subscribe.

Filters apply to both the snapshot and the incremental updates: you only receive records for accounts that match every filter you set.

Where the filter goes

The filter is a nested object inside the body of your subscribe message:

{
  "messageType": "subscribe",
  "topic": "balances",
  "key": "API_PUBLIC_KEY",
  "passphrase": "API_PASSPHRASE",
  "timestamp": "1720000000",
  "signature": "base64_encoded_hmac",
  "body": {
    "filter": {
      "account_owner": "ABC123",
      "account_group": "00SCXM",
      "account_type": "available",
      "asset": "USD"
    }
  }
}

An empty filter ("body": { "filter": {} }) returns all accessible accounts.

Available filters

All filters are optional. Combining multiple filters narrows the results (they are ANDed together).

Filter	Type	Description
`account_owner`	string	The participant code for the specific participant you want updates for
`account_group`	string	The group that you want updates for
`account_type`	string	Restrict to a single account type: `available`, `collateral`, `payable`, `receivable`, or `collateral_deficiency`
`asset`	string	The asset code you would like updates for (e.g. `USD`, `BTC`)

Examples

All USD balances for one participant:

{ 
  "filter": {     
    "account_owner": "ABC123",     
    "asset": "USD" 
  }
}

Only available balances across everything you can access:

{ 
  "filter": { 
    "account_type": "available" 
  } 
}

A single group's collateral balances:

{ 
  "filter": { 
    "account_group": "00SCXM", 
    "account_type": "collateral" 
  } 
}

Important notes

⚠️
The filter is part of the signed body. If you change any filter value, you must recompute the signature over the new body. The body you sign must be byte-for-byte identical to the body you send. See Authentication.

Filters are set at subscribe time. To change your filter, resubscribe with a new (re-signed) subscribe message.
Filters shape both phases. The same criteria govern the initial-balance snapshot and every subsequent balance-updated message — so if an account is filtered out, you will neither see it in the snapshot nor receive its updates.

Next steps

Initial Subscription — the subscribe request and snapshot
Balance Updates — the incremental update messages
Authentication — re-signing when the filter changes

Where the filter goes

Available filters

Examples

Important notes

The filter is part of the signed body. If you change any filter value, you must recompute the signature over the new body. The body you sign must be byte-for-byte identical to the body you send. See Authentication.

Next steps

The filter is part of the signed `body`. If you change any filter value, you must recompute the `signature` over the new `body`. The `body` you sign must be byte-for-byte identical to the `body` you send. See Authentication.