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.

🚧

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 such as the TypeScript SDK. Below are some examples on how to connect using these approaches:

# connect to the service
% wscat -c wss://node.shinami.com/ws/v1/<<apiKey>>

# create a subscription to see events for transferObjects
> {"jsonrpc":"2.0", "id":1, "method": "sui_subscribeEvent", "params": [{"All":[{"EventType":"TransferObject"}]}]}
# 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": "sui_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);

📘

Note:

Shinami will support two URL formats for our WebSocket API.

Network Agnostic: network is determined by the Shinami access key

  • node.shinami.com

Network Specific: Shinami access key network should match the network in the URL

  • sui-devnet.shinami.com
  • sui-testnet.shinami.com

sui_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
Subscribe to a MoveEvent stream 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}

Result

  • SuiEventEnvelope : <EventEnvelope>

sui_unsubscribeEvent

Description
Unsubscribe from a Sui event stream.

Example
Unsubscribe from the event stream used previously in the sui_subscribeEvent example:

>> {"jsonrpc":"2.0", "id": 1, "method": "sui_unsubscribeEvent", "params": [3121662727959200]}
<< {"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":"0x2"}
ModuleMove module nameMoveEvent
TransferObject
DeleteObject
NewObject
{"Module":"devnet_nft"}
MoveEventTypeMove event type defined in the move codeMoveEvent{"MoveEventType":"0x2::devnet_nft::MintNFTEvent"}
MoveEventFieldFilter using the data fields in the move event objectMoveEvent{"MoveEventField":{ "path":"/name", "value":"Example NFT"}}
SenderAddressAddress that started the transactionMoveEvent
Publish
TransferObject
DeleteObject
NewObject
{"SenderAddress": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1"}
EventTypeType of event described in the Events sectionMoveEvent
Publish
TransferObject
DeleteObject
NewObject
EpochChange
Checkpoint
{"EventType":"Publish"}

Operators for combining filters

OperatorDescriptionExample
AndCombine two filters; behaves the same as boolean And operator{"And":[{"Package":"0x2"}, {"Module":"devnet_nft"}]}
OrCombine two filters; behaves the same as boolean Or operator{"Or":[{"Package":"0x2"}, {"Package":"0x1"}]}
AllCombine a list of filters; returns true if all filters match the event{"All":[{"EventType":"MoveEvent"}, {"Package":"0x2"}, {"Module":"devnet_nft"}]}
AnyCombine a list of filters; returns true if any filter matches the event{"Any":[{"EventType":"MoveEvent"}, {"EventType":"TransferObject"}, {"EventType":"DeleteObject"}]}

Events

List of events emitted by the Sui node.

Move Event

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

Attributes: sender, packageId

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

Transfer object

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

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

Delete object

Attributes: packageId, transactionModule, sender, objectId

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

New object

Attributes: packageId, transactionModule, sender, recipient, objectId

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

Epoch change

Value: Epoch ID

{
  "epochChange": 20
}

Checkpoint

Value: Checkpoint Sequence Number

{
  "checkpoint": 10
}