Service Nearing End of LifeThis service may be fully removed by Mysten any day now. Deprecation was announced in the testnet-v1.28.2 release notes on July 2, 2024. Mysten is working on a new streaming subscription API as a part of the new gRPC API (which will eventually replace the JSON-RPC API). This streaming service has a tentative GA of Sept 2025. !We cannot guarantee that Mysten will support the current Websocket API until the new service is in GA so we advise against using it!
  • For the JSON_RPC API, the suix_queryEvents and suix_queryTransactionBlocks methods will still be supported moving forward (of course, this is a polling and not a listening approach).
  • Removal is expected to follow standard procedure, meaning it would leave Testnet first and then Mainnet a week or two later.

​
Overview

This service allows clients to subscribe to real-time event streams of transactions and events generated by the Sui network.

​
Authentication, Connection and Subscription Limits, and Error Handling

Authentication See our Authentication and API Keys guide, which includes guidance on how to assign the maximum number of WebSocket Service connections and subscriptions an API key is allowed. The number you set for a key applies to both. Region URL and Sui network table You’ll need to make sure you use the region URL you want, along with a Node Service API access key created in that region.
Region nameLocationNetworks offeredService URL (same URL for all networks offered)Only works with API keys made in
US East - us1Eastern United StatesTestnet, Mainnetwss://api.us1.shinami.com/sui/node/v1US East - us1
Tokyo - apac1Tokyo, JapanMainnetwss://api.apac1.shinami.com/sui/node/v1Tokyo - apac1
Connection and Subscription limits If you are at your connection limit and try to open another, you will get a HTTP 429. If you are at your subscription limit and try to open another, you will get a JSON-RPC code -31011. Error Handling See our Error Reference for guidance on the errors you may receive from our services, including a section on errors specific to the WebSocket API.

​
Connecting to our WebSocket Service

Below is an example of connecting to our WebSocket service, subscribing to an event stream, and then unsubscribing. The examples use the command line tool wscat, the Shinami Clients SDK, and the Mysten Rust SDK. Replace all instances of {{name}} with the actual value for that name 
# connect to the service
% wscat -c wss://api.us1.shinami.com/sui/node/v1/{{nodeAccessKey}}

# create a subscription to see events for transactions sent to a given Move package
>  { "jsonrpc":"2.0", "id":1, "method":"suix_subscribeEvent", "params":[{"Package":"{{packageId}}"}]}
# will return to you a subscription_id
< {"jsonrpc":"2.0","result":<subscription_id>,"id":1}
# e.g. {"jsonrpc":"2.0","result":2861815076633913,"id":1}

# unsubscribe from the previously created subscription
> {"jsonrpc":"2.0", "id":1, "method": "suix_unsubscribeEvent", "params": [{{subscription_id}}]} # e.g. {"jsonrpc":"2.0", "id":1, "method": "suix_unsubscribeEvent", "params": [2861815076633913]}
# will return to you whether the unsubscribe was successful.
< "jsonrpc":"2.0","result":true,"id":1}

​
Methods

​
(deprecated) suix_subscribeEvent

BE PREPARED:Active Websocket connections will be broken when our Fullnodes restart (due to regular protocol upgrades, auto-restarts due to a health issue, etc). Make sure that you have a way to handle a broken connection and reconnect.
Description
Subscribe to a Sui event stream that matches a provided filter. For each event that matches the filter, a notification with the event data and subscription ID is returned to the client. Deprecated. See notice attop of page. Params
  • filter : SuiEventFilter - enables fine control of the event subscription stream using one or a combination of event attribute filters, as detailed in the Event filters section
  • Shinami TypeScript SDK only:
    • onMessage: Function of type (SuiEvent) => void to be called when a message is received in the event stream.
Example Request Template This example uses our US East - us1 region URL since it is currently the only region where we offer Testnet. To send to another region, see the top of this page. The examples use the command line tool wscat, the Shinami Clients SDK, and the Mysten Rust SDK. Replace all instances of {{name}} with the actual value for that name 
# connect to the service
% wscat -c wss://api.us1.shinami.com/sui/node/v1/{{nodeAccessKey}}

