ListEvents - Sui

ListEvents. Streams events in a range, with optional filters.

ListEvents - sui [Value: 20CU]
Server-streaming. Lists events in a checkpoint range, optionally filtered by sender, emitting module or event type.
gRPC: sui.rpc.v2.LedgerService/ListEvents
Use cases

Use cases

  • Index protocol events
  • Track staking or DEX activity
  • Backfill events by range
Constraints

Constraints

  • Server-streaming response
  • Server caps the item limit
  • Filters use DNF terms and literals
Get started
Unlock Access to 100+ chains
Boost your app's speed and reliability with dRPC - get your access API key

Language

Request
Examples
grpcurl \
  -H "x-drpc-key: {API-KEY}" \
  -H "x-drpc-chain: sui" \
  -d '{
  "start_checkpoint": "1000000",
  "end_checkpoint": "1000100",
  "filter": {
    "terms": [{
      "literals": [{
        "event_type": { "event_type": "0x3::validator::StakingRequestEvent" }
      }]
    }]
  }
}' \
  grpc.drpc.live:443 \
  sui.rpc.v2.LedgerService/ListEvents
Copy
Response
200
{
  "event": {
    "sender": "0x94096a6a54129234237759c66e6ef1037224fb3102a0ae29d33b490281c8e4d5",
    "event_type": "0x3::validator::StakingRequestEvent",
    "json": {
      "amount": "1000000000",
      "epoch": "18",
      "pool_id": "0x4a5c7e1f2b3d4c6e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e",
      "staker_address": "0x94096a6a54129234237759c66e6ef1037224fb3102a0ae29d33b490281c8e4d5",
      "validator_address": "0x7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c"
    },
    "checkpoint": "1000053",
    "transaction_digest": "3ByWphQ5sAVojiTrTrGXGM5FmCVzpzYmhsjbhYESJtxp"
  },
  "watermark": {
    "cursor": "AAAAAAAPQnUAAAAAAAAAAwAAAAA=",
    "checkpoint": "1000053",
    "cursor_position": { "checkpoint": "1000053", "transaction_index": "17", "event_index": 2 }
  }
}
...
Copy

Request params

Parametersobject
object
read_maskstring
Optional. google.protobuf.FieldMask with the fields to return, as comma-separated paths. Defaults to `event_type`. Use `*` to return all fields.
start_checkpointstring
Optional. Start of the checkpoint range (inclusive). Defaults to genesis.
end_checkpointstring
Optional. End of the checkpoint range (exclusive). Defaults to the current indexed ledger tip.
filterobject
Optional. Filter in disjunctive normal form: `terms` (OR) of `literals` (AND). Each literal sets one predicate: `sender`, `emit_module`, `event_type` or `event_stream_head`, and optional `negated`.
optionsobject
Optional. Query options.
object
limitinteger
Maximum number of items to return. The server caps this value.
afterstring
Cursor (bytes, base64) to resume after, for ascending queries.
beforestring
Cursor (bytes, base64) to resume before, for descending queries.
orderingstring
`ORDERING_ASCENDING` (default) or `ORDERING_DESCENDING`.
start_transaction_indexstring
Optional. Transaction index within `start_checkpoint` to start from (inclusive). Requires `start_checkpoint`.
start_event_indexinteger
Optional. Event index within the start transaction to start from (inclusive). Requires `start_transaction_index`.
end_transaction_indexstring
Optional. Transaction index within the last checkpoint of the range to stop at (exclusive). Requires `end_checkpoint`.
end_event_indexinteger
Optional. Event index within the end transaction to stop at (exclusive). Requires `end_transaction_index`.

Response

200
A stream of frames. Each frame carries a watermark and, optionally, one event.

Response params

object
eventobject
One matching event. Not set on progress-only frames.
object
package_idstring
Package id of the top-level function invoked by the `MoveCall` that triggered the event.
modulestring
Module of the top-level function invoked by the `MoveCall` that triggered the event.
senderstring
Address of the account that sent the transaction that emitted the event.
event_typestring
Type of the event.
contentsobject
BCS-serialized event bytes.
jsonobject
JSON rendering of the event contents.
checkpointstring
Checkpoint that includes the emitting transaction. Set when the event is delivered on its own, as in ListEvents and SubscribeEvents.
transaction_digeststring
Digest of the transaction that emitted the event.
transaction_indexstring
Position of the emitting transaction within its checkpoint.
event_indexinteger
Index of the event within the transaction's events.
watermarkobject
Progress watermark, present on every frame.
object
cursorstring
Opaque resume cursor (bytes, base64), set on every watermark. Pass it back unchanged as `options.after` (ascending) or `options.before` (descending) to resume.
checkpointstring
Inclusive boundary checkpoint the scan has fully covered. Unset until the first checkpoint is fully covered.
cursor_positionobject
Resume point in ledger coordinates: `checkpoint`, `transaction_index`, `event_index`. Set by servers that support it.
endobject
Set exactly once, on the final frame of a successful stream. `reason`: `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`.
ListTransactionsState Service