Skip to main content

getEvents

Clients can request a filtered list of events emitted by a given ledger range.

Soroban-RPC will support querying within a maximum 24 hours of recent ledgers.

Note, this could be used by the client to only prompt a refresh when there is a new ledger with relevant events. It should also be used by backend Dapp components to "ingest" events into their own database for querying and serving.

If making multiple requests, clients should deduplicate any events received, based on the event's unique id field. This prevents double-processing in the case of duplicate events being received.

By default soroban-rpc retains the most recent 24 hours of events.

Parameters​

  • startLedger: <string> - Stringified ledger sequence number to fetch events after (inclusive). This method will return an error if startLedger is less than the oldest ledger stored in this node, or greater than the latest ledger seen by this node. If a cursor is included in the request, startLedger must be omitted.
  • filters: <object[]> - List of filters for the returned events. Events matching any of the filters are included. To match a filter, an event must match both a contractId and a topic. Maximum 5 filters are allowed per request.
    • type: <string> - (optional) A comma separated list of event types (system, contract, or diagnostic) used to filter events. If omitted, all event types are included.
    • contractIds: <string[]> - (optional) List of contract ids to query for events. If omitted, return events for all contracts. Maximum 5 contract IDs are allowed per request.
    • topics: <TopicFilter[]> - (optional) List of topic filters. If omitted, query for all events. If multiple filters are specified, events will be included if they match any of the filters. Maximum 5 filters are allowed per request.
      • A TopicFilter is SegmentMatcher[]
        • The list can be 1-4 SegmentMatchers long.
      • A SegmentMatcher is one of the following:
        • For an exact segment match, a string containing base64-encoded ScVal
        • For a wildcard single-segment match, the string "*", matches exactly one segment.
      • Examples of matching token transfer events. Events are emitted here: rs-soroban-env/event.rs at 924d86cacd58b8a162344bfe0ab37d9668f5d629. I've decoded the base64-encoded ScVals for easier reading (both the symbols and addresses). In real usage, the ScSymbol("transfer").toXdr().toString("base64"), and ScBinary(pubkeyBytes).toXdr().toString("base64"), would be base64 encoded strings for exact matches. For example:
        • [ScSymbol("transfer"), "*", "*"]
          • Matches any token transfer events
        • [ScSymbol("transfer"), "*", "GABC...123"]
          • Matches any token transfer events to recipient: GABC...123
        • [ScSymbol("transfer"), "GDEF...456", "GABC...123"]
          • Matches only token transfers from GDEF...456 to GABC...123.
  • pagination: <PaginationOptions> - See "Pagination"

Returns​

  • <object>
    • latestLedger: <string> - Stringified-number of the current latest ledger observed by the node when this response was generated.
    • events: <object[]>
      • ledger: <string> - String-ified sequence number of the ledger.
      • ledgerClosedAt: <string> - ISO8601 timestamp of the ledger closing time.
      • contractId: <string> - ID of the emitting contract.
      • id: <string> - Unique identifier for this event.
      • pagingToken: <string> - Duplicate of id field, but in the standard place for pagination tokens.
      • inSuccessfulContractCall: <boolean> - If true the event was emitted during a successful contract call.
      • topic: <xdr.ScVal[]> - List containing the topic this event was emitted with.
      • value: <object> - List containing the topic this event was emitted with.
        • xdr: <xdr.ScVal> - The emitted body value of the event (serialized in a base64 string).

Examples​

The following examples query the asset contract for the native token, searching for any transfers that take place (up to 100 results).

note

The examples below only returns two transfer events that took place to/from the same account. In the real-world, you would expect far more results.

Request​

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getEvents",
  "params": {
    "startLedger": "227000",
    "filters": [
      {
        "type": "contract",
        "contractIds": [
          "d93f5c7bb0ebc4a9c8f727c5cebc4e41194d38257e1d0d910356b43bfc528813"
        ],
        "topics": [
          ["AAAABQAAAAh0cmFuc2Zlcg==", "*", "*"]
        ]
      }
    ],
    "pagination": {
      "limit": 100
    }
  }
}

Response​

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "latestLedger": "230473",
    "events": [
      {
        "type": "contract",
        "ledger": "230010",
        "ledgerClosedAt": "2023-01-23T18:54:41Z",
        "contractId": "d93f5c7bb0ebc4a9c8f727c5cebc4e41194d38257e1d0d910356b43bfc528813",
        "id": "0000987885427757056-0000000001",
        "pagingToken": "0000987885427757056-0000000001",
        "inSuccessfulContractCall": true,
        "topic": [
          "AAAABQAAAAh0cmFuc2Zlcg==",
          "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o=",
          "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o="
        ],
        "value": {
          "xdr": "AAAABAAAAAEAAAAFAAAAAAABhqAAAAAAAAAAAA=="
        }
      },
      {
        "type": "contract",
        "ledger": "230170",
        "ledgerClosedAt": "2023-01-23T19:08:37Z",
        "contractId": "d93f5c7bb0ebc4a9c8f727c5cebc4e41194d38257e1d0d910356b43bfc528813",
        "id": "0000988572622524416-0000000001",
        "pagingToken": "0000988572622524416-0000000001",
        "inSuccessfulContractCall": true,
        "topic": [
          "AAAABQAAAAh0cmFuc2Zlcg==",
          "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o=",
          "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o="
        ],
        "value": {
          "xdr": "AAAABAAAAAEAAAAFAAAAAAAHoSAAAAAAAAAAAA=="
        }
      }
    ]
  }
}