# create a subscription to see events for transactions sent to a given Move package
>  { "jsonrpc":"2.0", "id":1, "method": "suix_subscribeEvent", "params": [{"Package":"{{packageId}}"}]}
Example Response 
{
    "jsonrpc":"2.0",
    "result": <subscription_id>, // e.g. 2861815076633913
    "id":1
}
Response Data
  • wscat
  • Shinami TypeScript SDK
    • A function with no parameters that returns a boolean. Call this to unsubscribe from the subscription you just created. Returns true when the un-subscription was successful.
  • Mysten Rust SDK
Event Stream Data Type
  • SuiEvent and the subscription id for this event stream.
Event Stream Example Payload 
{
    "jsonrpc":"2.0",
    "method":"suix_subscribeEvent",
    "params":{
        "subscription":498694087448692,
        "result":{
            "id":{
                "txDigest":"5VrUNde9D6VzHCw4jeimbhhWN1YXEFR8APqEsPWSTmGT",
                "eventSeq":"0"
            },
            "packageId":"0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66",
            "transactionModule":"spot_dex",
            "sender":"0x25171ad6a67b8c56de8935350e1531c0d3b2fbf1d9635a4ae7540db991c855ed",
            "type":"0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66::spot_dex::SwapEvent<0x2::sui::SUI>",
            "parsedJson":{
                "amount_in":"24007854747",
                "amount_out":"9510199",
                "pool_id":"0x5af4976b871fa1813362f352fa4cada3883a96191bb7212db1bd5d13685ae305",
                "reserve_x":"279134708847",
                "reserve_y":"703743451694313",
                "user":"0x25171ad6a67b8c56de8935350e1531c0d3b2fbf1d9635a4ae7540db991c855ed"
            },
            "bcs":"YLFPB51Fk3NvkyotqiwnjZ3KnoKXtUBNwJtbAAh4a6szzs2WKLVHYYjzCuWjXwXonsSJrMht2fdfgzZQCYD5nZH68soTTX9kp9yprRmfD4f2RNtFD5L3J2B26cXdMnePuSf",
            "timestampMs":"1698078843950"
        }
    }
}

​
(deprecated) suix_unsubscribeEvent

Description
Unsubscribe from a Sui event stream. Deprecated. See notice attop of page. Params
  • wscat only
    • subscription_id: the ID of the subscription you are unsubscribing to
Example Request Template The following example demonstrates how to unsubscribe from the event stream subscribed to in the suix_subscribeEvent example. The examples use the command line tool wscat and the Shinami Clients SDK. Replace all instances of {{name}} with the actual value for that name 
{"jsonrpc":"2.0", "id": 1, "method": "suix_unsubscribeEvent", "params": [{{subscription_id}}]}
# e.g. {"jsonrpc":"2.0", "id": 1, "method": "suix_unsubscribeEvent", "params": [2861815076633913]}
Example Response 
{
    "jsonrpc":"2.0",
    "result":true,
    "id":1
}
Response Data
  • A Boolean representing whether the un-subscription attempt was successful.

​
(deprecated) suix_subscribeTransaction

BE PREPARED:Active Websocket connections will be broken when our Fullnodes restart (due to regular protocol upgrades, auto-restarts due to a health issue, etc). Make sure that you have a way to handle a broken connection and reconnect.
Description
Subscribe to a Sui transaction stream that matches the provided filter. Deprecated. See notice attop of page. Params
  • filter : TransactionFilter
    Note:The FromOrToAddress, Checkpoint, TransactionKind, and TransactionKindIn filters do not work for WebSocket subscriptions.
  • Shinami TypeScript SDK only:
    • onMessage: Function of type (TransactionEffects) => void to be called when a transaction is received. See TransactionEffects for more info.
