---
title: StreamEventsRequest
description: StreamEventsRequest subscribes to chain events.
source_url:
  html: https://thru.org/docs/api-ref/grpc/messages/thru/services/v1/stream-events-request/
  md: https://thru.org/docs/api-ref/grpc/messages/thru/services/v1/stream-events-request.md
---

# StreamEventsRequest

StreamEventsRequest subscribes to chain events.

Filter expressions support the following params:

- params.prefix (bytes): Byte prefix for payload filtering Example: bytesPrefix(event.payload, params.prefix)

- params.slot (int64): Slot number for comparison Example: event.slot >= params.slot

- params.u64 (int64): Generic 64-bit value for payload extraction Examples: first8Bytes(event.payload) == params.u64 first4Bytes(event.payload) == params.u64 first1Byte(event.payload) == params.u64

- params.signature (bytes|Signature|TsSignature): Signature for comparison Examples: event.signature.value == params.signature // bytes type bytesPrefix(event.signature.value, params.signature) Note: Signature and TsSignature types are auto-converted to bytes

- params.address (bytes|Pubkey|TaPubkey): Address/pubkey for comparison Examples: event.program.value == params.address // bytes type bytesPrefix(event.program.value, params.address) Note: Pubkey and TaPubkey types are auto-converted to bytes

- params.timestamp (int64): Timestamp in seconds for comparison Example: int(event.timestamp) > params.timestamp

Available event fields: event.event\_id (string), event.slot (uint64), event.payload (bytes), event.call\_idx (uint32), event.signature (Signature), event.signature.value (bytes), event.program (Pubkey), event.program.value (bytes), event.timestamp (Timestamp)

Note: Unlike ListEventsRequest in QueryService, StreamEventsRequest does NOT support: event.block\_offset, event.program\_idx, event.payload\_size, event.transaction\_signature

Available filter functions:

- has(field): Check if optional field exists Example: has(event.program) && has(event.signature)

- startsWith(string, prefix): Check if string starts with prefix Example: event.event\_id.startsWith(“ts”)

- bytesPrefix(bytes, prefix): Check if bytes start with prefix Examples: bytesPrefix(event.payload, b”\x01\x00\x00\x00\x00\x00\x00\x00”) bytesPrefix(event.payload, params.prefix) bytesPrefix(event.program.value, params.address) bytesPrefix(event.signature.value, params.signature)

- first1Byte(bytes): Extract first byte as uint Example: first1Byte(event.payload) == uint(1)

- first4Bytes(bytes): Extract first 4 bytes as little-endian uint32 Example: first4Bytes(event.payload) == uint(2)

- first8Bytes(bytes): Extract first 8 bytes as little-endian uint64 Example: first8Bytes(event.payload) == uint(6)

- uint(value): Convert value to uint for comparison

- int(value): Convert value to int (used for timestamps)

Filter expression examples:

1. Filter by payload type using first1Byte (MESSAGE event type = 1): Expression: “first1Byte(event.payload) == uint(1)”

2. Filter by payload type using first4Bytes (COUNTER event type = 2): Expression: “first4Bytes(event.payload) == uint(2)”

3. Filter by payload type using first8Bytes (PATTERN event type = 6): Expression: “first8Bytes(event.payload) == uint(6)”

4. Filter by payload prefix with params: Expression: “bytesPrefix(event.payload, params.prefix)” Params: {“prefix”: \<bytes, e.g., 0x01000000…>}

5. Filter by slot using params: Expression: “event.slot >= params.slot” Params: {“slot”: 1000}

6. Filter by program address (exact match): Expression: “event.program.value == params.address” Params: {“address”: <32-byte pubkey as bytes, Pubkey, or TaPubkey>}

7. Filter by program address (prefix match): Expression: “bytesPrefix(event.program.value, params.address)” Params: {“address”: \<pubkey prefix bytes>}

8. Filter by transaction signature (exact match): Expression: “event.signature.value == params.signature” Params: {“signature”: <64-byte signature as bytes, Signature, or TsSignature>}

9. Filter by transaction signature (prefix match): Expression: “bytesPrefix(event.signature.value, params.signature)” Params: {“signature”: \<signature prefix bytes>}

10. Filter by call\_idx (0 = main program, 1+ = CPI calls): Expression: “event.call\_idx == uint(0)” Expression: “event.call\_idx == uint(1)”

11. Filter by event\_id prefix: Expression: “event.event\_id.startsWith(“ts”)”

12. Filter by timestamp (events in last hour): Expression: “has(event.timestamp) && int(event.timestamp) > int(1700000000)”

13. Filter by timestamp using params: Expression: “has(event.timestamp) && int(event.timestamp) > params.timestamp” Params: {“timestamp”: 1700000000}

14. Check field existence: Expression: “has(event.program) && has(event.signature)”

15. Filter using params.u64 with first8Bytes: Expression: “first8Bytes(event.payload) == params.u64” Params: {“u64”: 6}

16. Filter using params.u64 with first4Bytes: Expression: “first4Bytes(event.payload) == params.u64” Params: {“u64”: 2}

17. Filter using params.u64 with first1Byte: Expression: “first1Byte(event.payload) == params.u64” Params: {“u64”: 1}

18. Combined filter (slot + payload type + call\_idx): Expression: “event.slot > uint(1000) && first1Byte(event.payload) == uint(1) && event.call\_idx == uint(0)”

19. Combined filter (call\_idx + program address): Expression: “event.call\_idx == uint(1) && event.program.value == params.address” Params: {“address”: <32-byte CPI target program pubkey>}

20. Timestamp range filter: Expression: “has(event.timestamp) && int(event.timestamp) > int(1700000000) && int(event.timestamp) < int(1700100000)”

**Package:** `thru.services.v1`

## Fields

| Field | Type | # | Description |
| - | - | - | - |
| `filter` | [`thru.common.v1.Filter`](https://thru.org/docs/api-ref/grpc/messages/thru/common/v1/filter.md) | 1 · optional | |