WebSocket API

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

FilterDescriptionApplicable to Event TypeExample
PackageMove package IDMoveEvent
Publish
TransferObject
DeleteObject
NewObject
{"Package":"<PackageID>"}
ModuleMove module nameMoveEvent
TransferObject
DeleteObject
NewObject
{"Module":"nft"}
MoveEventTypeMove event type defined in the move codeMoveEvent{"MoveEventType":"<PackageID>::nft::MintNFTEvent"}
MoveEventFieldFilter using the data fields in the move event objectMoveEvent{"MoveEventField":{ "path":"/name", "value":"NFT"}}
SenderAddressAddress that started the transactionMoveEvent
Publish
TransferObject
DeleteObject
NewObject
{"SenderAddress": "<SuiAddress>"}
EventTypeType of event described in the Events sectionMoveEvent
Publish
TransferObject
DeleteObject
NewObject
EpochChange
Checkpoint
{"EventType":"Publish"}
ObjectIdObject IDTransferObject
DeleteObject
NewObject
{"ObjectId":"<ObjectID>"}

Operators for combining filters

OperatorDescriptionExample
AndCombine two filters; behaves the same as boolean And operator{"And":parameters]
{
"data": {
"0-0": "And",
}
OrCombine two filters; behaves the same as boolean Or operator{"Or"::parameters]
{
"data": {
"0-0": "And",
}
AllCombine a list of filters; returns true if all filters match the event{"All":parameters]
{
"data": {
"0-0": "And",
"2-0": "All",
"1-0": }
AnyCombine 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 QueryDescriptionParameter Example
AllAll events{"All"}
TransactionEvents emitted from the specified transaction{"Transaction":"<TransactionBlock>"}
MoveModuleEvents emitted from the specified Move module{"MoveModule":{"package":"", "module":"nft"}}
MoveEventMove struct name of the event{"MoveEvent":"::nft::MintNFTEvent"}
EventTypeType of event described in this Events section{"EventType": "NewObject"}
SenderQuery by sender address{"Sender": "<SuiAddress>"}
RecipientQuery by recipient{"Recipient":{"AddressOwner":"<SuiAddress>"}}
ObjectReturn events associated with the given object{"Object":"<ObjectID>"}
TimeRangeReturn 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
}