title
Sui Events API

Sui Full nodes support publish / subscribe using JSON-RPC notifications via the WebSocket API. This service allows clients to filter and subscribe to a real-time event stream generated from Move or from the Sui network.

The client can provide an event filter to narrow the scope of events. For each event that matches the filter, a notification with the event data and subscription ID is returned to the client.

Type of events

List of events emitted by the Sui node.

Move event

Move event are emitted from move call, user can define custom events in the move contract.

Attributes : packageId, transactionModule, sender, type, fields, bcs
Example :

{
  "moveEvent": {
    "packageId": "0x0000000000000000000000000000000000000002",
    "transactionModule": "devnet_nft",
    "sender": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
    "type": "0x2::devnet_nft::MintNFTEvent",
    "fields": {
      "creator": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
      "name": "Example NFT",
      "object_id": "0x497913a47dc0028a85f24c70d825991b71c60001"
    },
    "bcs": "SXkTpH3AAoqF8kxw2CWZG3HGAAFwYT9PF64TY/en5yUdqrXFsG9owQtFeGFtcGxlIE5GVA=="
  }
}

Publish

Attributes: sender, packageId
Example:

{
  "publish": {
    "sender": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
    "packageId": "0x2d052c9de3dd02f28ec0f8e4dfdee175a5c597c3"
  }
}

Transfer object

Attributes: packageId, transactionModule, sender, recipient, objectId, version, type
Example:

{
  "transferObject": {
    "packageId": "0x0000000000000000000000000000000000000002",
    "transactionModule": "native",
    "sender": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
    "recipient": {
      "AddressOwner": "0x741a9a7ea380aed286341fcf16176c8653feb667"
    },
    "objectId": "0x591fbb00a6c9676186cb44402040a8350520cbe9",
    "version": 1,
    "type": "Coin"
  }
}

Delete object

Attributes: packageId, transactionModule, sender, objectId
Example:

{
  "deleteObject": {
    "packageId": "0x2d052c9de3dd02f28ec0f8e4dfdee175a5c597c3",
    "transactionModule": "discount_coupon",
    "sender": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
    "objectId": "0xe3a6bc7bf1dba4d17a91724009c461bd69870719"
  }
}

New object

Attributes: packageId, transactionModule, sender, recipient, objectId
Example:

{
  "newObject": {
    "packageId": "0x0000000000000000000000000000000000000002",
    "transactionModule": "devnet_nft",
    "sender": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
    "recipient": {
      "AddressOwner": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1"
    },
    "objectId": "0x497913a47dc0028a85f24c70d825991b71c60001"
  }
}

Epoch change

Value: Epoch Id
Example:

{
  "epochChange": 20
}

Checkpoint

Value: Checkpoint Sequence Number
Example:

{
  "checkpoint": 10
}

Sui event query

Event query criteria

Users can query the full node using EventQuery criteria object to get the exact event relevant to the client.

List of queryable criteria

Query	Description	JSON-RPC Parameter Example
All	All events	{"All"}
Transaction	Events emitted by the given transaction.	{"Transaction":""}
MoveModule	Events emitted in a specified Move module	{"MoveModule":{"package":"0x2", "module":"devnet_nft"}}
MoveEvent	Move struct name of the event	{"MoveEvent":"0x2::event_nft::MintNFTEvent"}
EventType	Type of event described in the Events section	{"EventType": "NewObject"}
Sender	Query by sender address	{"Sender":"0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1"}
Recipient	Query by recipient	{"Recipient":{"AddressOwner":"0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1"}}
Object	Return events associated with the given object	{"Object":"0xe3a6bc7bf1dba4d17a91724009c461bd69870719"}
TimeRange	Return events emitted in [start_time, end_time] interval	{"TimeRange":{"start":, "start":}}

Pagination

The Event Query API provide cursor based pagination to make returning large result sets more efficient. User can provide a cursor parameter to the paginated query to indicate the starting position of the query, the query will return the query result with item size up to the set limit and a next_cursor value will be returned if there are more item. The maximum item size limit is 1000 per query.

Examples

1. Get all event emitted by devnet_nft module in descending time order

Request

