Subscribe to JSON-RPC Real-Time Events
Shinami supports publish / subscribe using JSON-RPC notifications via our 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 provides an event filter to limit the scope of events.
WebSocket Rate Limit:
10 connections and 10 subscriptions per Shinami access key.
Connecting to WebSockets
You can connect to our WebSocket service using a command line tool such as wscat or one of the Sui SDKs such as the TypeScript SDK. Below are some examples on how to connect using these approaches:
# connect to the service
% wscat -c wss://api.shinami.com/node/v1/<<apiKey>>
# create a subscription to see events for transferObjects
> {"jsonrpc":"2.0", "id":1, "method": "suix_subscribeEvent", "params": [{"All":[{"EventType":"MoveEvent"}, {"Package":"<PACKAGE-MODULE-ID>"}, {"Module":"nft"}]}]}
# will return to you a subscription_id
< {"jsonrpc":"2.0","result":<subscription_id>,"id":1}
# unsubscribe from the previously created subscription
> {"jsonrpc":"2.0", "id":1, "method": "suix_unsubscribeEvent", "params": [<subscription_id>]}
# will return to you whether the unsubscribe was successful.
< "jsonrpc":"2.0","result":true,"id":1}
import { JsonRpcProvider } from '@mysten/sui.js';
const provider = new JsonRpcProvider("wss://sui-devnet.shinami.com/ws/v1/<<apiKey>>");
// create a subscription to see events for transferObjects
const subscriptionId = await provider.subscribeEvent(
{ EventType: 'TransferObject' },
(event: SuiEventEnvelope) => {
// handle subscription notification message here. This function is called once per subscription message.
}
);
// to unsubscribe, call 'sui_unsubscribeEvent' with params: [ subscriptionId ]
const subFoundAndRemoved = await provider.unsubscribeEvent(subscriptionId);
suix_subscribeEvent
Description
Subscribe to a Sui event stream and use EventFilter
for the filter criteria. For each event that matches the filter, a notification with the event data and subscription ID is returned to the client.
Params
filter
:<EventFilter>
- enable fine control of the event subscription stream using one or a combination of event attribute filters, as detailed in the Event filters section
Example
The following example demonstrates how to subscribe to Move events (MoveEvent
) that a <PACKAGE-ID>::nft
package emits:
>> {"jsonrpc":"2.0", "id": 1, "method": "suix_subscribeEvent", "params": [{"All":[{"EventType":"MoveEvent"}, {"Package":"<PACKAGE-MODULE-ID>"}, {"Module":"nft"}]}]}
<< {"jsonrpc":"2.0","result":3121662727959200,"id":1}
Result
SuiEvent
:<Event>
suix_unsubscribeEvent
Description
Unsubscribe from a Sui event stream.
Example
Unsubscribe from the event stream used previously in the suix_subscribeEvent
example:
>> {"jsonrpc":"2.0", "id": 1, "method": "suix_unsubscribeEvent", "params": [3121662727959200]}
<< {"jsonrpc":"2.0","result":true,"id":1}
suix_subscribeTransaction
Description
Subscribe to a Sui transaction stream and use TransactionFilter
for the filter criteria.
Params
filter
:<TransactionFilter>
Result
SuiTransactionBlockEffects
:<TransactionBlockEffects>
suix_unsubscribeTransaction
Description
Unsubscribe from a Sui transaction stream.
Params
subscription_id
: the ID of the subscription you are unsubscribing to
Example
>> {"jsonrpc":"2.0", "id": 1, "method": "suix_unsubscribeTransaction", "params": [subscription_id]}
<< {"jsonrpc":"2.0","result":true,"id":1}
Event filters
You can use EventFilter
to filter the events included in your subscription to the event stream. EventFilter
supports filtering on one attribute or a combination of attributes.
Filterable attributes
Filter | Description | Applicable to Event Type | Example |
---|---|---|---|
Package | Move package ID | MoveEvent Publish TransferObject DeleteObject NewObject | {"Package":"<PackageID>"} |
Module | Move module name | MoveEvent TransferObject DeleteObject NewObject | {"Module":"nft"} |
MoveEventType | Move event type defined in the move code | MoveEvent | {"MoveEventType":"<PackageID>::nft::MintNFTEvent"} |
MoveEventField | Filter using the data fields in the move event object | MoveEvent | {"MoveEventField":{ "path":"/name", "value":"NFT"}} |
SenderAddress | Address that started the transaction | MoveEvent Publish TransferObject DeleteObject NewObject | {"SenderAddress": "<SuiAddress>"} |
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":"<ObjectID>"} |
Operators for combining filters
Operator | Description | Example |
---|---|---|
And | Combine two filters; behaves the same as boolean And operator | {"And":parameters] { "data": { "0-0": "And", } |
Or | Combine two filters; behaves the same as boolean Or operator | {"Or"::parameters] { "data": { "0-0": "And", } |
All | Combine a list of filters; returns true if all filters match the event | {"All":parameters] { "data": { "0-0": "And", "2-0": "All", "1-0": } |
Any | Combine a list of filters; returns true if any filter matches the event | {"Any":parameters] { "data": { "0-0": "And", "2-0": "All", "1-0": "Or", "3-0":} |
Event query criteria
You can use the EventQuery
criteria object to query a Sui node and retrieve events that match query criteria.
Event Query | Description | Parameter Example |
---|---|---|
All | All events | {"All"} |
Transaction | Events emitted from the specified transaction | {"Transaction":"<TransactionBlock>"} |
MoveModule | Events emitted from the specified Move module | {"MoveModule":{"package":"", "module":"nft"}} |
MoveEvent | Move struct name of the event | {"MoveEvent":"::nft::MintNFTEvent"} |
EventType | Type of event described in this Events section | {"EventType": "NewObject"} |
Sender | Query by sender address | {"Sender": "<SuiAddress>"} |
Recipient | Query by recipient | {"Recipient":{"AddressOwner":"<SuiAddress>"}} |
Object | Return events associated with the given object | {"Object":"<ObjectID>"} |
TimeRange | Return events emitted within a time range | {"TimeRange":{"startTime":1669039504014, "endTime":1669039604014}} |
Event Types
List of events emitted by the Sui node.
Move Event
Move calls emit Move events. You can define custom events in Move contracts.
Attributes: packageId
, transactionModule
, sender
, type
, fields
, bcs
{
"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
Publish events occur when you publish a package to the network.
Attributes: sender
, packageId
{
"publish": {
"sender": "0x008e9c621f4fdb210b873aab59a1e5bf32ddb1d33ee85eb069b348c234465106",
"packageId": "0x5f01a29887a1d95e5b548b616da63b0ce07d816e89ef7b9a382177b4422bbaa2"
}
}
Transfer object
Transfer object events occur when you transfer an object from one address to another.
Attributes: packageId
, transactionModule
, sender
, recipient
, objectId
, version
, type
{
"transferObject": {
"packageId": "0x0000000000000000000000000000000000000000000000000000000000000002",
"transactionModule": "native",
"sender": "0x008e9c621f4fdb210b873aab59a1e5bf32ddb1d33ee85eb069b348c234465106",
"recipient": {
"AddressOwner": "0xa3c00467938b392a12355397bdd3d319cea5c9b8f4fc9c51b46b8e15a807f030"
},
"objectId": "0x727b37454ab13d5c1dbb22e8741bff72b145d1e660f71b275c01f24e7860e5e5",
"version": 1,
"type": "Coin"
}
}
Delete object
Delete object events occur when you delete an object.
Attributes: packageId
, transactionModule
, sender
, objectId
{
"deleteObject": {
"packageId": "0x5f01a29887a1d95e5b548b616da63b0ce07d816e89ef7b9a382177b4422bbaa2",
"transactionModule": "discount_coupon",
"sender": "0x008e9c621f4fdb210b873aab59a1e5bf32ddb1d33ee85eb069b348c234465106",
"objectId": "0x727b37454ab13d5c1dbb22e8741bff72b145d1e660f71b275c01f24e7860e5e5"
}
}
New object
New object events occur when you create an object on the network.
Attributes: packageId
, transactionModule
, sender
, recipient
, objectId
{
"newObject": {
"packageId": "<PACKAGE-ID>",
"transactionModule": "nft",
"sender": "0x008e9c621f4fdb210b873aab59a1e5bf32ddb1d33ee85eb069b348c234465106",
"recipient": {
"AddressOwner": "0xa3c00467938b392a12355397bdd3d319cea5c9b8f4fc9c51b46b8e15a807f030"
},
"objectId": "0x727b37454ab13d5c1dbb22e8741bff72b145d1e660f71b275c01f24e7860e5e5"
}
}
Epoch change
Epoch change events occur when an epoch ends and a new epoch starts.
Attributes: None. The event includes an Epoch ID associated with the epochChange
{
"epochChange": 20
}
Checkpoint
A checkpoint event occurs for each checkpoint.
Attributes: None. The event includes the Checkpoint sequence number associated with the checkpoint
{
"checkpoint": 10
}