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

# events | TON v3

> The events endpoint queries blockchain events, which combine traces with their decoded actions. The events endpoint queries blockchain events.

# Events

The `events` endpoint queries blockchain events, which combine traces with their decoded actions. Events provide a complete view of what happened in a transaction flow, including all resulting actions.

<Note>
  **TON billing: full (1 RU)**

  This method is always billed as full. See [Request units — TON method scope](/docs/request-units#ton-method-scope).
</Note>

## Parameters

* `account` (string, optional) — Filter by account address.
* `start_utime` (integer, optional) — Start of time range (unix timestamp).
* `end_utime` (integer, optional) — End of time range (unix timestamp).
* `limit` (integer, optional) — Maximum number of events to return. Default: `10`.
* `offset` (integer, optional) — Number of events to skip for pagination. Default: `0`.
* `sort` (string, optional) — Sort order: `asc` or `desc`. Default: `desc`.

## Response

* `events` (array) — Array of event objects:
  * `trace_id` (string) — Trace ID.
  * `external_hash` (string) — Hash of the external message.
  * `mc_seqno_start` (string) — Start masterchain sequence number.
  * `mc_seqno_end` (string) — End masterchain sequence number.
  * `start_lt` (string) — Start logical time.
  * `start_utime` (integer) — Start unix timestamp.
  * `end_lt` (string) — End logical time.
  * `end_utime` (integer) — End unix timestamp.
  * `trace_info` (object) — Trace state and statistics.
  * `actions` (array) — Decoded actions from the event.
  * `is_incomplete` (boolean) — Whether the event is still processing.

* `address_book` (object) — Address book mapping.

## Use case

The `events` endpoint is useful for applications that need combined trace and action data:

1. Building activity feeds showing user transaction history.
2. Notification systems alerting on specific events.
3. Analytics dashboards tracking blockchain activity.
4. Block explorers showing transaction details with decoded actions.
5. Debugging complex multi-contract interactions.

Here's an example of getting recent events:

<CodeGroup>
  ```shell shell theme={"system"}
  curl -X GET \
    'https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/events?limit=5' \
    -H 'accept: application/json'
  ```
</CodeGroup>

<Tip>
  Events combine the structure of [traces](/reference/ton-traces-v3) with the decoded information from [actions](/reference/ton-actions-v3), making them ideal for building user-facing transaction histories.
</Tip>


## OpenAPI

````yaml openapi/ton_node_api/v3/getEvents.json GET /events
openapi: 3.0.0
info:
  title: TON API
  version: 3.0.0
  description: API for interacting with The Open Network (TON) blockchain
servers:
  - url: >-
      https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3
security: []
paths:
  /events:
    get:
      tags:
        - Events
      summary: Get Events
      description: Query blockchain events with decoded actions
      operationId: getEvents
      parameters:
        - name: account
          in: query
          description: Filter by account address
          schema:
            type: string
        - name: start_utime
          in: query
          description: Start of time range (unix timestamp)
          schema:
            type: integer
        - name: end_utime
          in: query
          description: End of time range (unix timestamp)
          schema:
            type: integer
        - name: limit
          in: query
          description: Maximum number of events to return
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          description: Number of events to skip
          schema:
            type: integer
            default: 0
        - name: sort
          in: query
          description: Sort order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                      properties:
                        trace_id:
                          type: string
                          description: Trace ID
                        external_hash:
                          type: string
                          description: External message hash
                        mc_seqno_start:
                          type: string
                          description: Start masterchain sequence number
                        mc_seqno_end:
                          type: string
                          description: End masterchain sequence number
                        start_lt:
                          type: string
                          description: Start logical time
                        start_utime:
                          type: integer
                          description: Start unix timestamp
                        end_lt:
                          type: string
                          description: End logical time
                        end_utime:
                          type: integer
                          description: End unix timestamp
                        trace_info:
                          type: object
                          description: Trace information
                        actions:
                          type: array
                          description: Decoded actions
                        is_incomplete:
                          type: boolean
                          description: Whether event is incomplete
                  address_book:
                    type: object
                    description: Address book mapping

````