curl --location --request POST '127.0.0.1:9000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getEvents",
  "params": [
    {"MoveModule":{"package":"0x2", "module":"devnet_nft"}},
    null,
    null,
    true
  ]
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "data": [
            {
                "timestamp": 1666699837426,
                "txDigest": "cZXsToU6r0Uia6HIAwvr1eMlGsrg6b9+2oYZAskJ0wc=",
                "id": {
                    "txSeq": 1001,
                    "eventSeq": 1,
                },
                "event": {
                    "moveEvent": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "type": "0x2::devnet_nft::MintNFTEvent",
                        "fields": {
                            "creator": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                            "name": "Example NFT",
                            "object_id": "0x2ee80b4a2d203365dfbd68a90a8ad9a0dca19155"
                        },
                        "bcs": "LugLSi0gM2XfvWipCorZoNyhkVX+1JBtcbilg//9jpVnYCe2u4HXzwtFeGFtcGxlIE5GVA=="
                    }
                }
            },
            {
                "timestamp": 1666699837426,
                "txDigest": "cZXsToU6r0Uia6HIAwvr1eMlGsrg6b9+2oYZAskJ0wc=",
                "id": {
                    "txSeq": 1001,
                    "eventSeq": 0,
                },
                "event": {
                    "newObject": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "recipient": {
                            "AddressOwner": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf"
                        },
                        "objectId": "0x2ee80b4a2d203365dfbd68a90a8ad9a0dca19155"
                    }
                }
            },
            {
                "timestamp": 1666698739180,
                "txDigest": "WF2V6FM6y/kpAgRqzsQmR/osy4pmTgVVbE6qvSJxWh4=",
                "id": {
                    "txSeq": 998,
                    "eventSeq": 1,
                },
                "event": {
                    "moveEvent": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "type": "0x2::devnet_nft::MintNFTEvent",
                        "fields": {
                            "creator": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                            "name": "Example NFT",
                            "object_id": "0xd5657cf6acaba958c5b01ec0516f4f0dac77c7d2"
                        },
                        "bcs": "1WV89qyrqVjFsB7AUW9PDax3x9L+1JBtcbilg//9jpVnYCe2u4HXzwtFeGFtcGxlIE5GVA=="
                    }
                }
            },
            {
                "timestamp": 1666698739180,
                "txDigest": "WF2V6FM6y/kpAgRqzsQmR/osy4pmTgVVbE6qvSJxWh4=",
                "id": {
                    "txSeq": 998,
                    "eventSeq": 0,
                },
                "event": {
                    "newObject": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "recipient": {
                            "AddressOwner": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf"
                        },
                        "objectId": "0xd5657cf6acaba958c5b01ec0516f4f0dac77c7d2"
                    }
                }
            }
        ],
        "nextCursor": null
    },
    "id": 1
}

2. Get all `0x2::devnet_nft::MintNFTEvent`

Request

curl --location --request POST '127.0.0.1:9000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getEvents",
  "params": [
    {"MoveEvent":"0x2::devnet_nft::MintNFTEvent"},
    null,
    null,
    "Ascending"
  ]
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "data": [
            {
                "timestamp": 1666699837426,
                "txDigest": "cZXsToU6r0Uia6HIAwvr1eMlGsrg6b9+2oYZAskJ0wc=",
                "id": {
                    "txSeq": 1001,
                    "eventSeq": 1,
                },
                "event": {
                    "moveEvent": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "type": "0x2::devnet_nft::MintNFTEvent",
                        "fields": {
                            "creator": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                            "name": "Example NFT",
                            "object_id": "0x2ee80b4a2d203365dfbd68a90a8ad9a0dca19155"
                        },
                        "bcs": "LugLSi0gM2XfvWipCorZoNyhkVX+1JBtcbilg//9jpVnYCe2u4HXzwtFeGFtcGxlIE5GVA=="
                    }
                }
            },
            {
                "timestamp": 1666698739180,
                "txDigest": "WF2V6FM6y/kpAgRqzsQmR/osy4pmTgVVbE6qvSJxWh4=",
                "id": {
                    "txSeq": 998,
                    "eventSeq": 1,
                },
                "event": {
                    "moveEvent": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "type": "0x2::devnet_nft::MintNFTEvent",
                        "fields": {
                            "creator": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                            "name": "Example NFT",
                            "object_id": "0xd5657cf6acaba958c5b01ec0516f4f0dac77c7d2"
                        },
                        "bcs": "1WV89qyrqVjFsB7AUW9PDax3x9L+1JBtcbilg//9jpVnYCe2u4HXzwtFeGFtcGxlIE5GVA=="
                    }
                }
            }
        ],
        "nextCursor": null
    },
    "id": 1
}

3. Get all event 2 items per paged, in descending time order

Request

curl --location --request POST '127.0.0.1:9000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getEvents",
  "params": [
    "All",
    null,
    2,
    "Ascending"
  ]
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "data": [
            {
                "timestamp": 1666698739180,
                "txDigest": "WF2V6FM6y/kpAgRqzsQmR/osy4pmTgVVbE6qvSJxWh4=",
                "id": {
                    "txSeq": 998,
                    "eventSeq": 0,
                },
                "event": {
                    "newObject": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "recipient": {
                            "AddressOwner": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf"
                        },
                        "objectId": "0xd5657cf6acaba958c5b01ec0516f4f0dac77c7d2"
                    }
                }
            },
            {
                "timestamp": 1666698739180,
                "txDigest": "WF2V6FM6y/kpAgRqzsQmR/osy4pmTgVVbE6qvSJxWh4=",
                "id": {
                    "txSeq": 998,
                    "eventSeq": 1,
                },
                "event": {
                    "moveEvent": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "type": "0x2::devnet_nft::MintNFTEvent",
                        "fields": {
                            "creator": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                            "name": "Example NFT",
                            "object_id": "0xd5657cf6acaba958c5b01ec0516f4f0dac77c7d2"
                        },
                        "bcs": "1WV89qyrqVjFsB7AUW9PDax3x9L+1JBtcbilg//9jpVnYCe2u4HXzwtFeGFtcGxlIE5GVA=="
                    }
                }
            }
        ],
        "nextCursor": 3
    },
    "id": 1
}

