How to check your transaction status on TON

In this article, you will learn how to leverage TONX API to help check your transaction status in TON ecosystem within just 3 steps.

TON operates as an asynchronous chain, making it complex to handle different messages simultaneously.

To simplify this process, we’ve developed the BoC Status API, which lets you easily check whether a BoC has completed successfully or failed. If an error occurs, it may indicate that another issue is causing the failure.

But you would need to…

💡 Get your TONX API key first here https://auth.tonxapi.com/signup

1. Verify

Before sending transaction payload to the TON blockchain, we need to make sure the validity of transaction payload (or so-called Bag of Cells, BoCs). With the useful tool - VerifyBoC in the TONX API Lab, it makes it easier to make sure the correctness of your constructed result.

For example, you have the following string

te6cckEBAQEAcgAA34gAbFAPRwqZafhhKJJF2v7oEELywR6SIooJqoUKdgxXv0IDIL7slT2uW2k/gt2S
5mrNMZGGXeBoTnQfszA9pWbw5aEBEBzHS6Nk4L1I0MUPHgs3vouQpFpcFqn9qMUOxQYIcU1NGL/////4
AAAAEAQdbiiJ

Using TONX VerifyBoC tool

curl --request POST \
--url https://mainnet-rpc.tonxapi.com/v2/labs/3eadfde7-6e4e-4dcd-ac8c-776dcd1ec73e \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"id": 1,
"jsonrpc": "2.0",
"method": "verifyBoc",
"params": {
"boc": "te6cckEBAQEAcgAA34gAbFAPRwqZafhhKJJF2v7oEELywR6SIooJqoUKdgxXv0IDIL7slT2uW2k/gt2S5mrNMZGGXeBoTnQfszA9pWbw5aEBEBzHS6Nk4L1I0MUPHgs3vouQpFpcFqn9qMUOxQYIcU1NGL/////4AAAAEAQdbiiJ"
}
}
'

You will be able to inspect the detail information hiding in the BoC string

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "is_valid": true,
    "hash": "c266b9ed835ddb2d566de039963f9dcd89af3e23f88e67ac0abbd16024a25e9d",
    "message_type": "external-in message",
    "dst_address": "EQA2KAejhUy0_DCUSSLtf3QIIXlgj0kRRQTVQoU7BivfoUav",
    "body": "te6cckEBAQEATwAAmmQX3ZKntcttJ/BbslzNWaYyMMu8DQnOg/ZmB7Ss3hy0ICIDmOl0bJwXqRoYoePBZvfRchSLS4LVP7UYodigwQ4pqaMX/////wAAAAIAw1vCKw=="
  }
}

Please note that the property "dst_address" in the response as above mentioned. This is the “entrance” contract address which receives an (external) message sending from you. Therefore, make sure you do have the permission of sending messages from this address and this address have enough TON balance to execute the action you would like to do.

If you are testing codes at the TON testnet, TONX API provides faucet as well. Besides, here is a tutorial talking about wallet contracts which will be the most common type of entrance contracts.

If you get error messages during this step, there are many tutorial resources (e.g., this one) talking about constructing valid BoC and interacting with TON smart contracts. We strongly recommend you to take a look at our sample codes to boost your DApp development pipeline.

2. Send

When you sent the transaction payload to TON blockchain, i.e., using SendMessage method, you would see a 200 OK response message as the successful signal.

For example, you did the following HTTP request

curl --request POST \
--url https://testnet-rpc.tonxapi.com/v2/json-rpc/3eadfde7-6e4e-4dcd-ac8c-776dcd1ec73e \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"id": 1,
"jsonrpc": "2.0",
"method": "sendMessage",
"params": {
"boc": "te6cckEBAQEAcgAA34gAbFAPRwqZafhhKJJF2v7oEELywR6SIooJqoUKdgxXv0IDIL7slT2uW2k/gt2S5mrNMZGGXeBoTnQfszA9pWbw5aEBEBzHS6Nk4L1I0MUPHgs3vouQpFpcFqn9qMUOxQYIcU1NGL/////4AAAAEAQdbiiJ"
}
}
'

This is an example of successful case you would see

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "@type": "ok",
    "@extra": "1734068276.3776543:0:0.8245238841308232"
  }
}

Please note that it is not allowed to send the same transaction payload twice by the TON blockchain protocol level. Most of beginners get errors in this step just because they accidentally send the message twice or they have not done the (1) Verify step as above mentioned.

3. Check

After sending the message, you may have a need for tracking the status of transaction processing. The powerful API - GetBoCStatus is just the thing you are willing to use.

Taking with the message content you sent in the (2) Send, calling GetBoCStatus API gives you the detailed state of your transaction processing that letting you do the proper handling after transaction sent.

Usually, it is almost instantly getting the response "broadcasted" which represents the message has been sent to the group of TON validators. After a few seconds of TON block production and indexing procedure, it is available for querying the TON blockchain result by calling GetMessages API. It is also possible getting the response "confirm" which indicates the transaction had been recorded permanently in the blockchain history.

For example, you did the following HTTP request

curl --request POST \
--url https://mainnet-rpc.tonxapi.com/v2/labs/3eadfde7-6e4e-4dcd-ac8c-776dcd1ec73e \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"id": 1,
"jsonrpc": "2.0",
"method": "getBocStatus",
"params": {
"boc": "te6cckEBAQEAcgAA34gAbFAPRwqZafhhKJJF2v7oEELywR6SIooJqoUKdgxXv0IDIL7slT2uW2k/gt2S5mrNMZGGXeBoTnQfszA9pWbw5aEBEBzHS6Nk4L1I0MUPHgs3vouQpFpcFqn9qMUOxQYIcU1NGL/////4AAAAEAQdbiiJ"
}
}
'

This is an example of successful case you would see

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": [
    {
      "hash": "wma57YNd2y1WbeA5lj+dzYmvPiP4jmesCrvRYCSiXp0=",
      "status": "confirm",
      "created_at": 1734068270
    }
  ]
}

The "hash" value in the response body would be useful when you calling GetMessages API. Here is an example of calling this API.

curl --request POST \
--url https://mainnet-rpc.tonxapi.com/v2/json-rpc/3eadfde7-6e4e-4dcd-ac8c-776dcd1ec73e \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"id": 1,
"jsonrpc": "2.0",
"method": "getMessages",
"params": {
"limit": 1,
"hash": "wma57YNd2y1WbeA5lj+dzYmvPiP4jmesCrvRYCSiXp0="
}
}
'

This is an example of successful case you would see

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": [
    {
      "hash": "wma57YNd2y1WbeA5lj+dzYmvPiP4jmesCrvRYCSiXp0=",
      "source": "",
      "source_friendly": "",
      "destination": "0:362807a3854cb4fc30944922ed7f74082179608f49114504d542853b062bdfa1",
      "destination_friendly": "EQA2KAejhUy0_DCUSSLtf3QIIXlgj0kRRQTVQoU7BivfoUav",
      "value": "0",
      "fwd_fee": "0",
      "ihr_fee": "0",
      ...
    }
  ]
}