Example Request Template This example uses our US East - us1 region URL since it is currently the only region where we offer Testnet. To send to another region, see the top of this page. The examples use the command line tool wscat, the Shinami Clients SDK, and the Mysten Rust SDK. Replace all instances of {{name}} with the actual value for that name 
# connect to the service
% wscat -c wss://api.us1.shinami.com/sui/node/v1/{{nodeAccessKey}}

{"jsonrpc":"2.0", "id":1, "method": "suix_subscribeTransaction", "params": [ {"MoveFunction": { "package":"{{packageId}}" }}]}
# e.g. {"jsonrpc":"2.0", "id":1, "method": "suix_subscribeTransaction", "params": [ {"MoveFunction": { "package":"0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66" }}]}
Example Response 
{
    "jsonrpc":"2.0",
    "result":<subscription_id>, // e.g. 2740101920696262
    "id":1
}
Response Data
  • wscat
  • Shinami TypeScript SDK
    • A function with no parameters that returns a boolean. Call this to unsubscribe from the subscription you just created. Returns true when the un-subscription was successful.
  • Mysten Rust SDK
Transaction Stream Data Type Transaction Stream Example Payload 
{
    "jsonrpc":"2.0",
    "method":"suix_subscribeTransaction",
    "params":{
        "subscription":1130080684748192,
        "result":{
            "messageVersion":"v1",
            "status":{
                "status":"success"
            },
            "executedEpoch":"193",
            "gasUsed":{
                "computationCost":"750000",
                "storageCost":"7698800",
                "storageRebate":"6147108",
                "nonRefundableStorageFee":"62092"
            },
            "modifiedAtVersions":[
                {
                    "objectId":"0x002cfa57179a9d704b40338aade07d7e964a25f42eed3a81a69862eca8458f95",
                    "sequenceNumber":"33873771"
                },
                {
                    "objectId":"0x12da3f2f187c8c2dde39326e8c7b030ccee25fd579b3e9325c6659d7451b70b6",
                    "sequenceNumber":"33873771"
                }
            ],
            "sharedObjects":[
                {
                    "objectId":"0xc216cdafaee1f417779f3f3051bfc70a4a6c1fe8c42107bf1db6b7a7b16cc936",
                    "version":33873771,
                    "digest":"4Nd3yXc11KrTpPQgTr44sGBsgfHLUCDSxgC6GG7pQNga"
                }
            ],
            "transactionDigest":"iWHW3f6EEJajsiLcztCE8NbnKGhvpfM9nUeVe1X3X77",
            "created":[
                {
                    "owner":{
                        "AddressOwner":"0x08d141f4c4f3d861d07c9c85480b2ddc983f17f101afd0291d9f8197c2a160a8"
                    },
                    "reference":{
                        "objectId":"0x68121914a572446631ee5be99168019b05e0b126b2282f2bbe696ea9601d9c1f",
                        "version":33873772,
                        "digest":"2WDuRjc9VULFeNP5y8zRcBX2zUhvdicHokECB7d8UQeU"
                    }
                },
                {
                    "owner":{
                        "AddressOwner":"0x08d141f4c4f3d861d07c9c85480b2ddc983f17f101afd0291d9f8197c2a160a8"
                    },
                    "reference":{
                        "objectId":"0x905ac00f3a17d0119fe794f76de1a067903ba1653853e06f9f2e065cffbe0a4c",
                        "version":33873772,
                        "digest":"E3yP1CwW94wvK9w521G2rjn1CYTv4nhS5ieidvBoogNi"
                    }
                }
            ],
             "mutated":[
                {
                    "owner":{
                        "AddressOwner":"0x08d141f4c4f3d861d07c9c85480b2ddc983f17f101afd0291d9f8197c2a160a8"
                    },
                    "reference":{
                        "objectId":"0x002cfa57179a9d704b40338aade07d7e964a25f42eed3a81a69862eca8458f95",
                        "version":33873772,
                        "digest":"332jmeHiV2SAviwHN7Spw7FfM1Y31VJxbxB1RLBPzVmK"
                    }
                },
                {
                    "owner":{
                        "Shared":{
                            "initial_shared_version":15819270
                        }
                    },
                    "reference":{
                        "objectId":"0xc216cdafaee1f417779f3f3051bfc70a4a6c1fe8c42107bf1db6b7a7b16cc936",
                        "version":33873772,
                        "digest":"CUAJvEx5J6EZk57C9ocogAZKG2Pq7bcTDAkrxmQnfiGh"
                    }
                }
            ],
            "deleted":[
                {
                    "objectId":"0x3909b5f3eb51418441d4c1ef9ee3a134737d97e83460ddaed4d1718dd7100365",
                    "version":33873772,
                    "digest":"7gyGAp71YXQRoxmFBaHxofQXAipvgHyBKPyxmdSJxyvz"
                }
            ],
            "gasObject":{
                "owner":{
                    "AddressOwner":"0x08d141f4c4f3d861d07c9c85480b2ddc983f17f101afd0291d9f8197c2a160a8"
                },
                "reference":{
                    "objectId":"0x002cfa57179a9d704b40338aade07d7e964a25f42eed3a81a69862eca8458f95",
                    "version":33873772,
                    "digest":"332jmeHiV2SAviwHN7Spw7FfM1Y31VJxbxB1RLBPzVmK"
                }
            },
            "eventsDigest":"4KSQza7XokSPgpjr3LeynzZnir2EmU3FgJR8wzDcH6PF",
            "dependencies":[
                "2bk5THZSzSwBt8zSaxPwcCYBE6sc1zCAULhMACd6Tp8f",
                "AyKtDH3SphRpC6smucm7MpJtfJFa5ZzHUVtpGwidbyo4",
                "GGsDqhUEP1QokmZyrJkYguJutuN1qf2XY6RmtyDtSeM3",
                "GMvEqg7sxZkKUFYGXE4NqWKw1Vzyh1GttREPEKvQKzzA"
            ]
        }
    }
}

