Balances Data Stream

Streams Cross-chain Account Balances

AGENT ID

steward

PROVIDES

streams

NETWORKS

The Balances Data Stream provides real-time account balance data for more than 500 assets across Polkadot and Kusama networks. It uses Server-Sent Events (SSE) to deliver account balance data.

Balances Server-Sent Events

Endpoint: /sse/steward/balances

Query String Parameters

Parameter	Type	Required	Description
`account`	string \| string[]	✓	Account(s) to monitor.

Acceptable formats:

SS58-encoded account address
Substrate public key (32-byte hex string)
EVM address (20-byte hex string)

You can provide a single account as a string or an array of 1–5 accounts. Each account in the array will receive balance snapshots and live updates.

Example (single account)

{
  "account": "13b6hRRYPHTxFzs9prvL2YGHQepvd4YhdDb9Tc7khySp3hMN"
}

Example (multiple accounts, mixed formats)

{
  "account": [
    "13b6hRRYPHTxFzs9prvL2YGHQepvd4YhdDb9Tc7khySp3hMN",
    "0x5fB8cB2f8F7c7d8f4C3D2bA1e0aB1C2d3E4F5678",
    "0x8ad5b6a49624ca22b21ba52c896d23dafd8269ffa315e16437e092f71cd92e56"
  ]
}

Protocol

When a client connects to the SSE endpoint, it streams events in the following sequence:

status event — indicates the snapshot discovery status of the account.
balances events — emitted as balance snapshots or live balance updates.
synced event — signals that all known balances for an account have been streamed and the snapshot is complete.
balances updates (optional) — emitted whenever balances change after initial snapshot.

After the synced event:

Clients may close the stream if only an initial snapshot is needed, or
Keep the connection open to receive live updates as balances change.

Status Event

Indicates the discovery state of a requested account.

Field	Description
`status`	Current status of the account in the balance discovery process.
`accountId`	The account identifier as provided in the SSE request.
`publicKey`	Substrate public key or EVM address.

Possible Status Values

Status	Description
`discovered`	A full balance snapshot for the account is already available.
`discovery-in-progress`	The balance discovery process is currently running.
`discovery-enqueued`	The account has been added to the discovery queue.
`max-addresses-enqueued-reached`	The per-client queue limit (10 accounts) has been reached. The account was not added to the queue; try again later.

Example:

{ "status": "discovered", "accountId": "13b6...hMN", "publicKey": "0x7279..." }

Balances Event

Emitted when an account balance snapshot is returned or when a live balance update occurs.

Field	Description
`origin`	Either `"snapshot"` (last known balance) or `"update"` (balance change).
`accountId`	SS58-encoded account address, always transformed to the SS58 format of the chain of the asset, or EVM address.
`publicKey`	Substrate public key or EVM address.
`balance`	Total transferable balance as a string.
`chainId`	Network URN identifying the chain where the balance is held.
`assetId`	Asset identifier on the network.
`symbol`	Token symbol (e.g., DOT, SUI, USDT).
`decimals`	Asset decimal precision.

The balance value represents the total transferable amount. For Substrate-based accounts, it is calculated as free balance - frozen balance. For ERC-20 tokens, it reflects the full balance returned by the token contract.

Note

Account balance snapshots are continuously updated as new on-chain events occur that affect the balance. Keeping the SSE stream open allows clients to receive these live updates automatically.

Example:

{
  "origin": "snapshot",
  "accountId": "13b6...hMN",
  "publicKey": "0x7279...",
  "balance": "1975249560950",
  "chainId": "urn:ocn:polkadot:2034",
  "assetId": 1000753,
  "symbol": "SUI",
  "decimals": 9
}

{
  "origin": "update",
  "accountId": "13b6...hMN",
  "publicKey": "0x7279...",
  "balance": "2522858266055",
  "chainId": "urn:ocn:polkadot:2034",
  "assetId": 1000753,
  "symbol": "SUI",
  "decimals": 9
}

Synced Event

Emitted when all known balances for an account have been streamed and the account snapshot is complete.

Field	Description
`accountId`	Same value as publicKey
`publicKey`	Substrate public key or EVM address.

Example:

{
  "accountId": "0x7279...",
  "publicKey": "0x7279..."
}

Examples

Client Library

For usage example with the client library, please browse our example on GitHub

Browser Usage

Stream balances in browser

const account = "12ZuLmUfn7M7zAhKA585c7nzypPB1Xfj1u8bRoEFAed4c5tv";

const source = new EventSource(
  `https://api.ocelloids.net/sse/steward/balances?account=${account}`
);

source.onopen = () => console.log("Connection open");

source.onerror = (err) => {
  console.error("SSE error:", err);
  source.close();
};

source.addEventListener("balance", (msg) => {
  console.log("balance:", JSON.parse(msg.data));
});

source.addEventListener("status", (msg) => {
  console.log("status:", JSON.parse(msg.data));
});

source.addEventListener("synced", (msg) => {
  console.log("synced:", JSON.parse(msg.data));
});