Reading from network

Introduction

This guide will walk you through reading data from TON Blockchain. You'll learn how to:

Fetch account information
Call get methods
Retrieve account transactions

By the end, you'll understand how to interact with TON HTTP-based APIs. In this guide, TON Center is used—a fast and reliable HTTP API for TON.

Set up environment

First, visit the installation pages and install Node.js and npm for your OS. Check that the installation is correct by running the following commands:

node -v
npm -v

Versions of node and npm should be at least v20 and v10 correspondingly.

Project setup

Let’s set up your project structure:

Create a new directory for your project and navigate into it.
Initialize a Node.js project.
Install the required dependencies.
Initialize TypeScript configuration.

Run these commands in your terminal:

mkdir reading-from-ton && cd reading-from-ton
npm init -y
npm install typescript ts-node @ton/ton @ton/core @ton/crypto
npx tsc --init

To run a TypeScript script saved as script.ts in your current directory, run:

npx ts-node script.ts

Reading account information

Account information includes the balance, state, code, and data.

balance: The amount of TON the account holds.
state: Can be one of:
- Nonexist: The address has no data.
- Uninit: The address has a balance but no smart contract code.
- Active: The address is live with code and balance.
- Frozen: The address is locked due to insufficient balance for storage costs.
code: The contract's code in raw format.
data: Serialized contract data stored in a Cell.

Account state may be obtained using the getContractState method.

Implementation

Create a new file 1-get-account-state.ts:

1-get-account-state.ts
import { Address, TonClient } from "@ton/ton";

async function main() {
  // Initializaing TON HTTP API Client
  const tonClient = new TonClient({
    endpoint: 'https://testnet.toncenter.com/api/v2/jsonRPC',
  });

  const accountAddress = Address.parse('0QD-SuoCHsCL2pIZfE8IAKsjc0aDpDUQAoo-ALHl2mje04A-'); // Replace with any address

  // Calling method on http api
  const state = await tonClient.getContractState(accountAddress);


  console.log('State: ', state.state);
  console.log('Balance: ', state.balance);
  console.log('Data: ', state.data?.toString('hex'));
  console.log('Code: ', state.code?.toString('hex'));
}

main();

Run this example using the following command:

npx ts-node 1-get-account-state.ts

Expected result

State:  active
Balance:  3722511000883n
Data:  b5ee9c7241010101002...fd1e976824402aa67b98
Code:  b5ee9c7241021401000...c9ed54696225e5

Calling get methods

Get methods are special functions in smart contracts that allow you to observe the current state of a smart contract. Their execution doesn't cost any fees and can't change the smart contract's storage.

The result of calling a get method from the TON HTTP API comes in stack format and may be deserialized one by one using readNumber() or a similar function.

Implementation

Create a new file 2-call-get-method.ts:

2-call-get-method.ts
import { Address, TonClient, TupleBuilder } from "@ton/ton";

async function main() {
  // Initializaing TON HTTP API Client
  const tonClient = new TonClient({
    endpoint: 'https://testnet.toncenter.com/api/v2/jsonRPC',
  });

  // Building optional get method parameters list
  const builder = new TupleBuilder();
  builder.writeAddress(Address.parse('0QD-SuoCHsCL2pIZfE8IAKsjc0aDpDUQAoo-ALHl2mje04A-'));

  const accountAddress = Address.parse('kQD0GKBM8ZbryVk2aESmzfU6b9b_8era_IkvBSELujFZPsyy')

  // Calling http api to run get method on specific contract
  const result = await tonClient.runMethod(
    accountAddress, // address to call get method on
    'get_wallet_address', // method name
    builder.build(), // optional params list
  );

  // Deserializing get method result
  const address = result.stack.readAddress();
  console.log(address.toRawString());
}

main();

Run this example using the following command:

npx ts-node 2-call-get-method.ts

Expected result

0:25f2bf1ce8f83ed0c0fd73ea27aac77093cdcf900c750b071df7fb0288e019b2

Get methods may also be called using Tonviewer:

Navigate to the get methods section.
Select get_wallet_address.
Insert the address from the example 0QD-SuoCHsCL2pIZfE8IAKsjc0aDpDUQAoo-ALHl2mje04A- into the slice section.
Press Execute.

You will end up with the same address you got from the console.

Using wrappers for simplicity

Wrappers are classes that simplify interactions with smart contracts by turning complex blockchain operations into simple function calls. Instead of manually serializing cells and transactions, you can just call methods like jettonMaster.getWalletAddress() that already perform these tasks for you. Here's an example of using a wrapper functionally equivalent to the previous code snippet:

import { Address, JettonMaster, TonClient } from "@ton/ton";

