Sui JSON-RPC Migration Guide

Sui is retiring JSON-RPC across the network. Please migrate your application to Sui gRPC by September 25, 2026 to avoid any disruption.

Sui gRPC is a Protocol Buffers API that covers reads, streaming, and transaction execution. This guide maps every JSON-RPC method to its gRPC equivalent and calls out the behavior differences that break a naive port.

Endpoints

gRPC uses a port-style host with TLS on 443, not an HTTPS URL path. Authentication uses a Bearer token in the request header:

-H "Authorization: Bearer <YOUR_API_KEY>"

Before you start

1. Clone the proto definitions from MystenLabs/sui-apis. Generated clients and grpcurl both need the .proto files.
2. Generate a typed client for your language, or use grpcurl for CLI testing.
3. Confirm connectivity with GetServiceInfo before porting anything else.

grpcurl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -import-path proto \
  -proto sui/rpc/v2/ledger_service.proto \
  -d '{}' \
  sui-mainnet.g.alchemy.com:443 \
  sui.rpc.v2.LedgerService/GetServiceInfo

Services

Method mapping

Checkpoints and network state

Transactions

Objects

Balances and coins

Events

Move packages

Name service

Methods with no gRPC equivalent

Beyond the unsafe_* builders above, these two read paths also require client-side work rather than a method swap.

Migration caveats

Typed requests replace positional params

JSON-RPC takes a positional array of arguments. gRPC takes typed protobuf messages. Do not translate positional indices directly, and do not port the JSON-RPC options object. Pass each value by name and use a FieldMask in read_mask to select the response shape.

Field masks are also the main latency lever. Requesting every field on a large object or transaction is significantly slower than requesting the three fields you actually use.

Pagination uses typed cursors

JSON-RPC cursors are opaque strings and are not portable into gRPC. Fetch a fresh cursor or token from the new API and persist that as your resume point.

gRPC uses two different paging mechanisms depending on the method. Check which one you are calling.

Unary methods — page tokens. StateService.ListOwnedObjects, StateService.ListBalances, StateService.ListDynamicFields, and MovePackageService.ListPackageVersions take page_size and page_token, and return next_page_token. The server can return fewer items than the requested page_size, so follow next_page_token rather than assuming a full page means more data and a short page means the end. Iterate until next_page_token is absent.

Server-streaming methods — bounds and cursors. LedgerService.ListCheckpoints, ListTransactions, and ListEvents have no page_token. They stream results and are controlled by these fields instead.

Each response frame carries watermark.cursor. Persist it as your resume point and pass it back as options.after on an ascending scan, or options.before on a descending one. The stream ends with a QueryEnd frame whose reason states why it stopped: QUERY_END_REASON_ITEM_LIMIT, QUERY_END_REASON_SCAN_LIMIT, QUERY_END_REASON_CHECKPOINT_BOUND, QUERY_END_REASON_CURSOR_BOUND, or QUERY_END_REASON_LEDGER_TIP. JSON responses carry these full enum names; typed clients expose them as generated enum constants. Do not treat stream termination as "all data retrieved" — check the reason and resume from the last cursor if it stopped on a limit rather than a bound.

WebSocket subscriptions become gRPC streams

suix_subscribeEvent and suix_subscribeTransaction are replaced by server-streaming RPCs on SubscriptionService. Three differences matter in production:

• Subscriptions begin at the current tip and do not support resumption. There is no cursor you can pass to start a stream from the past.
• To avoid gaps on reconnect, open the subscription first and immediately drain live frames into durable, bounded storage while a separate worker backfills with the paired list API (ListEvents, ListTransactions, or ListCheckpoints). Do not leave the subscription unread during backfill.
• Process the durable spool after backfill reaches the subscription boundary, and restart from the last durably processed cursor if the spool fills or the stream ends.

Filtered streams emit progress-only frames where the payload is unset but watermark is present. Track watermark.cursor on every frame, not just on frames carrying data.

SubscribeCheckpoints differs: its frames carry a plain cursor (a checkpoint sequence number) instead of a watermark message. Backfill checkpoints by passing cursor + 1 as start_checkpoint on ListCheckpoints, not options.after.

Pruning returns NOT_FOUND, with no implicit fallback

JSON-RPC sometimes resolved older data through fallback paths that were invisible to the caller. gRPC does not. A full node serves only data inside its retention window (7 epochs / ~7 days) and returns NOT_FOUND for anything older.

If your workload does replays, audits, or deep historical reads, plan for this explicitly rather than discovering it as intermittent NOT_FOUND responses in production.

Negative filters work differently

