Parameters

start_checkpoint

string

Optional. Start of the checkpoint range to query (inclusive). Defaults to genesis.

end_checkpoint

string

Optional. End of the checkpoint range to query (exclusive). Defaults to the current indexed ledger tip.

read_mask

object

Optional. Mask for specifying which parts of the Checkpoint should be returned (e.g. summary, contents, signature).

paths

array<string>

List of fields to include, such as 'sequence_number', 'digest', 'summary'.

filter

object

Optional. DNF filter over indexed transaction dimensions. A checkpoint matches if any transaction it contains satisfies the filter. If absent, all checkpoints in the range are returned.

terms

array

Terms are ORed together; each term is an AND of signed predicate literals (sender, affected_address, move_call, etc.).

options

object

Optional cursor-bounded query options. If unspecified, reads in ascending order with the default item limit.

limit

integer

The maximum number of items to return. The server enforces a maximum item limit and silently coerces larger values down to it.

after

string

Opaque exclusive lower bound cursor. Pass the last received watermark.cursor here to resume an ascending scan.

before

string

Opaque exclusive upper bound cursor. Pass the last received watermark.cursor here to resume a descending scan.

ordering

string

ORDERING_ASCENDING (default) or ORDERING_DESCENDING.

Returns

checkpoint

object

One matching checkpoint. Set on frames that deliver an item; unset on progress/terminal frames.

sequenceNumber

string

The height of this checkpoint.

digest

string

The digest of this checkpoint's summary.

summary

object

The CheckpointSummary for this checkpoint, present when included in read_mask.

watermark

object

Progress watermark present on every frame. Use cursor as options.after/options.before on the next request to resume the scan.

cursor

string

Opaque resume cursor at this scan position.

checkpoint

string

The checkpoint fully covered by the scan so far, in the scan direction. Unset until the first checkpoint is fully covered.

end

object

Set exactly once, on the final frame of a successful stream.

reason

string

Why the stream 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.

Request

1
grpcurl \
2
  -import-path . \
3
  -proto sui/rpc/v2/ledger_service.proto \
4
  -H "x-token: YOUR_TOKEN_VALUE" \
5
  -d '{
6
    "start_checkpoint": "306133000",
7
    "read_mask": {
8
      "paths": [
9
        "sequence_number",
10
        "digest",
11
        "summary"
12
      ]
13
    },
14
    "options": {
15
      "limit": 3
16
    }
17
  }' \
18
  docs-demo.sui-mainnet.quiknode.pro:9000 \
19
  sui.rpc.v2.LedgerService/ListCheckpoints
20

1
grpcurl \
2
  -import-path . \
3
  -proto sui/rpc/v2/ledger_service.proto \
4
  -H "x-token: YOUR_TOKEN_VALUE" \
5
  -d '{
6
    "start_checkpoint": "306133000",
7
    "read_mask": {
8
      "paths": [
9
        "sequence_number",
10
        "digest",
11
        "summary"
12
      ]
13
    },
14
    "options": {
15
      "limit": 3
16
    }
17
  }' \
18
  docs-demo.sui-mainnet.quiknode.pro:9000 \
19
  sui.rpc.v2.LedgerService/ListCheckpoints
20

1
package main
2

3
import (
4
	"context"
5
	"crypto/tls"
6
	"encoding/json"
7
	"fmt"
8
	"io"
9
	"log"
10
	"time"
11

12
	"google.golang.org/grpc"
13
	"google.golang.org/grpc/credentials"
14
	"google.golang.org/protobuf/encoding/protojson"
15
	"google.golang.org/protobuf/types/known/fieldmaskpb"
16

17
	pb "sui-grpc/sui/rpc/v2" // Your Generated .pb.go files path
18
)
19

20
// Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
21
// For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
22
// endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
23
// token will be : abcde123456789
24

25
var (
26
	token    = "YOUR_TOKEN_NUMBER"
27
	endpoint = "YOUR_QN_ENDPOINT:9000"
28
)
29

30
// Auth structure for x-token
31
type auth struct {
32
	token string
33
}
34

35
func (a *auth) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
36
	return map[string]string{"x-token": a.token}, nil
37
}
38
func (a *auth) RequireTransportSecurity() bool {
39
	return true
40
}
41

