> ## 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.

# traces | TON v3

> The traces endpoint retrieves transaction traces from the TON blockchain. A trace represents the complete execution path of a transaction.

# Traces

The `traces` endpoint retrieves transaction traces from the TON blockchain. A trace represents the complete execution path of a transaction, including all resulting internal messages and their effects across the network.

<Note>
  **TON billing: full or archive by block age**

  This method is billed as archive (2 RUs) when the requested block is 128 or more seqno behind the tip, and full (1 RU) otherwise. See [Request units — TON method scope](/docs/request-units#ton-method-scope).
</Note>

## Parameters

* `trace_id` (string, optional) — Filter by specific trace ID.
* `tx_hash` (string, optional) — Get traces for a specific transaction hash.
* `tx_lt` (integer, optional) — Filter by transaction logical time.
* `limit` (integer, optional) — Maximum number of traces to return. Default: `10`.
* `offset` (integer, optional) — Number of traces to skip for pagination. Default: `0`.
* `sort` (string, optional) — Sort order: `asc` or `desc`. Default: `desc`.

## Response

* `traces` (array) — Array of trace objects containing:
  * `trace_id` (string) — Unique identifier for the trace.
  * `external_hash` (string) — Hash of the external message that initiated the trace.
  * `mc_seqno_start` (integer) — Masterchain sequence number when the trace started.
  * `mc_seqno_end` (integer) — Masterchain sequence number when the trace ended.
  * `start_lt` (integer) — Logical time when the trace started.
  * `start_utime` (integer) — Unix timestamp when the trace started.
  * `end_lt` (integer) — Logical time when the trace ended.
  * `end_utime` (integer) — Unix timestamp when the trace ended.
  * `state` (string) — Current state of the trace (e.g., `complete`, `pending`).
  * `pending_edges` (integer) — Number of pending message edges.
  * `edges` (integer) — Total number of message edges in the trace.
  * `nodes` (integer) — Total number of transaction nodes in the trace.
  * `classification_state` (string) — Classification state of the trace.

* `address_book` (object) — Address book mapping raw addresses to user-friendly information.

## Use case

The `traces` endpoint is essential for understanding the complete execution flow of transactions:

1. Debugging failed transactions by tracing the exact execution path.
2. Analyzing multi-hop transactions across multiple smart contracts.
3. Understanding fee distribution across a transaction's execution.
4. Building transaction explorers that show complete message flows.
5. Auditing smart contract interactions and their side effects.

Here's an example of getting a trace for a specific transaction:

<CodeGroup>
  ```shell shell theme={"system"}
  curl -X GET \
    'https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/traces?tx_hash=BhLJTdV2R6Vr5c3BAOjH8nFpnMYOuPcJvRlagGSKU88%3D&limit=1' \
    -H 'accept: application/json'
  ```
</CodeGroup>

<Tip>
  Traces are particularly useful for understanding Jetton and NFT transfers, which typically involve multiple internal messages between minter, wallet, and recipient contracts.
</Tip>


## OpenAPI

````yaml openapi/ton_node_api/v3/getTraces.json GET /traces
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:
  /traces:
    get:
      tags:
        - Traces
      summary: Get Traces
      description: Retrieves transaction traces by specified filters
      operationId: getTraces
      parameters:
        - name: trace_id
          in: query
          description: Trace ID to filter by
          schema:
            type: string
        - name: tx_hash
          in: query
          description: Transaction hash to get traces for
          schema:
            type: string
            default: BhLJTdV2R6Vr5c3BAOjH8nFpnMYOuPcJvRlagGSKU88=
        - name: tx_lt
          in: query
          description: Transaction logical time
          schema:
            type: integer
        - name: limit
          in: query
          description: Maximum number of traces to return
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          description: Number of traces 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:
                  traces:
                    type: array
                    items:
                      type: object
                      properties:
                        trace_id:
                          type: string
                          description: Unique identifier for the trace
                        external_hash:
                          type: string
                          description: >-
                            Hash of the external message that initiated the
                            trace
                        mc_seqno_start:
                          type: integer
                          description: Masterchain sequence number at trace start
                        mc_seqno_end:
                          type: integer
                          description: Masterchain sequence number at trace end
                        start_lt:
                          type: integer
                          description: Logical time at trace start
                        start_utime:
                          type: integer
                          description: Unix timestamp at trace start
                        end_lt:
                          type: integer
                          description: Logical time at trace end
                        end_utime:
                          type: integer
                          description: Unix timestamp at trace end
                        state:
                          type: string
                          description: Current state of the trace
                        pending_edges:
                          type: integer
                          description: Number of pending message edges
                        edges:
                          type: integer
                          description: Total number of message edges
                        nodes:
                          type: integer
                          description: Total number of transaction nodes
                        classification_state:
                          type: string
                          description: Classification state of the trace
                  address_book:
                    type: object
                    description: Address book mapping addresses to user-friendly names

````