Skip to main content

getEvents

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

Stellar-RPC retains a bounded, ledger-denominated history of recent transactions and events, configured by a single history-retention-window setting with a stock default of 120960 ledgers (about 7 days, depending on ledger cadence); requests are served from within that retained range. The effective window and the ledgers currently available can be inspected via the getHealth method (ledgerRetentionWindow, oldestLedger, latestLedger).

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.

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

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

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

Filter events by type. If omitted, all event types are included.

Allowed values:
systemcontract
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]

A list of topic filters. Each filter is itself an array of one to four SegmentMatcher elements (see below). If omitted, query for all events. If multiple filters are specified, events will be included if they match any of the filters.

<= 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

An opaque string which acts as a paging token. To obtain the next page of results occurring after a given response set this value to the cursor field of the response.

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

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

Specifies whether XDR should be encoded as Base64 (default or 'base64') or JSON ('json').

Result

(getEventsResult)
latestLedger
number

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

oldestLedger
number

The sequence number of the oldest ledger ingested by Stellar RPC at the time it handled the request.

latestLedgerCloseTime
string

The unix timestamp (as a string) of the close time of the latest ledger known to Stellar RPC when it handled the request.

oldestLedgerCloseTime
string

The unix timestamp (as a string) of the close time of the oldest ledger kept in history by Stellar RPC when it handled the request.

events
array[object]
type
string

The type of event emission.

Allowed values:
contractsystem
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.

id
string

Unique identifier for this event, based on the TOID format. It combines a 19-character TOID and a 10-character, zero-padded event index, separated by a hyphen.Show all...

transactionIndex
number

The index of the transaction within the ledger this event occurred in.

operationIndex
number

The index of the operation within the transaction this event occurred in.

inSuccessfulContractCall
boolean
deprecated

If true the event was emitted during a successful contract call.

topic
array[string]

The ScVals containing the topics this event was emitted with (as a base64 string).

>= 1 items<= 4 items
value
string

The data emitted by the event (an ScVal, serialized as a base64 string).

txHash
string

The transaction which triggered this event.

>= 64 characters<= 64 characters
Match pattern:
^[a-f\d]{64}$
cursor
string

A token which can be included in a subsequent request to obtain the next page of results.

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

Result

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "events": [
      {
        "type": "contract",
        "ledger": 3727845,
        "ledgerClosedAt": "2026-07-21T18:01:10Z",
        "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
        "id": "0016010972359577600-0000000001",
        "transactionIndex": 5,
        "operationIndex": 0,
        "inSuccessfulContractCall": true,
        "topic": [
          "AAAADwAAAAh0cmFuc2Zlcg==",
          "AAAAEgAAAAAAAAAAjnWZyariB+Ah9OPGy5WJe1t2Ks3gKsKGYsy7vmpJRIY=",
          "AAAAEgAAAAGu/2GlTlA4D83fxvERV0mWvvsyBPo+xfk3Guav6IgNZQ==",
          "AAAADgAAAAZuYXRpdmUAAA=="
        ],
        "value": "AAAACgAAAAAAAAAAAAAAALLQXgA=",
        "txHash": "a5c9247b77eb04c0d857934a2e988c408167976c8acbdf3d8acf64c44deb3beb"
      },
      {
        "type": "contract",
        "ledger": 3727845,
        "ledgerClosedAt": "2026-07-21T18:01:10Z",
        "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
        "id": "0016010972359577600-0000000008",
        "transactionIndex": 5,
        "operationIndex": 0,
        "inSuccessfulContractCall": true,
        "topic": [
          "AAAADwAAAAh0cmFuc2Zlcg==",
          "AAAAEgAAAAFvWqehdOlYvvTHeLuVC7C5mabRfoyKnCxxAOeeSzHCbQ==",
          "AAAAEgAAAAEX55xp/WiwvNIMhmNvj+HN+OoYTpPk1xsJ+iKUVLmQLg==",
          "AAAADgAAAAZuYXRpdmUAAA=="
        ],
        "value": "AAAACgAAAAAAAAAAAAAAAAKJZY8=",
        "txHash": "a5c9247b77eb04c0d857934a2e988c408167976c8acbdf3d8acf64c44deb3beb"
      }
    ],
    "latestLedger": 3730843,
    "oldestLedger": 3609884,
    "latestLedgerCloseTime": "1784671886",
    "oldestLedgerCloseTime": "1784066056",
    "cursor": "0016010972359577600-0000000008"
  }
}

Event ordering​

getEvents returns events in ascending order of their id. The id holds a TOID and an event index, so the sort key is the ledger sequence, then the transaction index, then the operation index, then the event index.

Protocol 23 keeps events in two separate XDR fields. TransactionMetaV4.events holds the transaction-level events. Each OperationMetaV2.events holds the events of one operation. A transaction-level event also carries a stage, because these events happen at different points of the ledger apply flow. Operation events all happen when the transaction is applied.

Stellar RPC re-derives the execution order of Stellar Core and builds each cursor from it:

XDR fieldStageTransaction indexOperation index
TransactionMetaV4.eventsBEFORE_ALL_TXS00
OperationMetaV2.eventsnot applicableindex of the transactionindex of the operation
TransactionMetaV4.eventsAFTER_TXindex of the transaction4095
TransactionMetaV4.eventsAFTER_ALL_TXS10485750

A TOID gives 12 bits to the operation index and 20 bits to the transaction index. 4095 is therefore the largest operation index, which sorts an AFTER_TX event after every operation of its transaction. 1048575 is the largest transaction index, which sorts an AFTER_ALL_TXS event after every transaction of the ledger. Transaction indexes start at 1, so index 0 sorts before every transaction of the ledger.

Events in one ledger come back in this order:

  1. Every fee charge event.
  2. For each transaction, in transaction order: its operation events, then its post-transaction events.
  3. Every fee refund event.

To reproduce this order from meta XDR, sort your own events by the same four values. The getTransaction and getTransactions methods return the two XDR fields separately, in their events object, as events.transactionEventsXdr and events.contractEventsXdr.

note

transactionIndex and operationIndex come from the cursor. On a transaction-level event they hold the sort values in the table above, not a real position in the ledger. Read txHash to find the transaction that a fee event belongs to.

Fee events are the only transaction-level events today. Stellar Core emits the fee charge at the BEFORE_ALL_TXS stage. It emits a Soroban fee refund at the AFTER_ALL_TXS stage. Both are contract events from the native asset contract, and their topics are the symbol fee and the fee source address. A refund carries a negative amount. Stellar Core emits no event when the amount is zero.

Those are the decoded values. This method returns topic and value as base64 ScVals unless you set xdrFormat to json. A topic filter therefore takes the encoded symbol, AAAADwAAAANmZWUA, and not the string fee.

Using the Lab​

Let's test the example request for Native XLM Transfer Events directly on the Stellar Laboratory.

The new Lab supports sharable URLs that prefill input fields based on query parameters. This makes it easy to share and revisit specific configurations.

👉 View Native XLM Transfer Events example on the Lab

Lab: Get Events