Subscribe to Sui events

Sui full node supports publish / subscribe using JSON-RPC notifications via the WebSocket API. This service allows clients to filter and subscribe to a real-time event stream generated from Move or from the Sui network.

The client can provide an event filter to narrow the scope of the event subscription. For each event that matches the filter, a notification with the event data and subscription ID is returned to the client.

Event filters

Sui event publish / subscribe uses EventFilter to enable fine control of the event subscription stream; the client can subscribe to the event stream using one or a combination of event attribute filters to get the exact event relevant to the client.

List of filterable attributes

Filter	Description	Applicable to Event Type	JSON-RPC Parameter Example
Package	Move package ID	MoveEvent Publish TransferObject DeleteObject NewObject	`{"Package":"0x2"}`
Module	Move module name	MoveEvent TransferObject DeleteObject NewObject	`{"Module":"devnet_nft"}`
MoveEventType	Move event type defined in the move code	MoveEvent	`{"MoveEventType":"0x2::devnet_nft::MintNFTEvent"}`
MoveEventField	Filter using the data fields in the move event object	MoveEvent	`{"MoveEventField":{ "path":"/name", "value":"Example NFT"}}`
SenderAddress	Address that started the transaction	MoveEvent Publish TransferObject DeleteObject NewObject	`{"SenderAddress": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1"}`
EventType	Type of event described in the Events section	MoveEvent Publish TransferObject DeleteObject NewObject EpochChange Checkpoint	`{"EventType":"Publish"}`
ObjectId	Object ID	TransferObject DeleteObject NewObject	`{"ObjectId":"0xe3a6bc7bf1dba4d17a91724009c461bd69870719"}`

Combining filters

We provide a few operators for combining filters:

Operator	Description	z JSON-RPC Parameter Example
And	Combine two filters; behaves the same as boolean And operator	`{"And":[{"Package":"0x2"}, {"Module":"devnet_nft"}]}`
Or	Combine two filters; behaves the same as boolean Or operator	`{"Or":[{"Package":"0x2"}, {"Package":"0x1"}]}`
All	Combine a list of filters; returns true if all filters match the event	`{"All":[{"EventType":"MoveEvent"}, {"Package":"0x2"}, {"Module":"devnet_nft"}]}`
Any	Combine a list of filters; returns true if any filter matches the event	`{"Any":[{"EventType":"MoveEvent"}, {"EventType":"TransferObject"}, {"EventType":"DeleteObject"}]}`

Examples

Subscribe

Here is an example of subscribing to a stream of MoveEvent emitted by the 0x2::devnet_nft package, which is created by the Sui CLI client create-example-nft command:

>> {"jsonrpc":"2.0", "id": 1, "method": "sui_subscribeEvent", "params": [{"All":[{"EventType":"MoveEvent"}, {"Package":"0x2"}, {"Module":"devnet_nft"}]}]}
<< {"jsonrpc":"2.0","result":3121662727959200,"id":1}

Unsubscribe

To unsubscribe from this stream, use:

>> {"jsonrpc":"2.0", "id": 1, "method": "sui_unsubscribeEvent", "params": [3121662727959200]}
<< {"jsonrpc":"2.0","result":true,"id":1}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

event_api.md

event_api.md

Type of events

Move event

Publish

Transfer object

Delete object

New object

Epoch change

Checkpoint

Sui event query

Event query criteria

List of queryable criteria

Pagination

Examples

1. Get all event emitted by devnet_nft module in descending time order

2. Get all `0x2::devnet_nft::MintNFTEvent`

3. Get all event 2 items per paged, in descending time order

Subscribe to Sui events

Event filters

List of filterable attributes

Combining filters

Examples

Subscribe

Unsubscribe

Files

event_api.md

Latest commit

History

event_api.md

File metadata and controls

Type of events

Move event

Publish

Transfer object

Delete object

New object

Epoch change

Checkpoint

Sui event query

Event query criteria

List of queryable criteria

Pagination

Examples

1. Get all event emitted by devnet_nft module in descending time order

2. Get all 0x2::devnet_nft::MintNFTEvent

3. Get all event 2 items per paged, in descending time order

Subscribe to Sui events

Event filters

List of filterable attributes

Combining filters

Examples

Subscribe

Unsubscribe

2. Get all `0x2::devnet_nft::MintNFTEvent`