SubscriptionService.SubscribeCheckpoints
Subscribe to the stream of checkpoints.
The stream begins at the latest executed checkpoint as seen by the server and yields checkpoints matching the filter as they are executed. A checkpoint matches if any transaction it contains satisfies the filter.
Endpoint
| Network | Host | Authentication |
|---|---|---|
| Mainnet | mainnet-grpc.inodra.com:443 | x-api-key metadata |
| Testnet | testnet-grpc.inodra.com:443 | x-api-key metadata |
Full method name: sui.rpc.v2.SubscriptionService/SubscribeCheckpoints. Server-streaming: the response is a stream of messages. Get a key from the dashboard; the same key works on every protocol.
Request: SubscribeCheckpointsRequest
Request message for SubscriptionService.SubscribeCheckpoints.
| Field | Type | Description |
|---|---|---|
read_mask | google.protobuf.FieldMask | Optional. Mask for specifying which parts of the Checkpoint should be returned (e.g. summary, contents, signatures). cursor is always populated and is not subject to the mask. |
filter | TransactionFilter | Optional. DNF filter over indexed transaction dimensions. A checkpoint matches if any transaction it contains satisfies the filter. If absent, every checkpoint is streamed. |
Response: SubscribeCheckpointsResponse
Response message for SubscriptionService.SubscribeCheckpoints. A checkpoint stream's position is checkpoint-granular, so the cursor sequence number stands in for the Watermark message the other subscription responses carry. Progress-only frames (with checkpoint unset) occur only on filtered streams: on an unfiltered stream every frame carries both fields, in order and without gaps.
| Field | Type | Description |
|---|---|---|
cursor | uint64 | Required. The checkpoint sequence number the stream has fully covered, inclusive: every matching checkpoint from the stream's start position through cursor has been delivered. Present on every frame and advances monotonically. |
checkpoint | Checkpoint | The matching checkpoint. Unset when this frame only advances the cursor past non-matching checkpoints. |
Checkpoint
| Field | Type | Description |
|---|---|---|
sequence_number | uint64 | The height of this checkpoint. |
digest | string | The digest of this Checkpoint's CheckpointSummary. |
summary | CheckpointSummary | The CheckpointSummary for this checkpoint. |
signature | ValidatorAggregatedSignature | An aggregated quorum signature from the validator committee that certified this checkpoint. |
contents | CheckpointContents | The CheckpointContents for this checkpoint. |
transactions | repeated ExecutedTransaction | List of transactions included in this checkpoint. |
objects | ObjectSet | Set of objects either referenced as inputs or produced as outputs by transactions included in this checkpoint. In order to benefit from deduplication of objects that appear in multiple transactions in this checkpoint, objects will only be present here and the transactions.objects field will not be populated. |
grpcurl
grpcurl -H "x-api-key: YOUR_API_KEY" \
-d '{
"read_mask": {
"paths": [
"sequence_number",
"digest"
]
}
}' \
mainnet-grpc.inodra.com:443 \
sui.rpc.v2.SubscriptionService/SubscribeCheckpointsServer reflection is enabled, so no proto files are needed for grpcurl. Field masks are written as {"paths": [...]}.
TypeScript
import { GrpcWebFetchTransport, SuiGrpcClient } from '@mysten/sui/grpc'
const transport = new GrpcWebFetchTransport({
baseUrl: 'https://mainnet-grpc.inodra.com',
meta: { 'x-api-key': process.env.INODRA_API_KEY! }
})
const client = new SuiGrpcClient({ network: 'mainnet', transport })
const call = client.subscriptionService.subscribeCheckpoints({
readMask: { paths: ['sequence_number', 'digest'] }
})
for await (const frame of call.responses) {
console.log(frame.checkpoint?.sequenceNumber)
}@mysten/sui v2 has no typed method for this RPC, so the sample calls the generated client.subscriptionService service client. Install with npm install @mysten/sui and set INODRA_API_KEY. The gRPC gateway guide covers native gRPC transport for backends.
Credits
Billed by volume: 5 credits to open the stream, then 1 credit per 50 KB of encoded message with a 1-credit minimum per message (20 credits per MB). A full mainnet checkpoint without a mask is about 400 KB, roughly 8 credits; a read_mask that keeps only what you need brings a message down to the minimum. See credits and billing for the full table.