TON - Retrieve Token Transaction Information

Suggest Edits

This guide explains how to retrieve Jetton token transaction history on the TON blockchain using Tatum's API. Jettons are tokenized assets on TON, similar to ERC-20 tokens on Ethereum.

Fetching Jetton Transactions

To retrieve token (Jetton) transaction history for a specific TON wallet address, use the JSON RPC request seen below.

Example Request:

curl --location 'https://ton-mainnet.gateway.tatum.io/api/v3/jetton/transfers?owner_address=UQDQE50D-x9pjfzk5H4cj14k1HD44TC1AtqHBjmqupeQGkSU&limit=50&offset=0&sort=desc' \
--header 'x-api-key: YOUR_API_KEY'
//Response:
{
    "jetton_transfers": [
        {
            "source": "0:0D3A5C...",
            "destination": "0:D0139D...",
            "amount": "3",
            "jetton_master": "0:B113A9...",
            "transaction_hash": "N6pp/FCPTTidFc3...",
            "transaction_now": 1740738811,
            "trace_id": "XrVfjxGI1p23vXJg..."
        },
        {
            "source": "0:0D3A5C...",
            "destination": "0:D0139D...",
            "amount": "10",
            "jetton_master": "0:B113A9...",
            "transaction_hash": "046zm5ADuQeeaDZp...",
            "transaction_now": 1740674886
        }
    ],
    "metadata": {
        "0:B113A994B5024A16719F69139328EB759596C38A25F59028B146FECDC3621DFE": {
            "token_info": [
                {
                    "name": "Tether USD",
                    "symbol": "USD₮",
                    "decimals": "6",
                    "description": "Tether Token for Tether USD"
                }
            ]
        }
    }

The response contains:

Field	Description
`source`	Sender address
`destination`	Receiver address
`amount`	Raw token amount (needs conversion)
`jetton_master`	Token contract address
`transaction_hash`	Unique transaction identifier
`transaction_now`	Unix timestamp of the transaction
`trace_id`	Internal trace ID
`metadata.token_info.symbol`	The token symbol (e.g., `USDT`)
`metadata.token_info.decimals`	Number of decimals (e.g., `6` for USDT)

Converting Token Amounts

Jettons use the smallest unit representation, meaning you need to divide by 10^decimals to get the real amount.

Steps:

Find the decimals value in the metadata
USDT metadata shows: "decimals": "6"
This means 1 USDT = 1,000,000 units (10⁶).
Convert the raw "amount" to a human-readable value
Divide the amount by 10^6. Example calculation:

Raw Amount (amount field) USDT Equivalent (amount / 10^6)
"amount": "3" 0.000003 USDT
"amount": "10" 0.00001 USDT

Raw Amount (`amount` field)	USDT Equivalent (`amount` / 10^6)
`"amount": "3"`	0.000003 USDT
`"amount": "10"`	0.00001 USDT

Good To Know

Find the official TON v3 endpoints HERE.

Updated 6 days ago