42
func main() {
43
	creds := credentials.NewTLS(&tls.Config{})
44
	opts := []grpc.DialOption{
45
		grpc.WithTransportCredentials(creds),
46
		grpc.WithPerRPCCredentials(&auth{token}),
47
	}
48

49
	conn, err := grpc.Dial(endpoint, opts...)
50
	if err != nil {
51
		log.Fatalf("Failed to connect: %v", err)
52
	}
53
	defer conn.Close()
54

55
	client := pb.NewLedgerServiceClient(conn)
56

57
	startCheckpoint := uint64(306133000)
58
	limit := uint32(3)
59

60
	req := &pb.ListCheckpointsRequest{
61
		StartCheckpoint: &startCheckpoint,
62
		ReadMask: &fieldmaskpb.FieldMask{
63
			Paths: []string{"sequence_number", "digest", "summary"},
64
		},
65
		Options: &pb.QueryOptions{
66
			Limit: &limit,
67
		},
68
	}
69

70
	// ListCheckpoints is bounded by start/end checkpoint and options.limit, so the
71
	// stream terminates on its own once the QueryEnd frame is sent.
72
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
73
	defer cancel()
74

75
	stream, err := client.ListCheckpoints(ctx, req)
76
	if err != nil {
77
		log.Fatalf("ListCheckpoints failed: %v", err)
78
	}
79

80
	marshaler := protojson.MarshalOptions{
81
		UseProtoNames:   true,
82
		EmitUnpopulated: true,
83
		Indent:          "  ",
84
	}
85

86
	fmt.Println("Streaming checkpoints...")
87

88
	for {
89
		resp, err := stream.Recv()
90
		if err == io.EOF {
91
			fmt.Println("Stream ended")
92
			break
93
		}
94
		if err != nil {
95
			log.Fatalf("Stream error: %v", err)
96
		}
97

98
		jsonBytes, err := marshaler.Marshal(resp)
99
		if err != nil {
100
			log.Printf("Failed to marshal: %v", err)
101
			continue
102
		}
103

104
		var pretty map[string]interface{}
105
		if err := json.Unmarshal(jsonBytes, &pretty); err != nil {
106
			log.Printf("Failed to parse JSON: %v", err)
107
			continue
108
		}
109

110
		out, _ := json.MarshalIndent(pretty, "", "  ")
111
		fmt.Printf("Received frame:\n%s\n", string(out))
112

113
		if resp.GetEnd() != nil {
114
			fmt.Printf("Query ended: %s\n", resp.GetEnd().GetReason())
115
		}
116
	}
117
}
118

1
package main
2

3
import (
4
	"context"
5
	"crypto/tls"
6
	"encoding/json"
7
	"fmt"
8
	"io"
9
	"log"
10
	"time"
11

12
	"google.golang.org/grpc"
13
	"google.golang.org/grpc/credentials"
14
	"google.golang.org/protobuf/encoding/protojson"
15
	"google.golang.org/protobuf/types/known/fieldmaskpb"
16

17
	pb "sui-grpc/sui/rpc/v2" // Your Generated .pb.go files path
18
)
19

20
// Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
21
// For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
22
// endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
23
// token will be : abcde123456789
24

25
var (
26
	token    = "YOUR_TOKEN_NUMBER"
27
	endpoint = "YOUR_QN_ENDPOINT:9000"
28
)
29

30
// Auth structure for x-token
31
type auth struct {
32
	token string
33
}
34

35
func (a *auth) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
36
	return map[string]string{"x-token": a.token}, nil
37
}
38
func (a *auth) RequireTransportSecurity() bool {
39
	return true
40
}
41

42
func main() {
43
	creds := credentials.NewTLS(&tls.Config{})
44
	opts := []grpc.DialOption{
45
		grpc.WithTransportCredentials(creds),
46
		grpc.WithPerRPCCredentials(&auth{token}),
47
	}
48

49
	conn, err := grpc.Dial(endpoint, opts...)
50
	if err != nil {
51
		log.Fatalf("Failed to connect: %v", err)
52
	}
53
	defer conn.Close()
54

55
	client := pb.NewLedgerServiceClient(conn)
56

57
	startCheckpoint := uint64(306133000)
58
	limit := uint32(3)
59

60
	req := &pb.ListCheckpointsRequest{
61
		StartCheckpoint: &startCheckpoint,
62
		ReadMask: &fieldmaskpb.FieldMask{
63
			Paths: []string{"sequence_number", "digest", "summary"},
64
		},
65
		Options: &pb.QueryOptions{
66
			Limit: &limit,
67
		},
68
	}
69

70
	// ListCheckpoints is bounded by start/end checkpoint and options.limit, so the
71
	// stream terminates on its own once the QueryEnd frame is sent.
72
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
73
	defer cancel()
74

75
	stream, err := client.ListCheckpoints(ctx, req)
76
	if err != nil {
77
		log.Fatalf("ListCheckpoints failed: %v", err)
78
	}
79

80
	marshaler := protojson.MarshalOptions{
81
		UseProtoNames:   true,
82
		EmitUnpopulated: true,
83
		Indent:          "  ",
84
	}
85

86
	fmt.Println("Streaming checkpoints...")
87

88
	for {
89
		resp, err := stream.Recv()
90
		if err == io.EOF {
91
			fmt.Println("Stream ended")
92
			break
93
		}
94
		if err != nil {
95
			log.Fatalf("Stream error: %v", err)
96
		}
97

98
		jsonBytes, err := marshaler.Marshal(resp)
99
		if err != nil {
100
			log.Printf("Failed to marshal: %v", err)
101
			continue
102
		}
103

104
		var pretty map[string]interface{}
105
		if err := json.Unmarshal(jsonBytes, &pretty); err != nil {
106
			log.Printf("Failed to parse JSON: %v", err)
107
			continue
108
		}
109

110
		out, _ := json.MarshalIndent(pretty, "", "  ")
111
		fmt.Printf("Received frame:\n%s\n", string(out))
112

113
		if resp.GetEnd() != nil {
114
			fmt.Printf("Query ended: %s\n", resp.GetEnd().GetReason())
115
		}
116
	}
117
}
118

