Objects and ledger

The LedgerService provides methods for querying objects, transactions, checkpoints, epochs, and general chain information.

Returns chain metadata including the current checkpoint height and epoch.

Request: No fields required.

Response:

Field	Type	Description
`chain`	string	Network name (e.g., `mainnet`)
`chain_id`	string	Chain identifier
`checkpoint_height`	uint64	Current checkpoint height
`epoch`	uint64	Current epoch
`lowest_available_checkpoint`	uint64	Earliest available checkpoint
`lowest_available_checkpoint_objects`	uint64	Earliest checkpoint with object data
`server`	string	Server identifier
`timestamp`	Timestamp	Server timestamp

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

Fetches a single object by ID, optionally at a specific version.

Request:

Field	Type	Required	Description
`object_id`	string	Yes	The object ID
`version`	uint64	No	Specific version to fetch
`read_mask`	FieldMask	No	Fields to include in the response

Response:

Field	Type	Description
`object`	Object	The requested object

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

Fetches multiple objects in a single request.

Request:

Field	Type	Required	Description
`requests`	repeated GetObjectRequest	Yes	Array of object requests
`read_mask`	FieldMask	No	Fields to include in each response

Response:

Field	Type	Description
`objects`	repeated GetObjectResult	Array of results, each containing an `object` or `error`

grpcurl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -import-path proto \
  -proto sui/rpc/v2/ledger_service.proto \
  -d '{
    "requests": [
      {"object_id": "0x5"},
      {"object_id": "0x6"}
    ]
  }' \
  sui-mainnet.g.alchemy.com:443 \
  sui.rpc.v2.LedgerService/BatchGetObjects

Fetches a single executed transaction by its digest.

Request:

Field	Type	Required	Description
`digest`	string	Yes	Transaction digest
`read_mask`	FieldMask	No	Fields to include in the response

Response:

Field	Type	Description
`transaction`	ExecutedTransaction	The executed transaction

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

Fetches multiple transactions by digest in a single request.

Request:

Field	Type	Required	Description
`digests`	repeated string	Yes	Array of transaction digests
`read_mask`	FieldMask	No	Fields to include in each response

Response:

Field	Type	Description
`transactions`	repeated GetTransactionResult	Array of results, each containing a `transaction` or `error`

grpcurl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -import-path proto \
  -proto sui/rpc/v2/ledger_service.proto \
  -d '{"digests": ["DIGEST_1", "DIGEST_2"]}' \
  sui-mainnet.g.alchemy.com:443 \
  sui.rpc.v2.LedgerService/BatchGetTransactions

Fetches a checkpoint by sequence number or digest.

Request (one of):

Field	Type	Required	Description
`sequence_number`	uint64	No	Checkpoint sequence number
`digest`	string	No	Checkpoint digest
`read_mask`	FieldMask	No	Fields to include in the response

Response:

Field	Type	Description
`checkpoint`	Checkpoint	The checkpoint data

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

Fetches epoch information. Returns the current epoch if no epoch number is specified.

Request:

Field	Type	Required	Description
`epoch`	uint64	No	Epoch number. Defaults to current epoch
`read_mask`	FieldMask	No	Fields to include in the response

Response:

Field	Type	Description
`epoch`	Epoch	Epoch information

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/GetEpoch

Streams checkpoints matching the provided filter over a checkpoint range. Server-streaming RPC that returns one checkpoint per frame plus progress watermarks; the final frame carries a QueryEnd marker.

Request:

Field	Type	Required	Description
`read_mask`	FieldMask	No	Fields to include on each checkpoint
`start_checkpoint`	uint64	No	Inclusive lower bound. Defaults to genesis
`end_checkpoint`	uint64	No	Exclusive upper bound. Defaults to the current indexed tip
`filter`	TransactionFilter	No	DNF filter. A checkpoint matches if any transaction in it satisfies the filter. Absent means match every checkpoint in the range
`options`	QueryOptions	No	`limit`, `after`, `before`, `ordering`. The server applies its own default and maximum item limit

Response (stream):

Field	Type	Description
`checkpoint`	Checkpoint	One matching checkpoint. Unset on progress-only and terminal frames
`watermark`	Watermark	Safe resume cursor for this frame. Present on every frame
`end`	QueryEnd	Set exactly once on the final frame; carries the stop reason (item limit, scan limit, checkpoint bound, cursor bound, or ledger tip)

grpcurl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -import-path proto \
  -proto sui/rpc/v2/ledger_service.proto \
  -d '{"start_checkpoint": 1000000, "options": {"limit": 10}}' \
  sui-mainnet.g.alchemy.com:443 \
  sui.rpc.v2.LedgerService/ListCheckpoints

To paginate, pass the last received watermark.cursor back on the next request as options.after (ascending) or options.before (descending). Watermarks never regress in the requested ordering but consecutive frames may repeat the same cursor.

Streams executed transactions matching the provided filter over a checkpoint range. Same shape as ListCheckpoints, one transaction per frame.

Request:

Field	Type	Required	Description
`read_mask`	FieldMask	No	Fields to include on each transaction
`start_checkpoint`	uint64	No	Inclusive lower bound. Defaults to genesis
`end_checkpoint`	uint64	No	Exclusive upper bound. Defaults to the current indexed tip
`filter`	TransactionFilter	No	DNF filter over indexed transaction dimensions (`sender`, `affected_address`, `affected_object`, `move_call`, `emit_module`, `event_type`, `event_stream_head`, `package_write`). Absent means match every transaction in the range
`options`	QueryOptions	No	`limit`, `after`, `before`, `ordering`

Response (stream):

Field	Type	Description
`transaction`	ExecutedTransaction	One matching transaction. Unset on progress-only and terminal frames
`watermark`	Watermark	Safe resume cursor for this frame
`end`	QueryEnd	Set exactly once on the final frame; carries the stop reason

grpcurl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -import-path proto \
  -proto sui/rpc/v2/ledger_service.proto \
  -d '{"start_checkpoint": 1000000, "options": {"limit": 10}}' \
  sui-mainnet.g.alchemy.com:443 \
  sui.rpc.v2.LedgerService/ListTransactions

Streams events matching the provided filter over a checkpoint range. Same shape as ListTransactions, one event per frame.

Request:

Field	Type	Required	Description
`read_mask`	FieldMask	No	Fields to include on each event
`start_checkpoint`	uint64	No	Inclusive lower bound. Defaults to genesis
`end_checkpoint`	uint64	No	Exclusive upper bound. Defaults to the current indexed tip
`filter`	EventFilter	No	DNF filter over indexed event dimensions (`sender`, `emit_module`, `event_type`, `event_stream_head`). Absent means match every event in the range
`options`	QueryOptions	No	`limit`, `after`, `before`, `ordering`

Response (stream):

Field	Type	Description
`event`	Event	One matching event. Unset on progress-only and terminal frames
`watermark`	Watermark	Safe resume cursor for this frame
`end`	QueryEnd	Set exactly once on the final frame; carries the stop reason

grpcurl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -import-path proto \
  -proto sui/rpc/v2/ledger_service.proto \
  -d '{"start_checkpoint": 1000000, "options": {"limit": 10}}' \
  sui-mainnet.g.alchemy.com:443 \
  sui.rpc.v2.LedgerService/ListEvents