​
(deprecated) suix_unsubscribeTransaction

Description
Unsubscribe from a Sui transaction stream. Deprecated. See notice attop of page. Params
  • wscat only
    • subscription_id: the ID of the subscription you are unsubscribing to
Example Request Template The following example demonstrates how to unsubscribe from the transaction stream subscribed to in the suix_subscribeTransaction example. The examples use the command line tool wscat and the Shinami Clients SDK. Replace all instances of {{name}} with the actual value for that name 
{"jsonrpc":"2.0", "id": 1, "method": "suix_unsubscribeTransaction", "params": [subscription_id]}
// e.g.  {"jsonrpc":"2.0", "id":1, "method": "suix_unsubscribeTransaction", "params": [2740101920696262]}
Example Response 
{
  "jsonrpc":"2.0",
  "result": true,
  "id": 1
}
Response Data
  • A Boolean representing whether the un-subscription attempt was successful.

​
Event and Transaction Filter Examples

​
Event Filter Examples

The following examples demonstrate how to use the various SuiEventFilter options. The examples use the command line tool wscat and the Shinami Clients SDK.
Note that the TimeRange filter does not successfully match events.
Example Request Template This example uses our US East - us1 region URL since it is currently the only region where we offer Testnet. To send to another region, see the top of this page. The examples use the command line tool wscat, the Shinami Clients SDK, and the Mysten Rust SDK. Replace all instances of {{name}} with the actual value for that name 
# connect to the service
% wscat -c wss://api.us1.shinami.com/sui/node/v1/{{nodeAccessKey}}

# create a subscription to see events for transactions sent to a given Move package
{ "jsonrpc":"2.0", "id":1, "method": "suix_subscribeEvent", "params": [{{SuiEventFilter}}]}

## ---- Example SuiEventFilter usage ---- ##

