Guides
SupportStatusSign UpLogin

TON - Retrieve Full Transaction Data via Transaction Hash

Suggest Edits

At the moment, retrieving full transaction data on the TON blockchain using only the transaction hash is not a straightforward single-call operation. Unlike other chains where you can directly query a transaction by hash, TON requires an additional step due to its message-based architecture.

Use Case

You have a transaction hash (let's call it Transaction A) and want to locate Transaction B, which contains the actual transfer details (the “in” message).

This is particularly useful for:

  • Reconciling discrepancies when multiple systems return different hashes for the same event.
  • Matching the user-facing transaction from a payment provider to the one returned by TON.

Steps

Step_1: Get the Outgoing Message Hash from Transaction Account A

  1. Use the Ton REST API endpoint /api/v3/transactions
  2. Inspect the out_msgs field in the response. It includes one or more message hash.

Example request:

curl --location 'https://ton-mainnet.gateway.tatum.io/api/v3/transactions?hash=ce727a6282114374362792a8edc29ca5fbcce00e0673ce222357d4e20864437a&limit=100&offset=0&sort=desc' \
--header 'x-api-key: {YOUR_API_KEY}'
//Response:
{
    "transactions": [
        {
     //additional response data
            "out_msgs": [
                {
                    "hash": "MkCOXJcRhjwSa/kwJowo/Ri/I8n4rFeJ11fFrFH2qkk=", //out message hash
                    "source": "0:079679B81C9D3F394B69A6829C798C296CA2EE6771FC15B6F72F365D661308C8",
                    "destination": "0:73D2DD86EE4180386EB7B2EAD3ECAA09DBC85AEDF4AB8815FADCDE7964C6428B",
                    "value": "6965224520",
                    "value_extra_currencies": {},
                    "fwd_fee": "266669",
                    "ihr_fee": "0",
                    "created_lt": "58862096000002",
                    "created_at": "1751210286",
                    "opcode": "0x00000000",
                    "ihr_disabled": true,
                    "bounce": false,
                    "bounced": false,
                    "import_fee": null,
                    "message_content": {
                        "hash": "P+k4lxWGmOTUc7dEFNdJNxaw/DpwMQk0hz8AGdqsyrQ=",
                        "body": "te6cckEBAQEABgAACAAAAADjAK8P",
                        "decoded": {
                            "type": "text_comment",
                            "comment": ""
                        }
                    },
                    "init_state": null
                }
            ],
//additional response data
    "address_book": {
        "0:079679B81C9D3F394B69A6829C798C296CA2EE6771FC15B6F72F365D661308C8": {
            "user_friendly": "UQAHlnm4HJ0_OUtppoKceYwpbKLuZ3H8Fbb3LzZdZhMIyIlA",
            "domain": null
        },
        "0:73D2DD86EE4180386EB7B2EAD3ECAA09DBC85AEDF4AB8815FADCDE7964C6428B": {
            "user_friendly": "UQBz0t2G7kGAOG63surT7KoJ28ha7fSriBX63N55ZMZCi_7l",
            "domain": null
        }
    }
}

📘

Note

Example based on TON Mainnet transaction HERE

Step_2: Use the Outgoing Message Hash to Locate Transaction B

  1. Take the hash from the out_msgs array from step_1
  2. Use the Ton REST API endpoint /api/v3/transactionsByMessage
  3. Inspect the transactions field in the response. It includes one or more message hash.

Example request:

curl --location 'https://ton-mainnet.gateway.tatum.io/api/v3/transactionsByMessage?direction=in&msg_hash=MkCOXJcRhjwSa/kwJowo/Ri/I8n4rFeJ11fFrFH2qkk=' \
--header 'x-api-key: {YOUR_API_KEY}'
//Response:
{
    "transactions": [
        {
            "account": "0:73D2DD86EE4180386EB7B2EAD3ECAA09DBC85AEDF4AB8815FADCDE7964C6428B",
            "hash": "fkzbCMBO82bD+CN7g2NKKWD7Mr0xpcMAFPp2TUClBGo=", //in message hash
          //additional response data
    "address_book": {
        "0:079679B81C9D3F394B69A6829C798C296CA2EE6771FC15B6F72F365D661308C8": {
            "user_friendly": "UQAHlnm4HJ0_OUtppoKceYwpbKLuZ3H8Fbb3LzZdZhMIyIlA",
            "domain": null
        },
        "0:73D2DD86EE4180386EB7B2EAD3ECAA09DBC85AEDF4AB8815FADCDE7964C6428B": {
            "user_friendly": "UQBz0t2G7kGAOG63surT7KoJ28ha7fSriBX63N55ZMZCi_7l",
            "domain": null
        }
    }
}

Step_3: Convert the Base64 Message Hash to Hex

📘

“Tatum's TON implementation returns base-64 hashes, but accepts either hex or base-64.”

  1. Take the in message hash (base64): fkzbCMBO82bD+CN7g2NKKWD7Mr0xpcMAFPp2TUClBGo=
  2. Convert the hash to hex: 7e4cdb08c04ef366c3f8237b83634a2960fb32bd31a5c30014fa764d40a5046a
  3. We can verify it matches with the Ton Explorer

Updated 9 days ago