getEvents - Stellar Developer Docs

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

number

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.Sequence number of the ledger.

number

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

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.

Show items

string

Filter events by type. If omitted, all event types are included.Available options: system, contract

string[]

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

string[][]

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.

object

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

Show properties

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.

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.

string

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.Specifies whether XDR should be encoded as Base64 (default or ‘base64’) or JSON (‘json’).

Result

(getEventsResult)

number

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

number

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

string

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

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.

object[]

Show items

string

The type of event emission.Available options: contract, system

number

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

string

ISO-8601 timestamp of the ledger closing time

string

StrKey representation of the contract address that emitted this event.

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.

For example: 0000000000000123456-0000000001

number

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

number

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

string[]

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

string

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

string

The transaction which triggered this event.

string

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

Examples

Native XLM Transfer Events
All Events

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

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

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,
        "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,
        "topic": [
          "AAAADwAAAAh0cmFuc2Zlcg==",
          "AAAAEgAAAAFvWqehdOlYvvTHeLuVC7C5mabRfoyKnCxxAOeeSzHCbQ==",
          "AAAAEgAAAAEX55xp/WiwvNIMhmNvj+HN+OoYTpPk1xsJ+iKUVLmQLg==",
          "AAAADgAAAAZuYXRpdmUAAA=="
        ],
        "value": "AAAACgAAAAAAAAAAAAAAAAKJZY8=",
        "txHash": "a5c9247b77eb04c0d857934a2e988c408167976c8acbdf3d8acf64c44deb3beb"
      }
    ],
    "latestLedger": 3730843,
    "oldestLedger": 3609884,
    "latestLedgerCloseTime": "1784671886",
    "oldestLedgerCloseTime": "1784066056",
    "cursor": "0016010972359577600-0000000008"
  }
}

Example request to the getEvents method, filtering for all events of all types for any and all contracts.Request

curl -X POST \
-H 'Content-Type: application/json' \
-d '{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getEvents",
  "params": {
    "startLedger": 199616,
    "pagination": {
      "limit": 2
    }
  }
}' \
https://soroban-testnet.stellar.org | jq

let requestBody = {
  jsonrpc: "2.0",
  id: 8675309,
  method: "getEvents",
  params: {
    startLedger: 199616,
    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": 199616,
        "pagination": {
            "limit": 2
        }
    }
})
print(json.dumps(res.json(), indent=4))

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getEvents",
  "params": {
    "startLedger": 199616,
    "pagination": {
      "limit": 2
    }
  }
}

Result

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "events": [
      {
        "type": "contract",
        "ledger": 3729796,
        "ledgerClosedAt": "2026-07-21T20:44:01Z",
        "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
        "id": "0016019351840751616-0000000000",
        "transactionIndex": 0,
        "operationIndex": 0,
        "topic": [
          "AAAADwAAAANmZWUA",
          "AAAAEgAAAAAAAAAAA+0oimKONzC713z+Cl8orRHR8/s0JY+JMothA0fY7bY="
        ],
        "value": "AAAACgAAAAAAAAAAAAAAAAAAAGQ=",
        "txHash": "dd2f693c5d874ed09f2de0a4edbc453a0a74fe3e44a40e8a4017bd47a1708ffd"
      },
      {
        "type": "contract",
        "ledger": 3729796,
        "ledgerClosedAt": "2026-07-21T20:44:01Z",
        "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
        "id": "0016019351840751616-0000000001",
        "transactionIndex": 0,
        "operationIndex": 0,
        "topic": [
          "AAAADwAAAANmZWUA",
          "AAAAEgAAAAAAAAAAHvWJXEUjo0G/RW4K3B2oCbR8OHbnLlCyfD3iKAnjKPY="
        ],
        "value": "AAAACgAAAAAAAAAAAAAAAAAAASw=",
        "txHash": "3fcd635d285c5b3a4d9b65a10f6c70c11132d8fafd32e82fea79103eb1a05924"
      }
    ],
    "latestLedger": 3730797,
    "oldestLedger": 3609838,
    "latestLedgerCloseTime": "1784671655",
    "oldestLedgerCloseTime": "1784065826",
    "cursor": "0016019351840751616-0000000001"
  }
}

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 field	Stage	Transaction index	Operation index
`TransactionMetaV4.events`	`BEFORE_ALL_TXS`	`0`	`0`
`OperationMetaV2.events`	not applicable	index of the transaction	index of the operation
`TransactionMetaV4.events`	`AFTER_TX`	index of the transaction	`4095`
`TransactionMetaV4.events`	`AFTER_ALL_TXS`	`1048575`	`0`

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:

Every fee charge event.
For each transaction, in transaction order: its operation events, then its post-transaction events.
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.

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

​Params (5)

​Result

​Examples

​Event ordering

​Using the Lab

Params (5)

Result

Examples

Event ordering

Using the Lab