getEvents method

Future<GetEventsResponse> getEvents(
  1. GetEventsRequest request
)

Retrieves contract events emitted within a specified ledger range.

Events are emitted by smart contracts during execution and provide a way to track contract activity. This method allows filtering events by contract, topic, and type.

Event retention period is network-dependent (typically 24 hours on public networks, but may vary by RPC provider configuration). Use pagination to handle large result sets.

Important: When making multiple requests, deduplicate events using their unique ID to prevent double-processing.

Parameters:

  • request GetEventsRequest with filters and pagination options

Returns: GetEventsResponse containing:

  • events: List of EventInfo objects matching the filter criteria
  • latestLedger: Latest ledger known to the server
  • cursor: Pagination cursor for next page

Throws:

  • Exception: If the RPC request fails

Example:

try {
  // Get all events from a specific contract
  final filter = EventFilter(
    contractIds: ['CABC...'],
    topics: [
      TopicFilter(['*', XdrSCVal.forSymbol('transfer').toBase64EncodedXdrString()])
    ],
  );

  final request = GetEventsRequest(
    startLedger: 1000,
    filters: [filter],
    paginationOptions: PaginationOptions(limit: 100),
  );

  final response = await server.getEvents(request);
  if (response.events != null) {
    for (final event in response.events!) {
      print('Event: ${event.id} at ledger ${event.ledger}');
      final value = event.valueXdr;
    }
  }
} catch (e) {
  print('Failed to fetch events: $e');
}

See also:

Implementation

Future<GetEventsResponse> getEvents(GetEventsRequest request) async {
  JsonRpcMethod getEvents =
      JsonRpcMethod("getEvents", args: request.getRequestArgs());
  dio.Response response = await _dio.post(_serverUrl,
      data: json.encode(getEvents), options: dio.Options(headers: _headers));
  if (enableLogging) {
    print("getEvents response: $response");
  }
  return GetEventsResponse.fromJson(response.data);
}