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

​
Pending Traces

The pendingTraces endpoint retrieves traces that are pending completion in the TON blockchain. These represent transaction execution flows that have not yet fully propagated through all necessary contracts.
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.
  • limit (integer, optional) — Maximum number of traces to return. Default: 10.
  • offset (integer, optional) — Number of traces to skip for pagination. Default: 0.

​
Response

  • traces (array) — Array of pending trace objects:
    • trace_id (string) — Trace ID.
    • external_hash (string) — Hash of the external message.
    • mc_seqno_start (integer) — Start masterchain sequence number.
    • start_lt (integer) — Start logical time.
    • start_utime (integer) — Start unix timestamp.
    • state (string) — Trace state (e.g., pending).
    • pending_edges (integer) — Number of pending message edges.
    • edges (integer) — Total edges so far.
    • nodes (integer) — Total nodes so far.
  • address_book (object) — Address book mapping.

​
Use case

The pendingTraces endpoint is essential for tracking in-progress complex operations:
  1. Monitoring multi-hop transactions that involve several contracts.
  2. Tracking Jetton transfers waiting for completion across wallet contracts.
  3. Debugging stuck transactions by identifying pending message edges.
  4. Building real-time dashboards showing transaction progress.
  5. Implementing timeout alerts for transactions taking too long.
Here’s an example of getting pending traces: 
curl -X GET \
  'https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/pendingTraces?limit=5' \
  -H 'accept: application/json'
The pending_edges field indicates how many messages are still being processed. A trace completes when this reaches zero.

Query Parameters

​
trace_id
string

Filter by trace ID

​
limit
integer
default:10

Maximum number of traces to return

​
offset
integer
default:0

Number of traces to skip

Response

200 - application/json

Successful response

​
traces
object[]
​
address_book
object

Address book mapping