getEvents

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

Stellar-RPC will support querying within a maximum 7 days 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 stellar-rpc retains the most recent 24 hours of events.

Params

(5)

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 start fetching responses from (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. endLedger

Ledger sequence number represents the end of search window (exclusive). If a cursor is included in the request, endLedger must be omitted.

number

Sequence number of the ledger.

3. 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...

4. pagination

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

cursor

string

A unique identifier (specifically, a TOID) 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, RPC will not include the element whose ID matches the cursor in the response: only elements which appear after the cursor will be 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 Stellar-RPC for performance reasons. If this argument isn't designated, it defaults to 100.

5. format (required)

Lets the user choose the format in which the response should be returned - either as unpacked JSON or as base64-encoded XDR strings. Note that you should not rely on any schema for the JSON, as it will change when the underlying XDR changes.

string

A string which indicates whether the response should be decoded to json or return the base64 encoded xdr strings.

Result

(getEventsResult)

latestLedger

number

The sequence number of the latest ledger known to Stellar 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

string

The emitted body value of the event (serialized in a base64 string).

txHash

string

The transaction which triggered this event.

>= 64 characters<= 64 characters

Match pattern:

^[a-f\d]{64}$

cursor

string

The last populated event ID if total events reach the limit or end of the search window.

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": 1190000,
    "filters": [
      {
        "type": "contract",
        "contractIds": [
          "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
        ],
        "topics": [
          [
            "AAAADwAAAAh0cmFuc2Zlcg==",
            "*",
            "*",
            "*"
          ]
        ]
      }
    ],
    "pagination": {
      "limit": 2
    }
  }
}' \
https://soroban-testnet.stellar.org | jq

let requestBody = {
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getEvents",
  "params": {
    "startLedger": 1190000,
    "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": 1190000,
        "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": 1190000,
    "filters": [
      {
        "type": "contract",
        "contractIds": [
          "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
        ],
        "topics": [
          [
            "AAAADwAAAAh0cmFuc2Zlcg==",
            "*",
            "*",
            "*"
          ]
        ]
      }
    ],
    "pagination": {
      "limit": 2
    }
  }
}

Result

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "events": [
      {
        "type": "contract",
        "ledger": 1192402,
        "ledgerClosedAt": "2024-04-19T06:19:00Z",
        "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
        "id": "0005121327593697280-0000000002",
        "pagingToken": "0005121327593697280-0000000002",
        "topic": [
          "AAAADwAAAAh0cmFuc2Zlcg==",
          "AAAAEgAAAAAAAAAA/ItF3cwsGhkee6lL5X6kicifdluxtsuDq9J/F0zou6Q=",
          "AAAAEgAAAAAAAAAA2uSCoRk2StNEYAmWOhGXKQg0SLV6avaiN7TdV/uMozQ=",
          "AAAADgAAAAZuYXRpdmUAAA=="
        ],
        "value": "AAAACgAAAAAAAAAAAAAAAAX14QA=",
        "inSuccessfulContractCall": true,
        "txHash": "bd8a6611a3b44ff7dce76a27fb32fa69c9f6eff3435ca5296f6035d5105617ed"
      },
      {
        "type": "contract",
        "ledger": 1192438,
        "ledgerClosedAt": "2024-04-19T06:22:14Z",
        "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
        "id": "0005121482212511744-0000000002",
        "pagingToken": "0005121482212511744-0000000002",
        "topic": [
          "AAAADwAAAAh0cmFuc2Zlcg==",
          "AAAAEgAAAAAAAAAA/ItF3cwsGhkee6lL5X6kicifdluxtsuDq9J/F0zou6Q=",
          "AAAAEgAAAAAAAAAA2uSCoRk2StNEYAmWOhGXKQg0SLV6avaiN7TdV/uMozQ=",
          "AAAADgAAAAZuYXRpdmUAAA=="
        ],
        "value": "AAAACgAAAAAAAAAAAAAAAACYloA=",
        "inSuccessfulContractCall": true,
        "txHash": "3fa1787085a4aa585507751394d70494a02e71d347446095a763ecbfc647937c"
      }
    ],
    "latestLedger": 1197926
  }
}