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

# Contract Events

> Query and paginate events emitted by Ralph contracts.

Ralph contracts emit events to record activity on-chain. Events are immutable, indexed by the explorer, and queryable via the API without running contract code.

## How events work in Ralph

Events are declared at the contract level and emitted inside functions:

```ralph theme={null}
Contract TokenFaucet(...) {
  event Withdraw(to: Address, amount: U256)
  event Deposit(from: Address, amount: U256)

  pub fn withdraw(to: Address, amount: U256) -> () {
    // ... logic ...
    emit Withdraw(to, amount)
  }
}
```

Each `emit` writes an event to the chain. The event fields are stored in order and typed exactly as declared.

## Get events for a contract

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{contract-address}?start=0&limit=20" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "events": [
    {
      "blockHash": "00000000ab3c...",
      "txId": "503a2c...",
      "contractAddress": "27Gsc5...",
      "eventIndex": 0,
      "fields": [
        { "type": "Address", "value": "1DrDyTr9..." },
        { "type": "U256", "value": "1000000000000000000" }
      ]
    }
  ],
  "nextStart": 20
}
```

`eventIndex` maps to the declaration order in the contract source. `0` is the first declared event, `1` is the second, and so on. Use it to tell `Withdraw` events apart from `Deposit` events.

`nextStart` is the offset to pass on the next request. Always use it rather than calculating `start + limit` yourself the indexer may have gaps.

## Get the total event count

Before paginating check how many events exist:

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{contract-address}/current-count" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "count": 384
}
```

To read the most recent 20 events set `start` to `count - 20`.

## Get events for a specific transaction

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/events/tx-id/{txId}" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "events": [
    {
      "blockHash": "00000000ab3c...",
      "contractAddress": "27Gsc5...",
      "eventIndex": 0,
      "fields": [
        { "type": "Address", "value": "1DrDyTr9..." },
        { "type": "U256", "value": "1000000000000000000" }
      ]
    }
  ]
}
```

Useful for confirming exactly which events a transaction emitted after submission.

## Get events for a block

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/events/block-hash/{blockHash}" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "events": [
    {
      "txId": "503a2c...",
      "contractAddress": "27Gsc5...",
      "eventIndex": 0,
      "fields": [...]
    }
  ]
}
```

Use this when processing blocks sequentially fetch all events in a block in one request rather than per-transaction.

## Decode event fields

Fields are returned as typed values in declaration order. Map them back to your event definition:

```ralph theme={null}
event Withdraw(to: Address, amount: U256)
```

```json theme={null}
"fields": [
  { "type": "Address", "value": "1DrDyTr9..." },
  { "type": "U256",    "value": "1000000000000000000" }
]
```

Field 0 → `to`, Field 1 → `amount`. There are no field names in the API response order is the only mapping.

## Polling for new events

To watch for new events from a contract poll the count endpoint and fetch new events when it increases:

```bash theme={null}
# Get current count
curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{contract-address}/current-count" \
  -H "Authorization: Bearer API_KEY"
```

Store the count. On the next poll if the count has increased fetch from your last `nextStart`:

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{contract-address}?start={lastStart}&limit=20" \
  -H "Authorization: Bearer API_KEY"
```

Poll no faster than once per 16 seconds that is the average block time per chain.

## Parameters reference

| Parameter        | Type    | Description                                                |
| ---------------- | ------- | ---------------------------------------------------------- |
| contract-address | string  | Base58 address of the deployed contract                    |
| txId             | string  | Transaction hash to fetch events for                       |
| blockHash        | string  | Block hash to fetch events for                             |
| start            | integer | Pagination offset (use `nextStart` from previous response) |
| limit            | integer | Results per page (max 100)                                 |

## Next steps

<CardGroup cols={2}>
  <Card title="Interacting with contracts" icon="plug" href="/smart-contracts/interacting">
    Execute state-changing functions
  </Card>

  <Card title="Reading contracts via API" icon="file-code" href="/guides/reading-contracts">
    View calls and state reads reference
  </Card>
</CardGroup>