accessing-data

---
name: accessing-data
description: >
  How to read data from the Sui network. Use when choosing or implementing
  a data access strategy — queries for on-chain state, indexing pipelines,
  historical lookups, event subscriptions, cross-chain reads, or off-chain
  blob storage. Covers the three live Sui APIs (gRPC, GraphQL RPC,
  deprecated JSON-RPC), the Archival Store, the General-Purpose Indexer,
  the `sui-indexer-alt` custom indexing framework, and Walrus for off-chain
  blobs.
---

# Accessing Data on Sui

> **MCP tool:** When available in your environment, also query the Sui documentation MCP server (`https://sui.mcp.kapa.ai`) for up-to-date answers. Use it for verification and for details not covered by these reference files.

"How do I read data from Sui?" is the most frequently mis-answered question in agent-written Sui code. The defaults have changed. This skill fixes it.

**Key fact: JSON-RPC is deprecated.** From the official docs:

> JSON-RPC is deprecated. Migrate to either gRPC or GraphQL RPC by July 2026.

Any code — or tutorial — that uses JSON-RPC for new reads is wrong for mainnet past mid-2026.

The four canonical data surfaces are:

1. **gRPC** — low-latency, real-time, code-gen-friendly. Served by full nodes. Supports streaming/subscriptions. The default for transaction submission, live reads, and ingestion pipelines.
2. **GraphQL RPC** — flexible relational queries over the General-Purpose Indexer's Postgres + full node + Archival Store. Supports reads, transaction submission, and dry-run. Best for frontends, dashboards, wallets, and any client that benefits from composable queries.
3. **Archival Store** — long-term historical storage of transactions, checkpoints, and object states beyond full-node pruning. Accessed via GraphQL RPC (which routes to archival automatically for pruned data). Full nodes serving gRPC do **not** implicitly fall back to archival — if you need high-retention historical data over gRPC, you must query the archival service directly at its own URL.
4. **Custom indexer (`sui-indexer-alt`)** — build your own data pipeline keyed on exactly the on-chain data your app needs. Writes to any storage layer (Postgres by default, but any backend works). Ingests checkpoints from GCS (backfill) + full node gRPC (steady state).

Off-chain blob data (images, audio, models, large JSON) belongs on **Walrus**, not on-chain. Sui stores blob metadata; the blobs themselves sit on Walrus storage nodes.

All patterns in this skill are derived from:
- https://docs.sui.io/concepts/data-access/data-serving (overview & deprecation notice)
- https://docs.sui.io/concepts/data-access/graphql-rpc (GraphQL)
- https://docs.sui.io/concepts/data-access/archival-store (archival)
- https://docs.sui.io/guides/operator/indexer-stack-setup (general-purpose indexer)
- https://docs.wal.app (Walrus)

If unsure about an API, fetch from the relevant page before answering. Do not guess from Ethereum/Solana analogs — Sui's data surfaces are distinct.

---

## Reference files

### grpc — gRPC API
**Path:** `grpc.md`
**Load when:** writing backend services, indexers, exchanges, market makers, real-time clients, or any high-throughput read path. Also when subscribing to effects streams or doing dry runs / transaction simulation.
**Covers:** service surface (`ledger_service`, `transaction_execution_service`, `move_package_service`, `name_service`, `subscription_service`), endpoint URLs per network, the TypeScript (`SuiGrpcClient`) and Rust (`sui-rpc` crate) clients, streaming vs request-response, code-gen for arbitrary languages.

### graphql — GraphQL RPC
**Path:** `graphql.md`
**Load when:** the app needs flexible, composable queries — e.g., a frontend that joins object data with owner metadata and event history in a single request, transaction submission or dry-run via GraphQL, or historical queries with filters.
**Covers:** GraphQL endpoint URLs, relationship to the General-Purpose Indexer + Archival Store, `SuiGraphQLClient` usage, typical query shapes, pagination patterns, rate limits, transaction execution and simulation via GraphQL, execution-attached read-after-write consistency.