## Sender: matches events triggered by transactions executed by the given sender address
##
##   {"Sender":"0x02a212de6a9dfa3a69e22387acfbafbb1a9e591bd9d636e7895dcfc8de05f331"}
##
{ "jsonrpc":"2.0", "id":1, "method": "suix_subscribeEvent", "params": [{"Sender":"0x02a212de6a9dfa3a69e22387acfbafbb1a9e591bd9d636e7895dcfc8de05f331"}]}

## MoveEventType: matches the provided Move module event name
##
##   NOTE: the request DOES NOT check that the function and module names exist,
##   and matching is also case sensitive. The request also does not check that the
##   package id exists. It only checks that these parameters are sent in the expected format.
##   Make sure you double check your names and package id.
##
##   {"MoveEventType":"{{packageId}}::{{moduleName}}::{{eventName}}"}
##   {"MoveEventType": "0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66::spot_dex::SwapEvent" }
##
{ "jsonrpc":"2.0", "id":1, "method": "suix_subscribeEvent", "params": [{"MoveEventType": "0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66::spot_dex::SwapEvent"}]}

## MoveModule: matches events emitted by the provided Move module
##
##    NOTE: the request DOES NOT check that and module name exists,
##    and matching is also case sensitive. The request also does not check that the
##    package id exists. It only checks that these parameters are sent in the expected format.
##    Make sure you double check your module name and package id.
##
##   {"MoveModule": { "module": "spot_dex","package": "0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66"}}
##
{ "jsonrpc":"2.0", "id":1, "method": "suix_subscribeEvent", "params": [{ "MoveModule": { "module": "spot_dex","package": "0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66"}}]}

## MoveEventModule: matches events emitted by the provided Move module
##
##   NOTE: the request DOES NOT check that and module name exists,
##   and matching is also case sensitive. The request also does not check that the
##   package id exists. It only checks that these parameters are sent in the expected format.
##   Make sure you double check your module name and package id.
##
##   {"MoveEventModule": {"module": "spot_dex","package": "0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66"}}
##
{ "jsonrpc":"2.0", "id":1, "method": "suix_subscribeEvent", "params": [{"MoveEventModule": {"module": "spot_dex","package": "0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66"}}]}

## Transaction: matches events emitted by the provided digest
##
##   NOTE: This one doesn't really make sense for a websocket connection -
##   to listen for one transaction - but, you could, for example
##   listen for one very special sponsored transaction to be executed
##
##   {"Transaction": "BqjfsayknWKj1kwqkMnpHo62SviUvhfE7yCCwj6pdMt8"}
##
{ "jsonrpc":"2.0", "id":1, "method": "suix_subscribeEvent", "params": [{"Transaction": "BqjfsayknWKj1kwqkMnpHo62SviUvhfE7yCCwj6pdMt8"}]}

## -- The following will not throw an error but do not match events -- ##

## TimeRange
## {"TimeRange": {"endTime": "1698720000","startTime": "1698092253"}}
## { "jsonrpc":"2.0", "id":1, "method": "suix_subscribeEvent", "params": [{"TimeRange": {"endTime": "1698720000","startTime": "1698092253"}}]}

​
Transaction Filter Examples

The following examples demonstrate how to use the variousTransactionFilter options. The examples use the command line tool wscat and the Shinami Clients SDK. They also use our US East - us1 region URL since it is currently the only region where we offer Testnet. To send to another region, see the top of this page.
The FromOrToAddress, Checkpoint, TransactionKind, and TransactionKindIn filters do not successfully match transactions.
Example Request Template Replace all instances of {{name}} with the actual value for that name 
# connect to the service
% wscat -c wss://api.us1.shinami.com/sui/node/v1/{{nodeAccessKey}}

{"jsonrpc":"2.0", "id":1, "method": "suix_subscribeTransaction", "params": [ {{TransactionFilter}}]}

## ---- Example TransactionFilter usage ---- ##

