# Objects and ledger

> Sui gRPC LedgerService API reference

> For the complete documentation index, see [llms.txt](/docs/llms.txt).

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

## GetServiceInfo

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 |

```bash cURL
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
```

***

## GetObject

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 |

```bash cURL
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
```

***

## BatchGetObjects

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` |

```bash cURL
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
```

***

## GetTransaction

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 |

```bash cURL
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
```

***

## BatchGetTransactions

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` |

```bash cURL
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
```

***

## GetCheckpoint

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 |

```bash cURL
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
```

***

## GetEpoch

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 |

```bash cURL
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
```

***

## ListCheckpoints

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) |

```bash cURL
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
```

<Note>
  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.
</Note>

***

## ListTransactions

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 |

```bash cURL
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
```

***

## ListEvents

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 |

```bash cURL
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
```