### indexers — Custom indexing (`sui-indexer-alt`)
**Path:** `indexers.md`
**Load when:** a user asks "how do I track X event across history?", "how do I build an explorer / leaderboard / analytics pipeline?", or when a GraphQL or gRPC query is too slow / not filterable the way they need.
**Covers:** the checkpoint-streaming pipeline model, backfill (GCS buckets like `gs://mysten-mainnet-checkpoints-use4`) vs steady-state (full node gRPC), writing a pipeline config (`events.toml`, `obj_versions.toml` patterns), concurrency tuning, and when to run the General-Purpose Indexer vs a custom one.

### archival — Archival Store
**Path:** `archival.md`
**Load when:** the data you need has been pruned from full nodes — old transactions, old object versions, old checkpoints. GraphQL can route to archival when operator-configured; gRPC does not — you must query the Archival Service directly.
**Covers:** what the Archival Store retains, why pruning exists, how GraphQL routes to archival (operator-configured), Archival Service gRPC endpoint URLs, direct archival access for gRPC users, use cases (compliance, dispute resolution, long-range analytics).

### walrus — Off-chain blob storage
**Path:** `walrus.md`
**Load when:** the user wants to store a file (image, audio, model, document, large JSON, video) "on Sui" or is trying to put megabytes of data into a Move object. Route them to Walrus.
**Covers:** why you don't put blobs on-chain (250 KB per-object cap, storage-fund economics), the Walrus model (erasure-coded blobs stored off-chain with on-chain availability certificates), blob lifecycle, and the `@mysten/walrus` client extension.

### use-cases — Use case → method mapping
**Path:** `use-cases.md`
**Load when:** the user describes what they want to *do* and you need to pick the right surface. This is the first file to load for an unfamiliar data access request.
**Covers:** table of common use cases (balance lookup, owned-object list, event subscription, historical point-in-time read, analytics dashboard, cross-table joins, blob storage) mapped to the right API with rationale.

## Routing guide

| Task | Load |
|------|------|
| "How do I read X from Sui?" (first-pass question) | use-cases |
| Writing a backend/indexer read path | grpc + indexers |
| Writing a frontend data query | graphql (+ frontend-apps skill for hook patterns) |
| Building a custom analytics / explorer pipeline | indexers |
| Looking up data older than full-node retention | archival + graphql |
| Storing / retrieving a large file | walrus |
| Migrating an existing JSON-RPC app | use-cases + grpc + graphql |
| Designing a new app from scratch | use-cases (then grpc or graphql based on client type) |
| Full code review of a data-heavy app | **all reference files** |

## Skill Content

### Key concepts

- **JSON-RPC is deprecated.** Full deactivation targeted for **July 2026**. Any new code must default to gRPC or GraphQL RPC. Existing JSON-RPC code must be migrated.
- **gRPC is the performance default.** Typed protobuf, streaming, low latency, polyglot client code gen (TS, Rust, Go, Python, etc.). Served directly by full nodes. Best for backends, indexers, and apps built in typed systems languages.
- **GraphQL RPC is the flexibility default.** Generally available. Reads from the General-Purpose Indexer's Postgres + full node + Archival Store. Also supports transaction submission and dry-run. One request can span multiple entity types. Best for frontends, tools, and apps built in dynamic languages.
- **Archival routing is operator-configured.** GraphQL RPC can route supported historical point lookups to Archival when the GraphQL operator configures it. Full nodes serving gRPC do **not** fall back to archival — if you need historical data over gRPC, query the Archival Service endpoint directly (e.g., `archive.mainnet.sui.io:443`).
- **Custom indexers exist because no hosted API fits every query shape.** If you need filtered sorts over millions of rows with app-specific indexes, run your own `sui-indexer-alt` pipeline. Custom indexers can write to any storage layer by implementing the framework's `Store` and `Connection` traits — Postgres is the default, not a requirement.
- **On-chain storage is not general-purpose blob storage.** Max Move object size is 250 KB. Storage is paid once (storage fund redistributes returns to validators). Big files go to Walrus.
- **The storage fund does not "hold your data."** It's an economic mechanism: a fraction of each write fee goes in; validators earn yield that pays for ongoing storage. It affects pricing, not where you store.

### Rules

