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.

Params

(3)

Please note that parameter structure within the request must contain named parameters as a by-name object, and not as positional arguments in a by-position array

1. startLedger (required)

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.

number

Sequence number of the ledger.

2. filters (required)

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.

array of:

<= 5 items

type

string

A comma separated list of event types (system, contract, or diagnostic) used to filter events. If omitted, all event types are included.

contractIds

array[string]

List of contract IDs to query for events. If omitted, return events for all contracts. Maximum 5 contract IDs are allowed per request.

<= 5 items

topics

array[array]

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.

<= 5 items

string

A SegmentMatcher is one of the following:Show all...

3. pagination

Pagination in soroban-rpc is similar to pagination in Horizon. See Pagination.

cursor

string

A string ID that points to a specific location in a collection of responses and is pulled from the paging_token value of a record. When a cursor is provided Soroban-RPC will not include the element whose id matches the cursor in the response. Only elements which appear after the cursor are included.

limit

number

The maximum number of records returned. The limit for getEvents can range from 1 to 10000 - an upper limit that is hardcoded in Soroban-RPC for performance reasons. If this argument isn't designated, it defaults to 100.

Result

(getEventsResult)

latestLedger

number

The sequence number of the latest ledger known to Soroban RPC at the time it handled the request.

events

array[object]

type

string

The type of event emission.

Allowed values:

contractdiagnosticsystem

ledger

number

Sequence number of the ledger in which this event was emitted.

ledgerClosedAt

string

ISO-8601 timestamp of the ledger closing time

contractId

string

StrKey representation of the contract address that emitted this event.

string

Unique identifier for this event.Show all...

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

array[string]

List containing the topic this event was emitted with.

>= 1 items<= 4 items

value

object

The data the event was broadcasting in the emitted event.

Examples

Example request to the getEvents method, filtering for transfer events for native Lumens, and limiting the number of returned events to 2.

Request

cURL
JavaScript
Python
JSON

curl -X POST \
-H 'Content-Type: application/json' \
-d '{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getEvents",
  "params": {
    "startLedger": 2530000,
    "filters": [
      {
        "type": "contract",
        "contractIds": [
          "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
        ],
        "topics": [
          [
            "AAAADwAAAAh0cmFuc2Zlcg==",
            "*",
            "*",
            "*"
          ]
        ]
      }
    ],
    "pagination": {
      "limit": 2
    }
  }
}' \
https://soroban-testnet.stellar.org:443 | jq

let requestBody = {
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getEvents",
  "params": {
    "startLedger": 2530000,
    "filters": [
      {
        "type": "contract",
        "contractIds": [
          "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
        ],
        "topics": [
          [
            "AAAADwAAAAh0cmFuc2Zlcg==",
            "*",
            "*",
            "*"
          ]
        ]
      }
    ],
    "pagination": {
      "limit": 2
    }
  }
}
let res = await fetch('https://soroban-testnet.stellar.org', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(requestBody),
})
let json = await res.json()
console.log(json)

import json, requests
res = requests.post('https://soroban-testnet.stellar.org', json={
    "jsonrpc": "2.0",
    "id": 8675309,
    "method": "getEvents",
    "params": {
        "startLedger": 2530000,
        "filters": [
            {
                "type": "contract",
                "contractIds": [
                    "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
                ],
                "topics": [
                    [
                        "AAAADwAAAAh0cmFuc2Zlcg==",
                        "*",
                        "*",
                        "*"
                    ]
                ]
            }
        ],
        "pagination": {
            "limit": 2
        }
    }
})
print(json.dumps(res.json(), indent=4))

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getEvents",
  "params": {
    "startLedger": 2530000,
    "filters": [
      {
        "type": "contract",
        "contractIds": [
          "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
        ],
        "topics": [
          [
            "AAAADwAAAAh0cmFuc2Zlcg==",
            "*",
            "*",
            "*"
          ]
        ]
      }
    ],
    "pagination": {
      "limit": 2
    }
  }
}

Result

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "events": [
      {
        "type": "contract",
        "ledger": 2531021,
        "ledgerClosedAt": "2023-11-15T08:58:25Z",
        "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
        "id": "0010870652420501504-0000000004",
        "pagingToken": "0010870652420501504-0000000004",
        "topic": [
          "AAAADwAAAAh0cmFuc2Zlcg==",
          "AAAAEgAAAAAAAAAAjt5DlR5mhneFx/1Lct0ToW555OFzg/Y28++28cJXU+I=",
          "AAAAEgAAAAAAAAAA33Fu/fnobL8/u8tyLCIZzpMXbsRWRBlfAuEv7fBvTwM=",
          "AAAADgAAAAZuYXRpdmUAAA=="
        ],
        "value": {
          "xdr": "AAAACgAAAAAAAAAAAAAAAAAAAJY="
        },
        "inSuccessfulContractCall": true
      },
      {
        "type": "contract",
        "ledger": 2531273,
        "ledgerClosedAt": "2023-11-15T09:20:38Z",
        "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
        "id": "0010871734752280576-0000000004",
        "pagingToken": "0010871734752280576-0000000004",
        "topic": [
          "AAAADwAAAAh0cmFuc2Zlcg==",
          "AAAAEgAAAAAAAAAA+YQ+FM83vUUwQ6P3gKCMVTyC3/jO+DERXTWJDKEjagU=",
          "AAAAEgAAAAAAAAAAwl0UMLLKYqMEedoowz8VnwbRywjcKEeQegoMmU6C9/0=",
          "AAAADgAAAAZuYXRpdmUAAA=="
        ],
        "value": {
          "xdr": "AAAACgAAAAAAAAAAAAAAAAAAAJY="
        },
        "inSuccessfulContractCall": true
      }
    ],
    "latestLedger": 2539388
  }
}