> For the complete documentation index, see [llms.txt](https://docs.mercurydata.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mercurydata.app/mercury-classic/queries/1.-contract-events.md).

# 1. Contract Events

#### 1.1 GET `/events/by-ledger`

Get events for all contracts in a ledger range.

**Query params**

* `from` (i32, optional) – default `0`
* `to` (i32, optional) – default `i32::MAX`
* `limit` (i64, optional) – default `100`
* `offset` (i64, optional) – default `0`
* `cursor` (i32, optional) – last `id` from previous page; when set, `offset` is ignored

**Example**

```bash
curl -X GET \
  "$BASE/events/by-ledger?from=500000&to=500500&limit=50&offset=0" \
  -H "Authorization: $AUTH" \
  -H "Accept: application/json"
```

***

#### 1.2 GET `/events/by-contract/{contract_id}`

This route can do three things depending on the query string.

**1.2.a just the contract**

```bash
curl -X GET \
  "$BASE/events/by-contract/CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA?limit=100&offset=0" \
  -H "Authorization: $AUTH"
```

**1.2.b contract + ledger range**

```bash
curl -X GET \
  "$BASE/events/by-contract/CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA?from=500000&to=500200&limit=100&cur
  sor=98765" \
  -H "Authorization: $AUTH"
```

You can also do only `from` or only `to`.

**1.2.c contract + topics**

Topics are comma-separated in one param.

```bash
curl -X GET \
  "$BASE/events/by-contract/CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA?topics=AAAADwAAAAh0cmFuc2Zlcg==,anotherTopic&limit=100&offset=0" \
  -H "Authorization: $AUTH"
```

**Precedence in this route**:

1. if `from` or `to` → ledger branch
2. else if `topics` → topics branch
3. else → plain

***

#### 1.3 GET `/events/by-contracts`

Takes a comma-separated list of contracts.

**Query params**

* `contracts=ID1,ID2,...` (required) – comma-separated contract `IDs`
* `limit` (i64, optional) – default `100`, max `1000`
* `offset` (i64, optional) – default `0`
* `cursor` (i32, optional) - last `id` from previous page; when set, `offset` is ignored

**Example**

```bash
curl -X GET \
  "$BASE/events/by-contracts?contracts=CONTRACT1,CONTRACT2&limit=100&offset=0" \
  -H "Authorization: $AUTH"
```

***

#### 1.4 GET `/events/by-ledger/contracts`

You can filter by multiple contracts AND a ledger range.

**Query params**

* `contracts=ID1,ID2,...` (required) – comma-separated contract `IDs`
* `from` (i32, optional) – default `0`
* `to` (i32, optional) – default `i32::MAX`
* `limit` (i64, optional) – default `100`, max `1000`
* `offset` (i64, optional) – default `0`
* `cursor` (i32, optional) – last `id` from previous page; when set, `offset` is ignored

**Example**

```bash
curl -X GET \
  "$BASE/events/by-ledger/contracts?contracts=CONTRACT1,CONTRACT2&from=500000&to=500500&limit=100&offset=0" \
  -H "Authorization: $AUTH"
```

***

#### 1.5 GET `/events/by-tx/{tx_hex}`

Get events tied to a single transaction.

```bash
curl -X GET \
  "$BASE/events/by-tx/af01bc..." \
  -H "Authorization: $AUTH"
```

***

#### Response shape

Every route above returns a JSON array of event objects:

| Field              | Type           | Description                                                                 |
| ------------------ | -------------- | --------------------------------------------------------------------------- |
| `id`               | i32            | Mercury row id (opaque, monotonic; usable as a page `cursor`).              |
| `contract_id`      | string         | Emitting contract (`C...`).                                                 |
| `topic1`…`topic10` | string \| null | XDR-base64 event topics. Topics classify an event; they do not identify it. |
| `data`             | string         | XDR-base64 event data.                                                      |
| `tx`               | string         | Transaction hash (hex).                                                     |
| `event_index`      | i32 \| null    | 0-based position of the event within its transaction.                       |