pendingTraces | TON v3

The pendingTraces endpoint retrieves traces that are pending completion in the TON blockchain. Available on TON v3 via Chainstack.

GET /pendingTraces

Get Pending Traces

cURL

curl --request GET \
  --url https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/pendingTraces

200

{
  "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 your own node endpoint today

Start 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 billing: full (1 RU)

This method is always billed as full. See Request units — TON method scope.

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:

shell

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[]

Show child attributes

address_book · object

Address book mapping