async function main() {
  // Initializaing TON HTTP API Client
  const tonClient = new TonClient({
    endpoint: 'https://testnet.toncenter.com/api/v2/jsonRPC',
  });

  // Initializing wrappers
  const jettonMaster = tonClient.open(
    JettonMaster.create(Address.parse('kQD0GKBM8ZbryVk2aESmzfU6b9b_8era_IkvBSELujFZPsyy')),
  );

  // Calling get method through wrapper
  const address = jettonMaster.getWalletAddress(Address.parse('0QD-SuoCHsCL2pIZfE8IAKsjc0aDpDUQAoo-ALHl2mje04A-'));
  console.log(address);
}

main();

Fetching account transactions

Interaction within an account on the blockchain happens due to messages and transactions.

What is a transaction?

A transaction in TON consists of the following:

The incoming message that initially triggers the contract (special ways to trigger exist)
Contract actions caused by the incoming message, such as an update to the contract's storage (optional)
Outgoing messages generated and sent to other actors (optional)

Key transaction fields

A transaction obtained from the API has the following structure:

{
  "@type": "raw.transaction",
  "address": {
    "@type": "accountAddress",
    "account_address": "EQD-SuoCHsCL2pIZfE8IAKsjc0aDpDUQAoo-ALHl2mje02Zx"
  },
  "utime": 1738588970,
  ...
  "in_msg": {
    ...
  },
  "out_msgs": [...]
}

address: The account address where the transaction occurred.
utime: The unix timestamp of the transaction.
in_msg: The incoming message that triggered the transaction.
out_msgs: Outgoing messages sent during the transaction.

What is a message?

A message is a packet of data exchanged between actors (users, applications, or smart contracts). It typically contains information instructing the receiver on what action to perform, such as updating storage or sending a new message.

Key message fields

{
  "@type": "raw.message",
  "hash": "mcHdqltDAB8ODQHqtedtYQIS6MQL7x4ut+nf9tXWGqg=",
  "source": "EQAJTegD8OO-HksHfI4KVDqb7vW9Dlqi5C1FTcL1dECeosTf",
  "destination": "EQD-SuoCHsCL2pIZfE8IAKsjc0aDpDUQAoo-ALHl2mje02Zx",
  "value": "20000000",
  ...
  "msg_data": {
    "@type": "msg.dataRaw",
    "body": "te6cckEBAQEAAgAAAEysuc0=",
    ...
  },
  ...
}

source: The address of the sender (the account that initiated the message).
destination: The address of the receiver (the account that will process the message).
value: The amount of TON (in nanoTON) attached to the message.
msg_data: Contains the message body and state initialization.

Implementation

Create a new file 3-fetch-account-transaction.ts:

3-fetch-account-transaction.ts
import { Address, TonClient } from "@ton/ton";

async function main() {
  // Initializaing TON HTTP API Client
  const tonClient = new TonClient({
    endpoint: 'https://testnet.toncenter.com/api/v2/jsonRPC',
  });

  // Calling method on http api
  // full api: https://testnet.toncenter.com/api/v2/#/accounts/get_transactions_getTransactions_get
  const transactions = await tonClient.getTransactions(
    Address.parse('0QD-SuoCHsCL2pIZfE8IAKsjc0aDpDUQAoo-ALHl2mje04A-'), // Address to fetch transactions
    {
      limit: 10,      //maximum ammount of recieved transactions
      archival: true, //search in all history
    },
  );

  const firstTx = transactions[0];
  const { inMessage } = firstTx;

  console.log('Timestamp:', firstTx.now);
  if (inMessage?.info?.type === 'internal') {
    console.log('Value:', inMessage.info.value.coins);
    console.log('Sender:', inMessage.info.src);
  }
}

main();

Run this example using following command:

npx ts-node 3-fetch-account-transaction.ts

Expected result

Timestamp: 1743516631
Value: 100000000n
Sender: EQBui16XCF61MSWauIDpVFbKAOJmjLHRxXvXeqiN9dYaIgjq

info

A more complex example of traversing transactions graph may be found here.

Next step

Now that you’ve learned how to read data from TON Blockchain, it’s time to explore how to write data to the network.

Click the button below to continue:

Writing to the network

Was this article useful?

Introduction​

Set up environment​

Project setup​

Reading account information​

Implementation​

Expected result​

Calling get methods​

Implementation​

Expected result​

Using wrappers for simplicity​

Fetching account transactions​

What is a transaction?​

Key transaction fields​

What is a message?​

Key message fields​

Implementation​

Expected result​

Next step​

Introduction

Set up environment

Project setup

Reading account information

Implementation

Expected result

Calling get methods

Implementation

Expected result

Using wrappers for simplicity

Fetching account transactions

What is a transaction?

Key transaction fields

What is a message?

Key message fields

Implementation

Expected result

Next step