> For the complete documentation index, see [llms.txt](https://docs.tronql.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tronql.com/events.md).

# Tron events server

**Base URL:** `https://mainnet.tron.tronql.com`

***

## Table of Contents

* [Authentication](#authentication)
* [Concepts](#concepts)
* [Transactions](#transactions)
* [Transfers](#transfers)
* [Events](#events)
* [Blocks](#blocks)
* [Contract Logs](#contract-logs)
* [Contract Events (ABI-decoded)](#contract-events-abi-decoded)
* [TronGrid-Compatible Events](#trongrid-compatible-events)
* [TRC20](#trc20)

***

## Authentication

Two methods are supported:

**Header (recommended):**

```
GET https://mainnet.tron.tronql.com/transactions
Authorization: <your-token>
```

**Token in subdomain:**

```
GET https://<your-token>.mainnet.tron.tronql.com/transactions
```

***

## Concepts

### Pagination

Most list endpoints use 1-based page numbers (`start=1` is the first page). **Contract Logs** and **Contract Events** endpoints are 0-based (`start=0`).

| Parameter | Description              | Default |
| --------- | ------------------------ | ------- |
| `limit`   | Number of items per page | 25      |
| `start`   | Page number              | 1 or 0  |

### Sorting

Pass a field name to `sort`. Prefix with `-` for descending order.

**Supported sort fields for events, transactions, transfers:**

| `sort` value       | Sorts by                 |
| ------------------ | ------------------------ |
| `timeStamp`        | Timestamp ascending      |
| `-timeStamp`       | Timestamp descending     |
| `blockNumber`      | Block number ascending   |
| `-blockNumber`     | Block number descending  |
| `transactionId`    | Transaction ID ascending |
| `energyUsageTotal` | Energy usage ascending   |
| `netFee`           | Net fee ascending        |

**Supported sort fields for blocks:**

| `sort` value      | Sorts by                    |
| ----------------- | --------------------------- |
| `timeStamp`       | Timestamp ascending         |
| `-timeStamp`      | Timestamp descending        |
| `blockNumber`     | Block number ascending      |
| `blockHash`       | Block hash ascending        |
| `transactionSize` | Transaction count ascending |

### Timestamps

All timestamps (`since`, `fromTimestamp`) are Unix milliseconds (e.g., `1620000000000`).

### Solidified Blocks

A *solidified* (confirmed) block has received enough network confirmations and cannot be rolled back. The `latestSolidifiedBlockNumber` value is returned on most responses. Events in blocks above this number are marked `_unconfirmed: true` in TronGrid-compatible responses.

***

## Transactions

### List Transactions

**GET** `/transactions`

**Query Parameters:**

| Name       | Type   | Description           | Default    |
| ---------- | ------ | --------------------- | ---------- |
| `limit`    | int    | Page size (max 100)   | 25         |
| `sort`     | string | Sort field            | -timeStamp |
| `start`    | int    | Page number (1-based) | 1          |
| `block`    | int    | Minimum block number  | 0          |
| `block_to` | int    | Maximum block number  | —          |

**Response:**

```json
{
  "total": 1234567,
  "data": [
    {
      "transactionId": "9a4f09...",
      "blockHash": "00000000...",
      "blockNumber": 4835773,
      "energyUsage": 0,
      "energyFee": 0,
      "originEnergyUsage": 0,
      "energyUsageTotal": 13000,
      "netUsage": 267,
      "netFee": 0,
      "result": "SUCCESS",
      "contractAddress": "TR7NHq...",
      "contractType": "TriggerSmartContract",
      "feeLimit": 100000000,
      "contractCallValue": 0,
      "timeStamp": 1620000000000,
      "triggerName": "triggerSmartContract",
      "internalTrananctionList": null,
      "fromAddress": "TJ7yJN...",
      "toAddress": "TAEcoD...",
      "assetName": "",
      "assetAmount": 0,
      "contractResult": "0x",
      "latestSolidifiedBlockNumber": 4835755,
      "data": ""
    }
  ]
}
```

**Example:** `https://mainnet.tron.tronql.com/transactions?limit=25&sort=-timeStamp&block=10000&block_to=20000`

***

### Get Transaction by Hash

**GET** `/transactions/{hash}`

**Response:** `{ "transaction": { ...TransactionItem } }`

**Example:** `https://mainnet.tron.tronql.com/transactions/9a4f096700672d7420889cd76570ea47bfe9ef815bb2137b0d4c71b3d23309e9`

***

### Get Transactions Total

**GET** `/transactions/total`

Returns total transaction count as plain text.

**Example:** `https://mainnet.tron.tronql.com/transactions/total` → `1234567`

***

## Transfers

Transfers are transactions of type `TransferContract` or `TransferAssetContract`.

### List Transfers

**GET** `/transfers`

**Query Parameters:**

| Name    | Type   | Description                        | Default    |
| ------- | ------ | ---------------------------------- | ---------- |
| `limit` | int    | Page size (max 100)                | 25         |
| `sort`  | string | Sort field                         | -timeStamp |
| `start` | int    | Page number (1-based)              | 1          |
| `from`  | string | Filter by sender address           | —          |
| `to`    | string | Filter by recipient address        | —          |
| `token` | string | Filter by token name (e.g., `trx`) | —          |
| `block` | int    | Minimum block number               | —          |

**Response:**

```json
{
  "total": 56789,
  "data": [ ...TransactionItem ]
}
```

**Example:** `https://mainnet.tron.tronql.com/transfers?token=trx&from=TJ7yJNWS8RmvpXcAyXBhvFDfGpV9ZYc3vt`

***

### Get Transfer by Hash

**GET** `/transfers/{hash}`

Returns 404 if the transaction exists but is not a transfer type.

**Response:** `{ "transaction": { ...TransactionItem } }`

**Example:** `https://mainnet.tron.tronql.com/transfers/70d655a17e04d6b6b7ee5d53e7f37655974f4e71b0edd6bcb311915a151a4700`

***

### Get Transfers Total

**GET** `/transfers/total`

Returns total transfer count as plain text.

**Example:** `https://mainnet.tron.tronql.com/transfers/total` → `56789`

***

### Get Transfers Total by Address

**GET** `/transfers/total/{address}`

Returns total transfer count for a specific address as plain text.

**Example:** `https://mainnet.tron.tronql.com/transfers/total/TJ7yJNWS8RmvpXcAyXBhvFDfGpV9ZYc3vt` → `42`

***

## Events

Events are smart contract logs indexed by the indexer. These endpoints return a **native TronQL format** (see also [TronGrid-Compatible Events](#trongrid-compatible-events) for TronGrid format).

### Event Object

```json
{
  "eventSignature": "Transfer(address,address,uint256)",
  "eventSignatureFull": "Transfer(address _from, address _to, uint256 value)",
  "eventName": "Transfer",
  "topicMap": { "_from": "TJ7yJN...", "_to": "TAEcoD..." },
  "dataMap": { "value": "1000000" },
  "transactionId": "9a4f09...",
  "contractAddress": "TR7NHq...",
  "callerAddress": "TJ7yJN...",
  "originAddress": "TJ7yJN...",
  "creatorAddress": "TR7NHq...",
  "blockNumber": 4835773,
  "timeStamp": 1620000000000,
  "triggerName": "triggerSmartContract",
  "uniqueId": "9a4f09..._0",
  "removed": "false",
  "latestSolidifiedBlockNumber": 4835755,
  "abiString": null,
  "rawData": {}
}
```

> `uniqueId` is `{transactionHash}_{eventIndex}`, e.g., `9a4f09..._0`.

***

### List Events

**GET** `/events`

**Query Parameters:**

| Name         | Type   | Description           | Default    |
| ------------ | ------ | --------------------- | ---------- |
| `limit`      | int    | Page size (max 100)   | 25         |
| `sort`       | string | Sort field            | -timeStamp |
| `start`      | int    | Page number (1-based) | 1          |
| `block`      | int    | Minimum block number  | 0          |
| `event_name` | string | Filter by event name  | —          |

**Response:** Plain JSON array of Event objects (no `total` wrapper).

**Example:** `https://mainnet.tron.tronql.com/events?limit=25&sort=-timeStamp&block=10000`

***

### Get Events Total

**GET** `/events/total`

Returns total event count as plain text.

**Example:** `https://mainnet.tron.tronql.com/events/total` → `98765432`

***

### Get Event by Unique ID

**GET** `/events/uniqueId/{uniqueId}`

Returns a single event. Returns 404 if not found.

**Example:** `https://mainnet.tron.tronql.com/events/uniqueId/9a4f096700672d7420889cd76570ea47bfe9ef815bb2137b0d4c71b3d23309e9_0`

***

### Get Events by Transaction

**GET** `/events/transaction/{transactionId}`

Returns all events emitted by a transaction.

**Example:** `https://mainnet.tron.tronql.com/events/transaction/cd402e64cad7e69c086649401f6427f5852239f41f51a100abfc7beaa8aa0f9c`

***

### Get Confirmed Events

**GET** `/events/confirmed`

Returns only events from solidified (confirmed) blocks. Same query parameters as [`/events`](#list-events).

**Example:** `https://mainnet.tron.tronql.com/events/confirmed?since=1620000000000&limit=25`

***

### Get Events by Timestamp

**GET** `/events/timestamp`

Same as `/events` but additionally supports filtering by `contract` address. Uses `block` as the minimum block number filter (not a timestamp filter despite the endpoint name).

| Name         | Type   | Description                | Default    |
| ------------ | ------ | -------------------------- | ---------- |
| `limit`      | int    | Page size (max 100)        | 25         |
| `sort`       | string | Sort field                 | -timeStamp |
| `start`      | int    | Page number (1-based)      | 1          |
| `block`      | int    | Minimum block number       | 0          |
| `event_name` | string | Filter by event name       | —          |
| `contract`   | string | Filter by contract address | —          |

**Example:** `https://mainnet.tron.tronql.com/events/timestamp?block=1620000&contract=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t&limit=25`

***

### Get Events by Contract Address

**GET** `/events/{contractAddress}`

Returns events emitted by a specific contract. Response items are flattened: `topicMap` and `dataMap` fields are merged into the top-level object alongside standard fields.

**Query Parameters:**

| Name         | Type   | Description            | Default    |
| ------------ | ------ | ---------------------- | ---------- |
| `limit`      | int    | Page size (max 100)    | 25         |
| `sort`       | string | Sort field             | -timeStamp |
| `start`      | int    | Page number (1-based)  | 1          |
| `block`      | int    | Minimum block number   | 0          |
| `since`      | int    | Minimum timestamp (ms) | 0          |
| `event_name` | string | Filter by event name   | —          |

**Example:** `https://mainnet.tron.tronql.com/events/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk?event_name=Bet&limit=25`

***

### Get Events by Contract Address and Event Name

**GET** `/events/contract/{contractAddress}/{eventName}`

Accepts the same query parameters as `/events`.

**Example:** `https://mainnet.tron.tronql.com/events/contract/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk/Bet?limit=25&sort=-timeStamp`

***

### Get Events by Contract, Event Name, and Block

**GET** `/events/contract/{contractAddress}/{eventName}/{blockNumber}`

Filters events by an **exact** block number match on `{blockNumber}`. The `block` query parameter (minimum block) still applies.

**Example:** `https://mainnet.tron.tronql.com/events/contract/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk/Bet/4835773`

***

### Filter Events by Contract and Event Name (Exact Block)

**GET** `/events/filter/contract/{contractAddress}/{eventName}`

Like the endpoint above, but the `block` query parameter filters by an **exact** block number instead of a minimum.

**Query Parameters:**

| Name    | Type   | Description                     | Default    |
| ------- | ------ | ------------------------------- | ---------- |
| `limit` | int    | Page size (max 100)             | 25         |
| `sort`  | string | Sort field                      | -timeStamp |
| `start` | int    | Page number (1-based)           | 1          |
| `since` | int    | Minimum timestamp (ms)          | 0          |
| `block` | int    | **Exact** block number to match | —          |

**Example:** `https://mainnet.tron.tronql.com/events/filter/contract/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk/Bet?block=4835773`

***

## Blocks

### List Blocks

**GET** `/blocks`

**Query Parameters:**

| Name       | Type   | Description           | Default    |
| ---------- | ------ | --------------------- | ---------- |
| `limit`    | int    | Page size (max 100)   | 25         |
| `sort`     | string | Sort field            | -timeStamp |
| `start`    | int    | Page number (1-based) | 1          |
| `block`    | int    | Minimum block number  | 0          |
| `block_to` | int    | Maximum block number  | —          |

**Response:**

```json
{
  "total": 65432100,
  "data": [
    {
      "blockNumber": 4835773,
      "blockHash": "000000000049c11f...",
      "transactionSize": 42,
      "transactionList": ["9a4f09...", "cd402e..."],
      "timeStamp": 1620000000000,
      "triggerName": "block",
      "latestSolidifiedBlockNumber": 4835755
    }
  ]
}
```

**Example:** `https://mainnet.tron.tronql.com/blocks?limit=25&sort=-timeStamp`

***

### Get Block by Hash or Number

**GET** `/blocks/{hashOrNumber}`

Accepts either a block hash (hex string) or a block number (integer). When the value parses as an integer it is looked up by block number; otherwise it is looked up by hash.

**Response:** `{ "block": { ...BlockItem } }`

**Examples:** `https://mainnet.tron.tronql.com/blocks/000000000049c11f15d4e91e988bc950fa9f194d2cb2e04cda76675dbb349009` `https://mainnet.tron.tronql.com/blocks/4835773`

***

### Get Latest Solidified Block Number

**GET** `/blocks/latestSolidifiedBlockNumber`

Returns the current solidified block number as plain text.

**Example:** `https://mainnet.tron.tronql.com/blocks/latestSolidifiedBlockNumber` → `4835755`

***

### Get Blocks Total

**GET** `/blocks/total`

Returns total block count as plain text.

**Example:** `https://mainnet.tron.tronql.com/blocks/total` → `65432100`

***

## Contract Logs

Raw EVM-style logs (topics + data), without ABI decoding. For decoded results use [Contract Events (ABI-decoded)](#contract-events-abi-decoded).

> **Note:** These endpoints use **0-based** page numbers (`start=0`).

### Contract Log Object

```json
{
  "topicList": ["0xddf252ad..."],
  "data": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "transactionId": "f7440e...",
  "contractAddress": "TXDk8m...",
  "callerAddress": "TJ7yJN...",
  "originAddress": "TJ7yJN...",
  "creatorAddress": "TXDk8m...",
  "blockNumber": 4835773,
  "timeStamp": 1620000000000,
  "triggerName": "triggerSmartContract",
  "uniqueId": "f7440e..._0",
  "removed": false,
  "latestSolidifiedBlockNumber": 4835755,
  "abiString": null,
  "rawData": {
    "address": "TXDk8m...",
    "topics": [{ "data": "0xddf252ad..." }],
    "data": "0x..."
  }
}
```

***

### List Contract Logs

**GET** `/contractlogs`

**Query Parameters:**

| Name    | Type   | Description               | Default    |
| ------- | ------ | ------------------------- | ---------- |
| `limit` | int    | Page size (max 200)       | 25         |
| `sort`  | string | Sort field                | -timeStamp |
| `start` | int    | Page number (**0-based**) | 0          |
| `block` | int    | Filter by block number    | —          |

**Response:** `{ "total": 42, "data": [ ...ContractLog ] }`

> **Note:** `total` reflects the number of records returned on this page, not the database-wide count. Use `/contractlogs/total` for the true count.

**Example:** `https://mainnet.tron.tronql.com/contractlogs?limit=25&sort=-timeStamp`

***

### Get Contract Logs Total

**GET** `/contractlogs/total`

Returns total contract log count as plain text.

**Example:** `https://mainnet.tron.tronql.com/contractlogs/total` → `12345678`

***

### Get Contract Logs by Transaction

**GET** `/contractlogs/transaction/{transactionId}`

Returns all contract logs for a transaction as a plain JSON array (no `{ total, data }` wrapper).

**Example:** `https://mainnet.tron.tronql.com/contractlogs/transaction/f7440eb396632db8e279078069a55abc0a3c018072b458bbd4eeddafc4782b55`

***

### Get Contract Logs by Contract Address

**GET** `/contractlogs/contract/{contractAddress}`

**Query Parameters:**

| Name        | Type   | Description                         | Default    |
| ----------- | ------ | ----------------------------------- | ---------- |
| `limit`     | int    | Page size (max 200)                 | 25         |
| `sort`      | string | Sort field                          | -timeStamp |
| `start`     | int    | Page number (**0-based**)           | 0          |
| `since`     | int    | Minimum timestamp (ms)              | 0          |
| `block`     | int    | Minimum block number (`-1` to skip) | —          |
| `eventName` | string | Filter by event name                | —          |

**Response:** Plain JSON array of ContractLog objects (no `{ total, data }` wrapper).

**Example:** `https://mainnet.tron.tronql.com/contractlogs/contract/TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz?eventName=Transfer&limit=25`

***

### Get Contract Log by Unique ID

**GET** `/contractlogs/uniqueId/{uniqueId}`

Returns a single contract log. Returns 404 if not found.

**Example:** `https://mainnet.tron.tronql.com/contractlogs/uniqueId/f7440eb396632db8e279078069a55abc0a3c018072b458bbd4eeddafc4782b55_0`

***

## Contract Events (ABI-decoded)

These endpoints accept a JSON request body with ABI field filters and return decoded event data. They use the same response format as [TronGrid-Compatible Events](#trongrid-compatible-events) but wrapped in `{ "total", "data" }`.

> **Note:** These endpoints use **0-based** page numbers (`start=0`).

### Decoded Event Object

```json
{
  "transaction_id": "9a4f09...",
  "block_timestamp": 1620000000000,
  "block_number": 4835773,
  "result_type": { "_from": "address", "_to": "address", "value": "uint256" },
  "result": { "_from": "TJ7yJN...", "_to": "TAEcoD...", "value": "1000000" },
  "event_index": 0,
  "event_name": "Transfer",
  "contract_address": "TR7NHq...",
  "caller_contract_address": "TJ7yJN...",
  "_unconfirmed": true
}
```

> `_unconfirmed` is only present when the event is in an unconfirmed block.

***

### Get Decoded Events by Contract Address

**POST** `/contract/contractAddress/{contractAddress}`

**Query Parameters:**

| Name        | Type   | Description                         | Default    |
| ----------- | ------ | ----------------------------------- | ---------- |
| `limit`     | int    | Page size (max 200)                 | 25         |
| `sort`      | string | Sort field                          | -timeStamp |
| `start`     | int    | Page number (**0-based**)           | 0          |
| `since`     | int    | Minimum timestamp (ms)              | 0          |
| `block`     | int    | Minimum block number (`-1` to skip) | —          |
| `eventName` | string | Filter by event name                | —          |

**Request Body:** JSON object with decoded field name → value pairs to filter results.

```json
{ "_to": "TAEcoD8J7P5QjWT32r31gat8L7Sga2qUy8" }
```

**Response:** `{ "total": 42, "data": [ ...DecodedEvent ] }`

**Example:**

```
POST https://mainnet.tron.tronql.com/contract/contractAddress/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t?eventName=Transfer
Content-Type: application/json

{ "_to": "TAEcoD8J7P5QjWT32r31gat8L7Sga2qUy8" }
```

***

### Get Decoded Events by Transaction

**POST** `/contract/transaction/{transactionId}`

**Request Body:** JSON object with decoded field name → value pairs to filter results.

**Response:** `{ "total": 42, "data": [ ...DecodedEvent ] }`

**Example:**

```
POST https://mainnet.tron.tronql.com/contract/transaction/f7440eb396632db8e279078069a55abc0a3c018072b458bbd4eeddafc4782b55
Content-Type: application/json

{}
```

***

### Get Decoded Event by Unique ID

**POST** `/contract/uniqueId/{uniqueId}`

**Request Body:** JSON object with decoded field name → value pairs to filter results.

**Response:** `{ "total": 1, "data": [ ...DecodedEvent ] }`

**Example:**

```
POST https://mainnet.tron.tronql.com/contract/uniqueId/f7440eb396632db8e279078069a55abc0a3c018072b458bbd4eeddafc4782b55_0
Content-Type: application/json

{}
```

***

## TronGrid-Compatible Events

Drop-in replacement for the TronGrid event API. Use these endpoints to migrate from TronGrid without changing client code.

Response items use snake\_case field names and include `_unconfirmed` / `_fingerprint` markers.

### TronGrid Event Object

```json
{
  "transaction_id": "9a4f09...",
  "block_timestamp": 1620000000000,
  "block_number": 4835773,
  "result_type": { "_from": "address", "_to": "address", "value": "uint256" },
  "result": { "_from": "TJ7yJN...", "_to": "TAEcoD...", "value": "1000000" },
  "event_index": 0,
  "event_name": "Transfer",
  "contract_address": "TR7NHq...",
  "caller_contract_address": "TJ7yJN...",
  "_unconfirmed": true,
  "_fingerprint": "00000001"
}
```

> `_unconfirmed` is only present on unconfirmed events.\
> `_fingerprint` is only present on the **last item** of a page; pass it as the `fingerprint` query parameter to retrieve the next page.

***

### Common TronGrid Query Parameters

| Name              | Type   | Description                                               | Default    |
| ----------------- | ------ | --------------------------------------------------------- | ---------- |
| `size`            | int    | Page size (max 200)                                       | 20         |
| `sort`            | string | Sort field; also accepts `block_timestamp`                | -timeStamp |
| `start`           | int    | Page number (0-based)                                     | 0          |
| `since`           | int    | Minimum timestamp (ms)                                    | 0          |
| `fromTimestamp`   | int    | Alias for `since`                                         | —          |
| `fingerprint`     | string | Pagination cursor from previous response's `_fingerprint` | —          |
| `onlyConfirmed`   | bool   | `true` to return only solidified events                   | —          |
| `onlyUnconfirmed` | bool   | `true` to return only unconfirmed events                  | —          |

> `onlyConfirmed` and `onlyUnconfirmed` are mutually exclusive.

***

### Get Events by Transaction (TronGrid)

**GET** `/event/transaction/{transactionId}`

**Example:** `https://mainnet.tron.tronql.com/event/transaction/cd402e64cad7e69c086649401f6427f5852239f41f51a100abfc7beaa8aa0f9c`

***

### Get Latest Solidified Block Number (TronGrid)

**GET** `/event/contract/latestSolidifiedBlockNum`

Returns the latest solidified block number as plain text.

**Example:** `https://mainnet.tron.tronql.com/event/contract/latestSolidifiedBlockNum` → `4835755`

***

### Get Events by Contract Address (TronGrid)

**GET** `/event/contract/{contractAddress}`

**Example:** `https://mainnet.tron.tronql.com/event/contract/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t?size=20&onlyConfirmed=true`

***

### Get Events by Contract Address and Event Name (TronGrid)

**GET** `/event/contract/{contractAddress}/{eventName}`

**Example:** `https://mainnet.tron.tronql.com/event/contract/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk/Bet?size=20`

***

### Get Events by Contract, Event Name, and Block (TronGrid)

**GET** `/event/contract/{contractAddress}/{eventName}/{blockNumber}`

`{blockNumber}` accepts a numeric block number or the special value `latest`, which resolves to the current solidified block.

**Example:** `https://mainnet.tron.tronql.com/event/contract/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk/Bet/latest`

***

## TRC20

### Get TRC20 Token Holders

**GET** `/trc20/getholder/{contractAddress}`

Returns a deduplicated list of addresses that have appeared as sender or recipient in Transfer events for the given contract.

**Response:**

```json
["TJ7yJNWS8RmvpXcAyXBhvFDfGpV9ZYc3vt", "TAEcoD8J7P5QjWT32r31gat8L7Sga2qUy8"]
```

**Example:** `https://mainnet.tron.tronql.com/trc20/getholder/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`