1. **Absolutely no JSON-RPC for new code.** If a tutorial says `new SuiClient({ url: getFullnodeUrl(...) })`, replace with `new SuiGrpcClient({ network, baseUrl })`. If a user insists on JSON-RPC, name the deprecation + July 2026 sunset and offer `SuiJsonRpcClient` only as a migration stopgap.
2. **Choose your initial API based on what you're building.** Front-ends, tools, and apps in dynamic languages → start with **GraphQL RPC** (superset of gRPC functionality, composable queries, archival routing). Backends, indexers, and apps in typed systems languages → start with **gRPC** (performance, streaming, code-gen). Only switch if you hit a limitation. **Current temporary caveats** (will be resolved in the coming months): only gRPC supports subscriptions; only GraphQL supports filtered pagination over historical transactions and events.
3. **Archival routing differs by API.** GraphQL RPC routes supported historical point lookups to archival when the operator configures it. gRPC does **not** — if you need high-retention historical access via gRPC, query the Archival Service directly at its own URL (e.g., `archive.mainnet.sui.io:443`).
4. **Build a custom indexer only when hosted APIs don't fit.** Operating an indexer is ongoing work — Postgres, checkpoint ingestion, failure handling. Evaluate GraphQL RPC first.
5. **Put large files on Walrus.** Never advise embedding images/audio/video in Move objects or in transaction inputs. If the user is trying to, route them to the `walrus` reference file.
6. **Map use case → method correctly.** See `use-cases.md`:
   - Live balance / owned-object / coin list → **gRPC `client.core.*`**.
   - Flexible multi-entity query for a frontend → **GraphQL RPC**.
   - Historical transaction > N days old → **GraphQL RPC (routes through archival)**.
   - Custom leaderboard / analytics across all events → **custom indexer**.
   - Transaction subscription / real-time effects feed → **gRPC streaming**.
   - Large files → **Walrus**.
7. **Read-after-write consistency varies by API.** For **GraphQL RPC**, queries nested under `executeTransaction` or `simulateTransaction` are evaluated in a special scope just after the executed/simulated transaction, without waiting for indexing. This provides consistent read-after-write for fields that don't require indexed history (e.g., effects, gas, object changes). Prefer selecting these fields in the same GraphQL request rather than making a separate indexed follow-up query. For **gRPC**, call `client.waitForTransaction({ digest })` before the follow-up read. In both cases, cross-node reads after a write are not guaranteed immediately visible.
8. **Cite docs when unsure.** All sources listed above.

### Common mistakes

- **Using `client.getObject` / `client.getOwnedObjects` / `client.getCoins`** — these are v1 JSON-RPC method names. v2 is `client.core.getObject` / `client.core.listOwnedObjects` / `client.core.listCoins` on any of the v2 clients.
- **Recommending "the Sui API" without specifying which.** "The Sui API" conflates three different interfaces with different use cases. Always name gRPC / GraphQL / JSON-RPC.
- **Telling users to "use the indexer"** for a simple query that gRPC covers in one method. Only reach for a custom indexer when you've outgrown the hosted APIs.
- **Storing images or large JSON "on Sui."** Sui's 250 KB object size limit and pricing model make this wrong. Use Walrus.
- **Assuming all three APIs return the same shape.** gRPC is protobuf; GraphQL is typed GraphQL; JSON-RPC is JSON with v1-specific nesting. Response shapes differ; field names differ; pagination differs.
- **Polling for events via JSON-RPC.** Use gRPC streaming / subscriptions instead. Polling is high-cost and high-latency.
- **Reading from an RPC node and writing to a different one expecting read-after-write consistency.** Fullnodes are eventually consistent across the network. For GraphQL, prefer selecting fields in the same `executeTransaction` mutation (execution-attached scope gives consistent results without indexing). For gRPC, read from the same node you wrote to, or `waitForTransaction` before cross-node reads.
- **Conflating "storage fund" with "storage service."** The storage fund is a tokenomics mechanism. It is not an API you call.
- **Assuming gRPC falls back to archival for pruned data.** It does not. GraphQL can route to archival when the operator configures it. For gRPC clients needing historical data, query the Archival Service directly (e.g., `archive.mainnet.sui.io:443`).
- **Assuming GraphQL archival routing is automatic.** It's operator-configured. If the GraphQL operator hasn't paired the service with an Archival Service backend, retention is limited to the Postgres database's retention policy.