1
import * as grpc from '@grpc/grpc-js';
2
import * as protoLoader from '@grpc/proto-loader';
3
import * as path from 'path';
4

5
// Configuration
6
const PROTO_PATH = path.join(__dirname, 'protos/proto/sui/rpc/v2/ledger_service.proto');
7

8
// Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
9
// For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
10
// endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
11
// token will be : abcde123456789
12

13
const endpoint = 'docs-demo.sui-mainnet.quiknode.pro:9000';
14
const token = 'abcde123456789';
15

16
// Load protobuf definitions
17
const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
18
  keepCase: true,
19
  longs: String,
20
  enums: String,
21
  defaults: true,
22
  oneofs: true,
23
  includeDirs: [path.join(__dirname, 'protos/proto')],
24
});
25

26
const proto = grpc.loadPackageDefinition(packageDefinition) as any;
27
const LedgerService = proto.sui.rpc.v2.LedgerService;
28

29
// Create secure client
30
const client = new LedgerService(endpoint, grpc.credentials.createSsl());
31

32
// Add token metadata
33
const metadata = new grpc.Metadata();
34
metadata.add('x-token', token);
35

36
// Request payload
37
// ListCheckpoints is bounded by start/end_checkpoint and options.limit, so the
38
// stream ends on its own — no Ctrl+C handling needed.
39
const request = {
40
  start_checkpoint: '306133000',
41
  read_mask: {
42
    paths: ['sequence_number', 'digest', 'summary'],
43
  },
44
  options: {
45
    limit: 3,
46
  },
47
};
48

49
const call = client.ListCheckpoints(request, metadata);
50

51
console.log('Streaming checkpoints...');
52

53
call.on('data', (response: any) => {
54
  console.log('Received frame:', JSON.stringify(response, null, 2));
55
  if (response.end) {
56
    console.log('Query ended:', response.end.reason);
57
  }
58
});
59

60
call.on('error', (error: any) => {
61
  console.error('Stream error:', error);
62
});
63

64
call.on('end', () => {
65
  console.log('Stream ended');
66
});
67

1
import * as grpc from '@grpc/grpc-js';
2
import * as protoLoader from '@grpc/proto-loader';
3
import * as path from 'path';
4

5
// Configuration
6
const PROTO_PATH = path.join(__dirname, 'protos/proto/sui/rpc/v2/ledger_service.proto');
7

8
// Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
9
// For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
10
// endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
11
// token will be : abcde123456789
12

13
const endpoint = 'docs-demo.sui-mainnet.quiknode.pro:9000';
14
const token = 'abcde123456789';
15

16
// Load protobuf definitions
17
const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
18
  keepCase: true,
19
  longs: String,
20
  enums: String,
21
  defaults: true,
22
  oneofs: true,
23
  includeDirs: [path.join(__dirname, 'protos/proto')],
24
});
25

26
const proto = grpc.loadPackageDefinition(packageDefinition) as any;
27
const LedgerService = proto.sui.rpc.v2.LedgerService;
28

29
// Create secure client
30
const client = new LedgerService(endpoint, grpc.credentials.createSsl());
31

32
// Add token metadata
33
const metadata = new grpc.Metadata();
34
metadata.add('x-token', token);
35

36
// Request payload
37
// ListCheckpoints is bounded by start/end_checkpoint and options.limit, so the
38
// stream ends on its own — no Ctrl+C handling needed.
39
const request = {
40
  start_checkpoint: '306133000',
41
  read_mask: {
42
    paths: ['sequence_number', 'digest', 'summary'],
43
  },
44
  options: {
45
    limit: 3,
46
  },
47
};
48

49
const call = client.ListCheckpoints(request, metadata);
50

