Access Sui Data
You can access Sui network data like Transactions, Checkpoints, Objects, Events and more through the available interfaces. You can use this data in your application workflows, or to analyze the network behavior across applications or protocols of interest, or to perform audits on parts or the whole of the network.
This document outlines the interfaces that are currently available to access the Sui network data, along with a overview of how that's gradually evolving. Refer to the following definitions for release stages mentioned in this document:
- Alpha - Experimental release which is subject to change and is not recommended for production use. You can use it for validation in non-production environments.
- Beta - Somewhat stable release which is subject to change based on user feedback. Use it in production only after verifying the desired functional, performance, and other relevant characteristics in a non-production environment.
- Generally available (GA) - Fully stable release which you can use in production. Notifications for any breaking changes will be made in advance.
Current data access interfaces
Currently, you can use any of the following mechanisms to access Sui network data:
- Directly connect to JSON-RPC hosted on Sui Full nodes that are operated by RPC providers (filter by
RPC) or Data indexer operators. - Set up your own custom indexer to continuously load the data of interest into a Postgres database.
You can also use one of the future-oriented interfaces that are available in alpha, but those are not recommended for production use.
JSON-RPC
You can currently get real-time or historical data from a Sui Full node. Retention period for historical data depends on the pruning strategy implemented by a node operator, though currently all Full nodes are by default configured to implicitly fall back on a Sui Foundation managed key-value store for historical transaction data.
Websockets-based JSON RPCs suix_subscribeEvent and suix_subscribeTransaction were deprecated in July 2024. You should not rely on those RPCs in your applications. Refer to Future data access interfaces to learn about a future alternative.
Custom indexer
If you need more control over the types, granularity, and retention period of the data that you need in your application, or if you have specific query patterns that could be best served from a relational database, then you can setup your own custom indexer or reach out to a Data indexer operator who may already have setup one.
If you setup your own indexer, you are responsible for its ongoing maintenance and the related infrastructure & operational costs. You can reduce your costs by implementing a pruning strategy for the relational database by taking into account the retention needs of your application.
Future data access interfaces
Primary interfaces to access Sui access data in future will be:
- Full node gRPC API will replace JSON-RPC on Full nodes, and is currently available in alpha. If you already use the JSON-RPC or are starting to utilize it as a dependency for your use case, you would need to migrate to gRPC or GraphQL (see below) within a reasonable duration. Refer to the high-level timeline for gRPC availability below.
- Indexer 2.0 will include a performant and scalable version of the indexer framework and is currently available in alpha. You would be able to use it to load data from Full nodes into a postgres relational database.
- GraphQL RPC will include a lightweight GraphQL RPC Server that you would be able to use to read data from the Indexer 2.0's relational database. It is currently available in alpha. You would be able to use it as an alternative to gRPC, including for migration from JSON-RPC for an existing application. Refer to the high-level timeline for GraphQL availability below.
You would still be able to utilize a RPC provider (filter by RPC) or a Data indexer operator with the above options, assuming some or all of those providers choose to operate Indexer 2.0 and GraphQL RPC server as well.
gRPC API
As mentioned above, gRPC API will replace the JSON-RPC on Full nodes, such that JSON-RPC will be deprecated when gRPC API is generally available. Apart from the message & request format changes between the two, the gRPC API will come with a couple of key functional differences:
- It will have streaming or subscription API endpoints such that you could consume real-time streaming data in your application without having to poll for those records. This support will be a proper replacement of the deprecated Websockets support in JSON-RPC.
- It will not have implicit fallback on the above mentioned Sui Foundation managed key-value store for historical transaction data. Full node operators, RPC providers, and Data indexer operators will be encouraged to run their own instance of a similar archival store, which you would be able to explicitly define a dependency on to get the relevant historical data.
The gRPC API is in alpha and not recommended for production use. Its public documentation is coming soon. Until then, you can refer to this technical proto spec.
High-level timeline
The target times indicated below are tentative and subject to updates based on project progress and your feedback.
| Tentative time | Milestone | Description |
|---|---|---|
| March 2025 | Beta release of initial set of polling-based APIs | You can start validating the initial gRPC integration from your application and share feedback on the improvements you would like to see. |
| May 2025 | Beta release of streaming APIs and the remaining set of polling-based APIs | If your use case requires streaming low-latency data, this would be apt time to start validating that integration. Also, the API coverage will be functionality wise complete at this point, so you can start migrating your application in the non-production environments. |
| July 2025 | GA release of polling-based APIs with appropriate SDK support | You can start migration and cutover of your application in the production environment, with the support for streaming APIs still in beta. |
| September 2025 | GA release of scalable streaming APIs | If your use case requires streaming low-latency data, you can now use those APIs at scale. JSON-RPC will be deprecated at this point and migration notice period will start. |
| June 2026 | End of migration timeline | JSON-RPC will be fully deactivated at this point. This timeline assumes about 9 months of migration notice period. |
See below for a comparison with GraphQL RPC with Indexer 2.0.
GraphQL RPC with Indexer 2.0
As mentioned above, Indexer 2.0 will include a performant and scalable implementation of the indexer framework, and the GraphQL RPC Server will provide a performant GraphQL RPC layer while reading data from the indexer's relational database. Internally the indexer 2.0 framework will use the Full node RPCs to ingest the data, initially using the currently generally available JSON-RPC, and later using the above mentioned gRPC API.
GraphQL RPC format has been a key ask from many application builders, and the overall combination with Indexer 2.0 will come with following capabilities:
- Indexer 2.0 will be a declarative framework that you would be able to configure to load different kinds of Sui network data into postgres relational tables in parallel. This change is being implemented to improve the performance of the data ingestion into the postgres database.
- In addition, you would be able to configure pruning for different tables in the postgres tables, allowing you to tune it for the desired combination of performance and cost characteristics.
- GraphQL RPC Server will be a lightweight server component that will allow you to combine data from multiple database tables using GraphQL's expressive querying system, which is appealing to the frontend developers.
Both Indexer 2.0 and GraphQL RPC Server are in alpha and not recommended for production use. Check out this getting started document for GraphQL RPCs that refers to Mysten Labs managed relevant infrastructure. A sneak preview of how Indexer 2.0 could be setup is also available here.
Based on valuable feedback from the community, the GraphQL RPC release stage has been updated from beta to alpha. Refer to the high-level timeline for beta and GA releases in this document.
High-level timeline
The target times indicated below are tentative and subject to updates based on project progress and your feedback.
| Tentative time | Milestone | Description |
|---|---|---|
| July 2025 | Beta release of GraphQL RPC Server and Indexer 2.0 | You can start validating the setup of Indexer 2.0, along with testing the GraphQL RPC Server to access the indexed Sui data. You can also start migrating your application in the non-production environments, and share feedback on the improvements you would like to see. |
| September 2025 | Deprecation of JSON-RPC | JSON-RPC will be deprecated at this point and migration notice period will start. |
| December 2025 | GA release of GraphQL RPC Server and Indexer 2.0 | You can start migration and cutover of your application in the production environment. |
| June 2026 | End of migration timeline | JSON-RPC will be fully deactivated at this point. This timeline assumes about 9 months of migration notice period. |
See below for a comparison with the gRPC API.
When to use gRPC vs GraphQL with Indexer 2.0
You can use the high-level criteria mentioned in the following table to determine whether gRPC API or GraphQL RPC with Indexer 2.0 would better serve your use case. It's not an exhaustive list and it's expected that either of the options could work suitably for some of the use cases.
| Dimension | gRPC API | GraphQL RPC with Indexer 2.0 |
|---|---|---|
| Type of application or data consumer | Ideal for Web3 exchanges, defi market maker apps, other defi protocols or apps with ultra low-latency needs | Ideal for webapp builders or builders with slightly relaxed latency needs |
| Query patterns | Okay to read data from different endpoints separately and combine on the client-side; faster serialization, parsing and validation due to binary format | Need easier decoupling of the client with the ability to combine different types of data in fewer calls; data will be consistent across the underlying queries, including for paginated results |
| Retention period requirements | Default retention period will be 2 weeks with actual configuration dependent on the Full node operator and their needs & goals; see history-related note after the table | Default retention period in postgres database will be 4 weeks with actual configuration depending on your or a data indexer operator's needs; see history-related note after the table |
| Streaming needs | Will include a streaming or subscription API before beta release | Subscription API is planned but will be available after GA |
| Incremental costs | Little to no incremental costs if already using Full node JSON-RPC | Somewhat significant incremental costs if already using Full node JSON-RPC and if retention period & query patterns differences are insignificant |
Above table only mentions the default retention period for both options. The expectation is that it should be reasonable for you or a Full node / data indexer operator to configure that to a few times higher without impacting the performance significantly, but relevant guidelines will be shared before each option's respective GA release. Those will include recommendations for how to access historical data beyond the configured retention period.
Feel free to refer to the following articles outlining general differences between gRPC and GraphQL. Please validate the accuracy and authenticity of the differences using your own experiments.