Object Streams

Stream changes to specific on-chain objects, in real time over WebSocket or SSE.

Overview

Object streams push a message whenever a specific object is created, modified, transferred, or deleted. Ideal for tracking NFTs, shared objects like AMM pools, or any other Sui object - the streaming counterpart of Object Webhooks.

Configuration

Create the stream in the dashboard:

Field	Required	Description
Object ID	Yes	The object ID to monitor

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

Example Message

Messages arrive with the event name object:

{
  "id": "12345684_Lm4Np8qrst_0x5678efgh_output_mutated",
  "event": "object",
  "data": {
    "activityType": "object_change",
    "object_id": "0x5678efgh",
    "transactionDirection": "output",
    "writeKind": "mutated",
    "owner": "0x1234abcd",
    "previousOwner": "0x9876fedc",
    "txDigest": "Lm4Np8qrst",
    "checkpoint": 12345684,
    "timestamp": 1703097750000
  }
}

Payload Fields

Field	Type	Description
data.activityType	string	Always object_change
data.object_id	string	The monitored object ID
data.transactionDirection	input | output	Whether object was input or output of tx
data.writeKind	string	How the object was modified (see below)
data.owner	string | null	Current/new owner address
data.previousOwner	string | null	Previous owner (if ownership changed)
data.txDigest	string	Transaction digest
data.checkpoint	number	Checkpoint sequence number
data.timestamp	number	Unix timestamp in milliseconds

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

Write Kinds

The writeKind field indicates how the object was modified:

Write Kind	Description
created	Object was created in this transaction
mutated	Object was modified (fields changed)
deleted	Object was permanently deleted
wrapped	Object was wrapped inside another object
unwrapped	Object was unwrapped from another object
unwrapped_then_deleted	Object was unwrapped and then deleted

Transaction Direction

• input: The object was read or consumed by the transaction
• output: The object was created or modified by the transaction

Use Cases

• NFT tracking: Live ownership changes for specific NFTs
• DeFi monitoring: Watch AMM pool state changes as they happen
• Gaming: Track item modifications and transfers in real time
• Auditing: Stream mutations of critical shared or admin objects

Best Practices

1. Handle all write kinds - different kinds may require different handling
2. Compare owner and previousOwner to detect transfers
3. Expect volume on shared objects - anyone can mutate them, so they change frequently
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
• Coin Streams - Stream balance changes