Data Access Interfaces
Access Sui network data, like transactions, checkpoints, objects, and events, through different interfaces to build applications, analyze network behavior, or audit network activity.
Primary interfaces to access Sui data include:
-
GraphQL RPC: A generally available RPC service for flexible reads, transaction submission, and transaction simulation. GraphQL is backed by the General-purpose Indexer, Consistent Store, full nodes, and, when configured, the Archival Service.
-
gRPC API: A generally available, type-safe full node API that replaces JSON-RPC on full nodes. Use it when you need generated clients, low-latency point lookups, transaction submission, simulation, or streaming subscriptions.
-
Archival Store and Service: Provides long-term storage and access to historical network data that might no longer be available on full nodes because of pruning. GraphQL can route supported historical lookups to Archival when the GraphQL operator configures it. Full node gRPC does not implicitly fall back to Archival; gRPC clients must query an Archival Service endpoint directly.
-
Custom indexers: Build your own pipelines for application-specific data with the custom indexing framework. PostgreSQL is the default storage path, but custom indexers can write to any storage layer by implementing the framework storage traits.
Latest data access interfaces
View the video below for a comparison of the latest and legacy Sui data stacks.
Supported SDKs
You can use the following SDKs to interact with data on Sui.
-
Community-maintained Python SDK
When to use GraphQL or gRPC
Choose the RPC interface based on the client you are building and the data access pattern you need. GraphQL offers the broadest query surface and can combine data from multiple sources in one request. gRPC offers strongly typed generated clients, lower protocol overhead, and streaming subscriptions.
| Dimension | Prefer GraphQL RPC | Prefer gRPC API |
|---|---|---|
| Client type | Frontends, dashboards, developer tools, scripts, and apps in dynamic languages. | Backends, indexers, exchanges, low-latency services, and apps in typed systems languages. |
| Query patterns | Flexible, nested, filtered, or historical queries that combine transactions, objects, events, balances, and checkpoints in one request. | Point lookups, transaction execution, simulation, or workflows where the client is already modeled around protobuf messages. |
| Historical access | GraphQL can use configured Archival Service backends for supported historical lookups and supports filtered pagination over historical transactions and events. | Full node gRPC is limited by the node's retention. For higher retention, query the Archival Service gRPC endpoint directly. |
| Streaming needs | Use for query flexibility. Subscription support is not yet available on GraphQL. | Use gRPC when you need live checkpoint subscriptions or other streaming workflows. |
| Consistency | GraphQL scopes queries to checkpoints and can return read-after-write data from execution- or simulation-attached query scopes when fields do not require indexed history. | Use gRPC for low-latency full node reads, then wait or retry when subsequent reads depend on data being indexed elsewhere. |
A good default is GraphQL for frontends, tools, and flexible query workloads, and gRPC for backend systems, indexers, streaming, and performance-sensitive typed clients. You can use both interfaces in one application when different components have different requirements.
Refer to the following articles outlining general differences between gRPC and GraphQL. 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 is deprecated. Migrate to either gRPC or GraphQL RPC by July 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. Do not use those for production.
You can get real-time or historical data using JSON-RPC while it remains available. The retention period for historical data depends on the pruning strategy that node operators implement. Do not assume a full node implicitly falls back to the Archival Store; use GraphQL with Archival configured by the operator, or query an Archival Service endpoint directly.