## MoveFunction: matches when the move function is called by a transaction
##
##   NOTE: the request DOES NOT check that the function and module names exist,
##   and matching is also case sensitive. The request also does not check that the
##   package id exists. It only checks that these parameters are sent in the expected format.
##   Make sure you double check your names and package id.
##
##   {"MoveFunction": { "function": "swap_token_y", "module": "spot_dex", "package": "0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66"}}
##
{"jsonrpc":"2.0", "id":1, "method": "suix_subscribeTransaction", "params": [ {"MoveFunction": { "function": "swap_token_y", "module": "spot_dex", "package": "0xa0eba10b173538c8fecca1dff298e488402cc9ff374f8a12ca7758eebe830b66"}}]}

## InputObject: matches when the objectId is a transaction input
##
##   NOTE: the request DOES NOT check that the object id exists, only that it's
##   sent in a valid format.
##   Make sure you double check your object id.
##
##   { "InputObject": "0xd0086b7713e0487bbf5bb4a1e30a000794e570590a6041155cdbebee3cb1cb77"}
##
{"jsonrpc":"2.0", "id":1, "method": "suix_subscribeTransaction", "params": [ { "InputObject": "0xd0086b7713e0487bbf5bb4a1e30a000794e570590a6041155cdbebee3cb1cb77"}]}

## ChangedObject: matches when the objectId is changed by a transaction.
##
##   NOTE: the request DOES NOT check that the object id exists, only that it's
##   sent in a valid format.
##   Make sure you double check your object id.
##
##   {"ChangedObject": "0xd0086b7713e0487bbf5bb4a1e30a000794e570590a6041155cdbebee3cb1cb77"}
##
{"jsonrpc":"2.0", "id":1, "method": "suix_subscribeTransaction", "params": [ {"ChangedObject": "0xd0086b7713e0487bbf5bb4a1e30a000794e570590a6041155cdbebee3cb1cb77"}]}

## FromAddress: matches when the provided address is the sender of a transaction
##
## { "FromAddress": "0xa66b25208b75d1cc0c0e73695ea1a295a9c2912b5b5d9154497a0f4dc08e11d0"}
##
{"jsonrpc":"2.0", "id":1, "method": "suix_subscribeTransaction", "params": [ { "FromAddress": "0xa66b25208b75d1cc0c0e73695ea1a295a9c2912b5b5d9154497a0f4dc08e11d0"}]}

## ToAddress: matches when the provided address is the sender of a transaction
##
##   { "ToAddress": "0xa66b25208b75d1cc0c0e73695ea1a295a9c2912b5b5d9154497a0f4dc08e11d0"}
##
{"jsonrpc":"2.0", "id":1, "method": "suix_subscribeTransaction", "params": [ { "ToAddress": "0xa66b25208b75d1cc0c0e73695ea1a295a9c2912b5b5d9154497a0f4dc08e11d0"}]}

## FromAndToAddress: matches when the provided addresses match the sender and recipient of a transaction, respectively
##
##   {"FromAndToAddress": {"from": "0xa66b25208b75d1cc0c0e73695ea1a295a9c2912b5b5d9154497a0f4dc08e11d0", "to": "0xa66b25208b75d1cc0c0e73695ea1a295a9c2912b5b5d9154497a0f4dc08e11d0"}}
##
{"jsonrpc":"2.0", "id":1, "method": "suix_subscribeTransaction", "params": [ {"FromAndToAddress": {"from": "0xa66b25208b75d1cc0c0e73695ea1a295a9c2912b5b5d9154497a0f4dc08e11d0", "to": "0xa66b25208b75d1cc0c0e73695ea1a295a9c2912b5b5d9154497a0f4dc08e11d0"}}  ]}

## -- The following will not throw an error but do not match transactions -- ##

{"FromOrToAddress": {"addr": "{{SuiAddress}}"}}

{"Checkpoint" : "{{checkpointNum}}"}

{"TransactionKind": "{{TransactionKindName}}"}

{"TransactionKindIn": ["{{TransactionKindName}}","{{TransactionKindName}}"]}