Coin Streams

Stream token balance changes for a specific Sui address, in real time over WebSocket or SSE.

Overview

Coin streams push a message whenever the monitored address's token balance changes. Perfect for payment confirmation UIs, live balance displays, and treasury monitoring - the streaming counterpart of Coin Webhooks.

Configuration

Create the stream in the dashboard:

Field	Required	Description
Address	Yes	The address to monitor for balance changes
Coin Type	No	Specific coin type to filter (e.g., 0x2::sui::SUI). Leave empty for all coins

Then connect with the Stream ID via WebSocket (recommended) or SSE - see Setup & Connection.

Example Message

Messages arrive with the event name coin:

{
  "id": "12345682_Qr9Mn3wxyz_0x1234abcd_0x2::sui::SUI_-1000000000",
  "event": "coin",
  "data": {
    "activityType": "balance_change",
    "address": "0x1234abcd",
    "coin_type": "0x2::sui::SUI",
    "amount": "-1000000000",
    "txDigest": "Qr9Mn3wxyz",
    "checkpoint": 12345682,
    "timestamp": 1703097700000
  }
}

Payload Fields

Field	Type	Description
data.activityType	string	Always balance_change
data.address	string	The monitored address
data.coin_type	string	The coin type (e.g., 0x2::sui::SUI)
data.amount	string	Balance change amount (string for precision, can be negative)
data.txDigest	string	Transaction digest
data.checkpoint	number	Checkpoint sequence number
data.timestamp	number	Unix timestamp in milliseconds

Note the coin_type field uses snake_case, unlike most other fields.

Understanding Amount Values

The amount field is a string representation of the balance change:

• Positive values: Tokens received (e.g., "1000000000")
• Negative values: Tokens sent (e.g., "-1000000000")
• String format: Preserves precision for large values - parse with BigInt

💡 Token Decimals: Most tokens use 9 decimals. "1000000000" = 1 SUI. Always verify the decimal places for the specific token type.

Use Cases

• Payment systems: Confirm payment receipts the moment they land
• Wallet apps: Live balance updates without polling
• Treasury monitoring: Instant alerts on large movements
• Token distribution: Watch airdrops and vesting payouts in real time

Best Practices

1. Use coin type filters when you only care about specific tokens
2. Handle negative amounts - outgoing transfers have negative amounts
3. Parse as BigInt to avoid precision loss
4. ACK on WebSocket after processing for exactly-once delivery

Next Steps

• Setup & Connection - Authentication, ACKs, reconnection
• Event Streams - Stream smart contract events
• Address Streams - Stream wallet activity
• Object Streams - Stream object mutations