51
console.log('Streaming checkpoints...');
52

53
call.on('data', (response: any) => {
54
  console.log('Received frame:', JSON.stringify(response, null, 2));
55
  if (response.end) {
56
    console.log('Query ended:', response.end.reason);
57
  }
58
});
59

60
call.on('error', (error: any) => {
61
  console.error('Stream error:', error);
62
});
63

64
call.on('end', () => {
65
  console.log('Stream ended');
66
});
67

1
import grpc
2
import json
3
from google.protobuf.field_mask_pb2 import FieldMask
4
from google.protobuf.json_format import MessageToDict
5
from sui.rpc.v2 import ledger_service_pb2, ledger_service_pb2_grpc, query_options_pb2
6

7
def list_checkpoints():
8
    # Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
9
    # For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
10
    # endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
11
    # token will be : abcde123456789
12

13
    endpoint = 'docs-demo.sui-mainnet.quiknode.pro:9000';
14
    token = 'abcde123456789';
15

16
    channel = grpc.secure_channel(endpoint, grpc.ssl_channel_credentials())
17
    stub = ledger_service_pb2_grpc.LedgerServiceStub(channel)
18

19
    read_mask = FieldMask(paths=["sequence_number", "digest", "summary"])
20

21
    # ListCheckpoints is bounded by start/end_checkpoint and options.limit, so
22
    # the stream ends on its own once the server sends the QueryEnd frame.
23
    request = ledger_service_pb2.ListCheckpointsRequest(
24
        start_checkpoint=306133000,
25
        read_mask=read_mask,
26
        options=query_options_pb2.QueryOptions(limit=3)
27
    )
28

29
    metadata = [("x-token", token)]
30

31
    return stub.ListCheckpoints(request, metadata=metadata)
32

33
def parse_response_to_json(response):
34
    return json.dumps(
35
        MessageToDict(response, preserving_proto_field_name=True),
36
        indent=2
37
    )
38

39
def main():
40
    print("Streaming checkpoints...")
41

42
    try:
43
        response_stream = list_checkpoints()
44

45
        for response in response_stream:
46
            print("Received frame:")
47
            print(parse_response_to_json(response))
48
            if response.HasField("end"):
49
                reason = query_options_pb2.QueryEndReason.Name(response.end.reason)
50
                print(f"Query ended: {reason}")
51

52
        print("Stream ended")
53

54
    except grpc.RpcError as e:
55
        print(f"{e.code().name}: {e.details()}")
56

57
if __name__ == "__main__":
58
    main()
59

1
import grpc
2
import json
3
from google.protobuf.field_mask_pb2 import FieldMask
4
from google.protobuf.json_format import MessageToDict
5
from sui.rpc.v2 import ledger_service_pb2, ledger_service_pb2_grpc, query_options_pb2
6

7
def list_checkpoints():
8
    # Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
9
    # For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
10
    # endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
11
    # token will be : abcde123456789
12

13
    endpoint = 'docs-demo.sui-mainnet.quiknode.pro:9000';
14
    token = 'abcde123456789';
15

16
    channel = grpc.secure_channel(endpoint, grpc.ssl_channel_credentials())
17
    stub = ledger_service_pb2_grpc.LedgerServiceStub(channel)
18

19
    read_mask = FieldMask(paths=["sequence_number", "digest", "summary"])
20

21
    # ListCheckpoints is bounded by start/end_checkpoint and options.limit, so
22
    # the stream ends on its own once the server sends the QueryEnd frame.
23
    request = ledger_service_pb2.ListCheckpointsRequest(
24
        start_checkpoint=306133000,
25
        read_mask=read_mask,
26
        options=query_options_pb2.QueryOptions(limit=3)
27
    )
28

29
    metadata = [("x-token", token)]
30

31
    return stub.ListCheckpoints(request, metadata=metadata)
32

33
def parse_response_to_json(response):
34
    return json.dumps(
35
        MessageToDict(response, preserving_proto_field_name=True),
36
        indent=2
37
    )
38

39
def main():
40
    print("Streaming checkpoints...")
41

42
    try:
43
        response_stream = list_checkpoints()
44

45
        for response in response_stream:
46
            print("Received frame:")
47
            print(parse_response_to_json(response))
48
            if response.HasField("end"):
49
                reason = query_options_pb2.QueryEndReason.Name(response.end.reason)
50
                print(f"Query ended: {reason}")
51

52
        print("Stream ended")
53

54
    except grpc.RpcError as e:
55
        print(f"{e.code().name}: {e.details()}")
56

57
if __name__ == "__main__":
58
    main()
59

Don't have an account yet?

Create your Quicknode endpoint in seconds and start building

Get started for free