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
}