> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stellar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# getEvents

> Returns contract events

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)

> [!TIP]
>
> 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

**startLedger** `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.

**endLedger** `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.

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

**items**

**type** `string`

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

Available options: `system`, `contract`

**contractIds** `string[]`

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

**topics** `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.

**pagination** `object`

Pagination in stellar-rpc is similar to pagination in Horizon. See [Pagination](https://developers.stellar.org/docs/data/rpc/api-reference/structure/pagination.md).

**properties**

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

**xdrFormat** `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)*

**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** `object[]`

**items**

**type** `string`

The type of event emission.

Available options: `contract`, `system`

**ledger** `number`

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

**ledgerClosedAt** `string`

[ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) 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](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0035.md#specification) format. It combines a 19-character TOID and a 10-character, zero-padded event index, separated by a hyphen.

* For example: `0000000000000123456-0000000001`

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

**topic** `string[]`

The [ScVal](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-contract.x#L214)s containing the topics this event was emitted with (as a base64 string).

**value** `string`

The data emitted by the event (an [ScVal](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-contract.x#L214), serialized as a base64 string).

**txHash** `string`

The transaction which triggered this event.

**cursor** `string`

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

## Examples

**Native XLM Transfer Events**

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

**Request**

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```

```js JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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))
```

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getEvents",
  "params": {
    "startLedger": 199616,
    "filters": [
      {
        "type": "contract",
        "contractIds": [
          "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
        ],
        "topics": [["AAAADwAAAAh0cmFuc2Zlcg==", "*", "*", "**"]]
      }
    ],
    "pagination": {
      "limit": 2
    }
  }
}
```

**Result**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
  }
}
```

**All Events**

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

**Request**

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```

```js JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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))
```

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "getEvents",
  "params": {
    "startLedger": 199616,
    "pagination": {
      "limit": 2
    }
  }
}
```

**Result**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0035.md#specification) 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](https://github.com/stellar/stellar-xdr/blob/v23.0/Stellar-ledger.x#L488-L498), 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:

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`](./getTransaction) and [`getTransactions`](./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](https://laboratory.stellar.org).

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](https://lab.stellar.org/endpoints/rpc/get-events?\$=network\$id=testnet\&label=Testnet\&horizonUrl=https:////horizon-testnet.stellar.org\&rpcUrl=https:////soroban-testnet.stellar.org\&passphrase=Test%20SDF%20Network%20/;%20September%202015;\&endpoints\$params\$startLedger=572089\&filters=%7B%22type%22:%22contract%22,%22contract_ids%22:%5B%22CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC%22%5D,%22topics%22:%5B%22%5B%5C%22AAAADwAAAAh0cmFuc2Zlcg==%5C%22,%5C%22*%5C%22,%5C%22*%5C%22,%5C%22*%5C%22%5D%22%5D%7D;;)

![Lab: Get Events](https://mintcdn.com/stellardevelopmentfoundation/1iVxlvEjme-PeN5h/assets/api/rpc/getevents.jpg?fit=max\&auto=format\&n=1iVxlvEjme-PeN5h\&q=85\&s=30802d8fe12a1ac8ee8b634a149610fa)