# 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-topics` 

Takes a comma-separated list of topics

**Query params**

* `topics=topicA,topicB,...` (required) – comma-separated `topic` strings
* `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-topics?topics=AAAADwAAAAh0cmFuc2Zlcg==&limit=100&offset=0" \
  -H "Authorization: $AUTH"
```

***

#### 1.5 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.6 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"
```