JSON-RPC object queries supported MatchAll, MatchAny, and MatchNone combinators. gRPC object queries have no equivalent: ListOwnedObjects takes a single positive object_type, so combine results from multiple calls or filter client-side. Transaction and event queries are where negation lives — TransactionFilter and EventFilter use a disjunctive normal form (DNF) filter with per-literal negation.

TransactionFilter and EventFilter are structured in three levels:

• terms are ORed together. A present filter must contain at least one term. An absent filter matches everything.
• literals within a single term are ANDed together.
• Each literal sets exactly one predicate, plus an optional negated: true to invert it.

Match transactions not sent by a given address:

{
  "filter": {
    "terms": [
      { "literals": [ { "negated": true, "sender": { "address": "0x..." } } ] }
    ]
  }
}

Set the predicate field directly on the literal, as above. Some generated clients (notably protobuf-ts) represent oneofs internally as { "oneofKind": "sender", ... }; that is a client-side artifact and is not valid protobuf JSON. Sending it fails with message type sui.rpc.v2.TransactionLiteral has no known field named oneofKind. If you instead see TransactionFilter has no known field named negated, you have set the literal's fields directly on the filter — nest them under terms[].literals[].

Transaction predicates: sender, affected_address, affected_object, move_call, emit_module, event_type, event_stream_head, package_write. Event predicates: sender, emit_module, event_type, event_stream_head.

Write addresses in filter literals fully padded to 64 hex characters. Short forms are rejected with INVALID_ARGUMENT: invalid address — for example 0x3::validator::StakingRequestEvent fails while 0x0000…0003::validator::StakingRequestEvent works. (ListOwnedObjects's object_type accepts short forms; filters do not.)

Balances cover two representations

Sui tracks value both in coin objects and in the address-balance accumulator. GetBalance returns a Balance message with three numeric fields.

Read balance for the combined total. Read coinBalance and addressBalance separately when you need to reconcile against your own ledger. There is no totalBalance field.

These fields use proto3 presence, so a field that is unset is omitted from the JSON response rather than returned as 0. Treat an absent addressBalance as zero rather than assuming the field is always present.

For transaction building, prefer gas smashing or address-balance gas payments over hand-assembling coin lists from ListOwnedObjects.

optional does not mean optional

In proto3, marking a field optional enables presence detection, meaning the server can tell an explicitly set value from a default. It does not mean you can omit the field. Follow the API contract for required inputs.

Ecosystem tools migrate on their own schedule

Worked examples

Look up a transaction

grpcurl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -import-path proto \
  -proto sui/rpc/v2/ledger_service.proto \
  -d '{
    "digest": "YOUR_TX_DIGEST",
    "read_mask": {"paths": ["digest", "effects", "events"]}
  }' \
  sui-mainnet.g.alchemy.com:443 \
  sui.rpc.v2.LedgerService/GetTransaction

Read a balance

grpcurl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -import-path proto \
  -proto sui/rpc/v2/state_service.proto \
  -d '{
    "owner": "0xYOUR_ADDRESS",
    "coin_type": "0x2::sui::SUI"
  }' \
  sui-mainnet.g.alchemy.com:443 \
  sui.rpc.v2.StateService/GetBalance

List owned coins

Replaces suix_getCoins. Drop the type parameter from the filter to cover the suix_getAllCoins case.

grpcurl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -import-path proto \
  -proto sui/rpc/v2/state_service.proto \
  -d '{
    "owner": "0xYOUR_ADDRESS",
    "object_type": "0x2::coin::Coin<0x2::sui::SUI>",
    "read_mask": {"paths": ["object_id", "version", "balance"]}
  }' \
  sui-mainnet.g.alchemy.com:443 \
  sui.rpc.v2.StateService/ListOwnedObjects

Stream events

Replaces suix_subscribeEvent. Pair it with LedgerService/ListEvents using the same filter to backfill.

grpcurl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -import-path proto \
  -proto sui/rpc/v2/subscription_service.proto \
  -d '{}' \
  sui-mainnet.g.alchemy.com:443 \
  sui.rpc.v2.SubscriptionService/SubscribeEvents

Migration checklist

• Generate a typed client from the v2 protos, not v2beta2
• Swap every JSON-RPC call using the mapping tables above
• Replace options objects with read_mask field masks, requesting only the fields you use
• Replace stored JSON-RPC cursors with fresh gRPC page tokens
• Move unsafe_* transaction building to PTBs client-side
• Rebuild staking reads on ListOwnedObjects plus GetObject, and move APY to a client-side computation
• Rework WebSocket subscribers into stream plus backfill, with a durable spool and persisted watermark cursor
• Handle NOT_FOUND for reads outside the retention window
• Load test against the new response shapes before cutover

Reference

• Sui Full Node gRPC methods
• Sui JSON-RPC migration guide
• Sui proto definitions on GitHub