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, to analyze 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 an overview of how that's gradually evolving. Refer to the following definitions for release stages mentioned in this document:
- Alpha - Experimental release that is subject to change and is not recommended for production use. You can use it for exploration in non-production environments.
- Beta - Somewhat stable release that is subject to change based on user feedback. You can use it for testing and production readiness in non-production environments. If you use it in production, do so at your own risk. Only entertain using after verifying the desired functional, performance, and other relevant characteristics in a non-production environment, and if you are comfortable keeping your application regularly updated for any changes.
- Generally available (GA) - Fully stable release that you can use in production. Notifications for any breaking changes are made in advance.
Latest data access interfaces
Primary interfaces to access Sui data include:
- gRPC API replaces JSON-RPC on full nodes. If you already use JSON-RPC or are starting to utilize it as a dependency for your use case, note that it is deprecated and you need to migrate to gRPC or GraphQL RPC (see below).
- General-purpose Indexer is a performant and scalable implementation of the custom indexing framework. It is currently available in beta. Use it to load network data at scale into a Postgres relational database.
- GraphQL RPC includes a lightweight GraphQL RPC service that you can use to read data from the General-purpose Indexer's relational database. It is currently available in beta. You can 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 and General-purpose Indexer availability.
- Archival Store and Service provides long-term storage and access to historical network data that may no longer be available on Full nodes due to pruning. If using gRPC as your primary data access mechanism, you can query it using the gRPC
LedgerServiceAPIs by changing the endpoint from a Full node to the Archival Service. If using GraphQL RPC, it's abstracted and you do not need to directly interact with it.
View the video below for a comparison of the latest and legacy Sui data stacks.
gRPC API
gRPC API replaces the JSON-RPC on full nodes. JSON-RPC is deprecated and gRPC API is generally available. Apart from the message and request format changes between the two, the gRPC API comes with a couple of key functional differences:
- Use streaming or subscription API endpoints to consume real-time streaming data in your application without having to poll for those records. This support replaces the deprecated WebSocket support in JSON-RPC.
- There is no implicit fallback on the Sui Foundation-managed archival store for historical data. Full node operators, RPC providers, and data indexer operators are encouraged to run their own instance of a similar archival store that can be a explicit dependency to fetch historical data.
See When to use gRPC vs GraphQL with General-purpose Indexer for a comparison with GraphQL RPC.
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 |
|---|---|---|
| ✔️ April 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 want to see. |
| ✔️ July 2025 | Beta release of streaming APIs and the remaining set of polling-based APIs. | If your use case requires streaming low-latency data, this is an apt time to start validating that integration. Also, the functionality of the API coverage will be complete at this point, so you can start migrating your application in non-production environments. |
| ✔️ September-October 2025 | GA release of polling-based and streaming APIs. | Begin migration and cutover of your application in the production environment. JSON-RPC will be deprecated at this point and migration notice period will start. |
| April 2026 | End of migration timeline. | JSON-RPC will be fully deactivated at this point. This timeline assumes about 7 months of migration notice period. |
The gRPC and GraphQL RPC APIs have replaced JSON-RPC! View the video below to learn more about the migration timeline and which API to use.
General-purpose Indexer
As mentioned, General-purpose Indexer includes a performant and scalable implementation of the custom indexing framework. The underlying framework uses the remote checkpoint store and full node RPCs to ingest the data.
General-purpose Indexer is declarative in the sense that you can seamlessly configure it to load different kinds of Sui network data into Postgres relational tables in parallel. This improves the performance of the data ingestion into the Postgres-compatible database. In addition, you can configure pruning for different tables in the Postgres-compatible database, allowing you to tune it for the desired combination of performance and cost characteristics.
General-purpose Indexer is in beta, which is a somewhat stable release that is subject to change based on user feedback. You can use it for testing and production readiness in non-production environments.
GraphQL RPC
The GraphQL RPC Service is a performant GraphQL RPC layer that reads data from the General-purpose Indexer's Postgres-compatible database, Archival Store and Service, and a full node. GraphQL RPC is an alternative to gRPC API. If you are already using deprecated JSON-RPC in your application today, you have an option to migrate to GraphQL RPC by either self-operating the combined stack of General-purpose Indexer, Postgres-compatible database, and GraphQL RPC server, or by utilizing it as a service from an RPC provider or indexer operator.
GraphQL RPC Service is a lightweight server component that allows you to combine data from multiple tables in the Postgres-compatible database using GraphQL's expressive querying system, which is appealing to frontend developers.
See When to use gRPC vs GraphQL with General-purpose Indexer for a comparison with the gRPC API.
GraphQL RPC Server is in beta, which is a somewhat stable release that is subject to change based on user feedback. You can use it for testing and production readiness in non-production environments.
High-level timeline
The target times indicated in this table are tentative and subject to updates based on project progress and your feedback.
| Tentative time | Milestone | Description |
|---|---|---|
| ✔️ September 2025 | Beta release of GraphQL RPC Server and General-purpose Indexer. | You can start validating the setup of General-purpose Indexer, 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 want to see. |
| ✔️ September-October 2025 | Deprecation of JSON-RPC. | JSON-RPC will be deprecated at this point and migration notice period will start. |
| December-January 2025 | GA release of GraphQL RPC Server and General-purpose Indexer. | Begin migration and cutover of your application in the production environment. |
| April 2026 | End of migration timeline. | JSON-RPC will be fully deactivated at this point. This timeline assumes about 7 months of migration notice period. |
Archival Store and Service
Long-term access to historical on-chain data is essential for developers, although Full nodes enforce limited retention for scalability and performance. Use the Archival Store and Service to access historical on-chain data data through a pluggable storage backend (like Bigtable) and a gRPC interface compatible with the LedgerService endpoint.
This infrastructure serves as the historical backbone for GraphQL RPC, gRPC-based apps, and data platforms, providing efficient point-lookups for old transactions, checkpoints, and object states, even after Full nodes have pruned them.
You can:
- Query the archival store via gRPC-based archival service for missing data when using a Full node
- Power GraphQL RPC queries that span unretained data
- Host the service yourself, use a provider, or rely on the public-good version (with rate limits)
Learn more about Archival Store and Service.
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 are not served with gRPC or GraphQL RPC, then you can set up your own custom indexer or reach out to a Data indexer operator that might already have set one up.
If you set up your own indexer, you are responsible for its ongoing maintenance and the related infrastructure and 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.
Custom indexers are a good choice for app or protocol-specific logic and data layout.
When to use gRPC vs GraphQL with General-purpose Indexer
You can use the high-level criteria mentioned in the following table to determine whether gRPC API or GraphQL RPC with General-purpose Indexer 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 General-purpose Indexer |
|---|---|---|
| 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. | Allows easier decoupling of the client with the ability to combine data from different tables in a single request; returns consistent data from different tables across similar checkpoints, including for paginated results. |
| Retention period requirements. | Default retention period will be two weeks with actual configuration dependent on the full node operator and their needs and goals; see history-related note after the table. | Default retention period in Postgres database will be four weeks with actual configuration depending on your needs or a RPC provider or data indexer operator's setup; 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 and query patterns differences are insignificant. |
This table only mentions the default retention period for both options. The expectation is that it's reasonable for a full node operator, RPC provider, or data indexer operator to configure that to a few times higher without significantly impacting the performance. Also by default, the GraphQL RPC service can directly connect to the archival store and service for historical data beyond the retention period configured for the underlying Postgres database. Whereas in comparison, gRPC API doesn't have such direct connectivity to the archival store and service and you must directly connect to one from your application.
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.
- https://stackoverflow.blog/2022/11/28/when-to-use-grpc-vs-graphql/
- https://blog.postman.com/grpc-vs-graphql/
Legacy data access interfaces
JSON-RPC
JSON-RPC is deprecated. Migrate to either gRPC or GraphQL RPC by April 2026.
Refer to the list of RPC or data providers that have enabled gRPC on their full nodes or offer GraphQL RPC. Contact a provider directly to request access. If your RPC or data provider doesn’t yet support these data access methods, ask them to enable support or contact the Sui Foundation team on Discord, Telegram, or Slack for help.
Directly connect to JSON-RPC hosted on Sui full nodes that are operated by RPC providers (filter by RPC) or data indexer operators.
- The Mainnet, Testnet, or Devnet load balancer URLs abstract the Sui Foundation-managed full nodes. Those are not recommended for production use.
You can get real-time or historical data using JSON-RPC. Retention period for historical data depends on the pruning strategy that node operators implement, though the default configuration for all full nodes is to implicitly fall back on the Archival Store managed by the Sui Foundation.
WebSocket-based JSON RPCs suix_subscribeEvent and suix_subscribeTransaction were deprecated in July 2024. Do not rely on those RPCs in your applications. Refer to Future data access interfaces to learn about the gRPC subscriptions alternative.
Related links
Use GraphQL to make Sui RPC calls. This feature is currently in Beta.
The sui-indexer-alt-framework is a powerful Rust framework for building high-performance, custom blockchain indexers on Sui. It provides customizable, production-ready components for data ingestion, processing, and storage.
The sui-indexer-alt-framework provides two distinct pipeline architectures. Understand the differences between the sequential and concurrent pipelines that the sui-indexer-alt-framework provides to decide which best suits your project needs.
Overview of the Archival Store and Service to access historical Sui network data.
Establishing a custom indexer helps improve latency, allows pruning the data of your Sui full node, and provides efficient assemblage of checkpoint data.
The GraphQL RPC Beta service offers a structured way for your clients to interact with data on the Sui blockchain. It accesses data processed by a general-purpose indexer and can connect to an archival store for historical network state.
Generated documentation from the Sui gRPC schema.
Schema documentation for GraphQL Beta.