LedgerService.ListEvents
List events matching the provided filters.
Events are returned in ascending or descending packed event sequence order according to the query options ordering.
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.LedgerService/ListEvents. Server-streaming: the response is a stream of messages. Get a key from the dashboard; the same key works on every protocol.
Request: ListEventsRequest
Request message for LedgerService.ListEvents.
| Field | Type | Description |
|---|---|---|
read_mask | google.protobuf.FieldMask | Optional. Mask for specifying which parts of the Event should be returned. |
start_checkpoint | uint64 | Optional. Start of the checkpoint range to query (inclusive). Defaults to genesis. |
end_checkpoint | uint64 | Optional. End of the checkpoint range to query (exclusive). Defaults to the current indexed ledger tip. |
filter | EventFilter | Optional. DNF filter over indexed dimensions. If absent, all events in the range are returned. |
options | QueryOptions | Optional cursor-bounded query options. If unspecified, reads in ascending order with the default item limit. The server enforces a maximum item limit and silently coerces larger values down to it. To paginate, pass the last received Watermark.cursor as options.after (ascending) or options.before (descending) on the next request. |
start_transaction_index | uint64 | Optional. Transaction position within start_checkpoint at which the query starts (inclusive): within start_checkpoint, only events of transactions whose Event.transaction_index is at least this value are returned. Unset starts at the beginning of start_checkpoint. An index at or past the checkpoint's transaction count starts at the next checkpoint, ignoring start_event_index. Requires start_checkpoint. When this position leaves events of start_checkpoint out, a descending query does not report that checkpoint as covered in Watermark.checkpoint. Combines with options.after by intersection: the query starts at whichever of the two is later in ledger order. Servers that predate this field ignore it and start at the beginning of start_checkpoint, so clients must still drop events before this position themselves. |
start_event_index | uint32 | Optional. Event position within the transaction at start_transaction_index at which the query starts (inclusive): within that transaction, only events whose Event.event_index is at least this value are returned. Unset starts at the transaction's first event. An index past the transaction's last event starts at the next transaction. Requires start_transaction_index. Servers that predate this field ignore it, as for start_transaction_index. |
end_transaction_index | uint64 | Optional. Transaction position within the last checkpoint of the range, end_checkpoint - 1, at which the query ends (exclusive): within that checkpoint, only events of transactions whose Event.transaction_index is below this value are returned, plus, with end_event_index, the events of the transaction at this index that precede it. Unset ends after the whole checkpoint. An index at or past the checkpoint's transaction count ends after the whole checkpoint. Requires end_checkpoint. A query that stops at this position ends with QUERY_END_REASON_CHECKPOINT_BOUND. When this position leaves events of that checkpoint out, an ascending query does not report it as covered in Watermark.checkpoint. Combines with options.before by intersection: the query ends at whichever of the two is earlier in ledger order. Servers that predate this field ignore it and return the whole checkpoint, so clients must still drop events at or after this position themselves. |
end_event_index | uint32 | Optional. Event position within the transaction at end_transaction_index at which the query ends (exclusive): events of that transaction whose Event.event_index is below this value are also returned. Unset, like 0, returns none of the transaction's events. An index past the transaction's last event returns all of them. Requires end_transaction_index. Servers that predate this field ignore it, as for end_transaction_index. |
Response: ListEventsResponse
Response message for LedgerService.ListEvents. Every frame carries a watermark with a safe resume cursor. A frame with event set delivers one matching item; a frame without it reports scan progress or terminal completion. Watermarks never regress in the requested ordering but may repeat. end is set exactly once, on the final frame of a successful stream. For QUERY_END_REASON_ITEM_LIMIT, that frame also carries the final item. For every other end reason, the final frame has no event payload.
| 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. A ScanLimit terminal watermark may repeat the previous frame's cursor when its authoritative scan frontier was already emitted. |
end | QueryEnd | Set exactly once, on the final frame of a successful query stream. |
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"
}
}
]
}
]
},
"options": {
"limit": 5,
"ordering": "ORDERING_DESCENDING"
}
}' \
mainnet-grpc.inodra.com:443 \
sui.rpc.v2.LedgerService/ListEventsServer 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 { events, endCursor } = await client.listEvents({
filter: {
eventType:
'0x0000000000000000000000000000000000000000000000000000000000000003::validator::StakingRequestEvent'
},
limit: 5,
order: 'descending'
})
console.log(events, endCursor)Uses the typed SuiGrpcClient method from @mysten/sui v2 that calls this RPC. Install with npm install @mysten/sui and set INODRA_API_KEY. The gRPC gateway guide covers native gRPC transport for backends.
Credits
1 credit to open the stream, then 2 credits per streamed message, including watermark-only progress messages and the final message. See credits and billing for the full table.
JSON-RPC equivalent
Replaces suix_queryEvents. The JSON-RPC to gRPC migration guide has before and after code for the common calls.
Related
- LedgerService overview and the gRPC gateway
- LedgerService.GetServiceInfo
- LedgerService.GetObject
- LedgerService.BatchGetObjects
- LedgerService.GetTransaction
- LedgerService.BatchGetTransactions
- LedgerService.GetCheckpoint
- LedgerService.GetEpoch
- LedgerService.ListCheckpoints
- LedgerService.ListTransactions
- Proto definition on GitHub