Skip to main content
GET
/
traces
Get Traces
curl --request GET \
  --url https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/traces
{
  "traces": [
    {
      "trace_id": "<string>",
      "external_hash": "<string>",
      "mc_seqno_start": 123,
      "mc_seqno_end": 123,
      "start_lt": 123,
      "start_utime": 123,
      "end_lt": 123,
      "end_utime": 123,
      "state": "<string>",
      "pending_edges": 123,
      "edges": 123,
      "nodes": 123,
      "classification_state": "<string>"
    }
  ],
  "address_book": {}
}

​
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.
Get you own node endpoint todayStart for free and get your app to production levels immediately. No credit card required.You can sign up with your GitHub, X, Google, or Microsoft account.
TON pricing is the same for full, archive, v2, v3There’s no difference between a full node an archive node in data availability or pricing. All data is always available and all node requests are consumed as 1 request unit.

​
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: 
curl -X GET \
  'https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/traces?tx_hash=BhLJTdV2R6Vr5c3BAOjH8nFpnMYOuPcJvRlagGSKU88%3D&limit=1' \
  -H 'accept: application/json'
Traces are particularly useful for understanding Jetton and NFT transfers, which typically involve multiple internal messages between minter, wallet, and recipient contracts.

Query Parameters

​
trace_id
string

Trace ID to filter by

​
tx_hash
string
default:BhLJTdV2R6Vr5c3BAOjH8nFpnMYOuPcJvRlagGSKU88=

Transaction hash to get traces for

​
tx_lt
integer

Transaction logical time

​
limit
integer
default:10

Maximum number of traces to return

​
offset
integer
default:0

Number of traces to skip

​
sort
enum<string>
default:desc

Sort order

Available options:
asc,
desc

Response

200 - application/json

Successful response

​
traces
object[]
​
address_book
object

Address book mapping addresses to user-friendly names