SubscriptionService.SubscribeEvents
Subscribe to the stream of events.
The stream begins at the latest executed checkpoint as seen by the server and yields events matching the filter as they are emitted.
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/SubscribeEvents. Server-streaming: the response is a stream of messages. Get a key from the dashboard; the same key works on every protocol.
Request: SubscribeEventsRequest
Request message for SubscriptionService.SubscribeEvents.
| Field | Type | Description |
|---|---|---|
read_mask | google.protobuf.FieldMask | Optional. Mask for specifying which parts of the Event should be returned. |
filter | EventFilter | Optional. DNF filter over indexed dimensions. If absent, every event is streamed. |
Response: SubscribeEventsResponse
Response message for SubscriptionService.SubscribeEvents. Mirrors ListEventsResponse, except there is no end field: a subscription stream has no successful end.
| Field | Type | Description |
|---|---|---|
event | Event | One matching event. Its ledger position -- containing checkpoint, emitting transaction digest and offset, and index within that transaction's event list -- is reported by the corresponding fields on Event. |
watermark | Watermark | Progress watermark as of this frame. Present on every frame. |
Event
An event.
| Field | Type | Description |
|---|---|---|
package_id | string | Package ID of the top-level function invoked by a MoveCall command that triggered this event to be emitted. |
module | string | Module name of the top-level function invoked by a MoveCall command that triggered this event to be emitted. |
sender | string | Address of the account that sent the transaction where this event was emitted. |
event_type | string | The type of the event emitted. |
contents | Bcs | BCS serialized bytes of the event. |
json | google.protobuf.Value | JSON rendering of the event. |
checkpoint | uint64 | The sequence number of the checkpoint that includes the transaction that emitted this event. Populated when the event is delivered on its own (for example via LedgerService.ListEvents); left unset when the event is carried inside its transaction's events list, where the enclosing ExecutedTransaction already provides this context. |
transaction_digest | string | The digest of the transaction that emitted this event. |
transaction_index | uint64 | Zero-based position of the emitting transaction within its containing checkpoint. For clients verifying authenticated event streams this index is part of the BCS-encoded EventCommitment leaf used to construct the per-checkpoint merkle root. |
event_index | uint32 | Zero-based index of this event within its transaction's event list. |
Watermark
Progress of a scan, carried on every response frame, whether or not the frame delivers a matching item. Watermarks never regress in the requested ordering, but consecutive frames may carry the same watermark when additional work does not advance the safe resume frontier. A watermark has two parts:
- The resume point, in two forms:
cursor, opaque, for the server, andcursor_position, in ledger coordinates, for clients to order frames and drop duplicates. - Coverage:checkpoint, the boundary checkpoint the scan has proven fully covered. It trails the resume point. To continue in the same direction, set the request's start (ascending) or end (descending) atcursor_position. To read in the other direction, set the other bound atcursor_positionfrom a frame without an item; from a frame with an item, start a page after the item at its key with the finest index incremented, or end a page before it at its key. In both cases passcursorasoptions.afterwith a start and asoptions.beforewith an end.
| Field | Type | Description |
|---|---|---|
cursor | bytes | Opaque cursor at the resume point. Set on every watermark. Use as options.after (ascending) or options.before (descending) on the next request to resume from here. The most recently received cursor is always the safe resume point. Pass cursors back unchanged; never compare or inspect them. Cursors that differ can name the same point, and their encoding may change. |
checkpoint | uint64 | The inclusive boundary checkpoint that the scan has fully covered within the request's effective interval, in the request's ordering direction: an ascending scan has emitted every matching item in the interval at checkpoints <= checkpoint (strictly greater ones may still hold matches); a descending scan has emitted every matching item in the interval at checkpoints >= checkpoint. This boundary never regresses in the scan direction, but it may repeat while the cursor advances. Unset until the scan's first checkpoint is fully covered. For example, a scan resumed from a cursor that lands mid-checkpoint leaves this unset until the next checkpoint boundary in the scan direction is fully covered. A watermark still has a valid resume cursor while this field is unset. |
cursor_position | LedgerPosition | The resume point in ledger coordinates. Set on every watermark by servers that support it. Ascending, every match from the request's start up to (excluding) cursor_position has been delivered. Descending, every match from cursor_position up to (excluding) the request's end has been delivered. On a frame that carries an item, ascending, it is the boundary just past the item, so it is not the item's own key: it is that key with its finest index incremented (event_index for events, transaction_index for transactions, checkpoint for checkpoints). Descending, it is the boundary just before the item, which is the item's key. It never moves before the request's start (ascending) or past its end (descending), so an ascending request that starts beyond what the server has indexed gets its start echoed back: the resume point says where the client is, not where the ledger is. cursor may then name an earlier point; bounds intersect, so resuming with both starts at cursor_position. |
grpcurl
grpcurl -H "x-api-key: YOUR_API_KEY" \
-d '{
"read_mask": {
"paths": [
"package_id",
"module",
"event_type"
]
},
"filter": {
"terms": [
{
"literals": [
{
"event_type": {
"event_type": "0x0000000000000000000000000000000000000000000000000000000000000003::validator::StakingRequestEvent"
}
}
]
}
]
}
}' \
mainnet-grpc.inodra.com:443 \
sui.rpc.v2.SubscriptionService/SubscribeEventsServer 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.subscribeEvents({
readMask: { paths: ['package_id', 'module', 'event_type'] },
filter: {
terms: [
{
literals: [
{
negated: false,
predicate: {
oneofKind: 'eventType',
eventType: {
eventType:
'0x0000000000000000000000000000000000000000000000000000000000000003::validator::StakingRequestEvent'
}
}
}
]
}
]
}
})
for await (const frame of call.responses) {
if (frame.event) console.log(frame.event.eventType)
}@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). Messages that carry only a watermark are free. The stream also pays for connection time, like a Warp stream: 4 credits per 5 seconds (about 48 per minute). See credits and billing for the full table.