Tron events server

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

---

Table of Contents

• Authentication

• Concepts

• Transactions

• Transfers

• Events

• Blocks

• Contract Logs

• Contract Events (ABI-decoded)

• TronGrid-Compatible Events

• 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:

{
  "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:

{
  "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 for TronGrid format).

Event Object

{
  "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.

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:

{
  "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).

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

Contract Log Object

{
  "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 but wrapped in { "total", "data" }.

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

Decoded Event Object

{
  "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.

{ "_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

{
  "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:

["TJ7yJNWS8RmvpXcAyXBhvFDfGpV9ZYc3vt", "TAEcoD8J7P5QjWT32r31gat8L7Sga2qUy8"]

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