tonapi

TonAPI — REST API for TON blockchain: accounts, transactions, jettons, NFTs, staking, DNS, rates, emulation, webhooks.

Config

Requires TONAPI_TOKEN in config/.env. Get your token at TonConsole. See config/README.md for setup.

First-time setup:

cp config/.env.example config/.env
# Edit config/.env and paste your token
bash scripts/check_connection.sh

Network

Default: mainnet (https://tonapi.io). For testnet: pass --testnet flag to any script or set TONAPI_NETWORK=testnet in config/.env.

IMPORTANT: Always run scripts with bash prefix. Scripts use bash-specific features and will not work if sourced from zsh.

Quick Start

# 1. Check connection
bash scripts/check_connection.sh

# 2. Get account info
bash scripts/accounts.sh --action get --account UQDNzlh0XSZdb5_Qrlx5QjyZHVAO74v5oMeVVrtF_5Vt1rIt

# 3. Get jetton balances
bash scripts/accounts.sh --action jettons --account UQDNzlh0XSZdb5_Qrlx5QjyZHVAO74v5oMeVVrtF_5Vt1rIt

# 4. Get TON price
bash scripts/rates.sh --action get --tokens ton --currencies usd

# 5. Get masterchain head
bash scripts/blockchain.sh --action masterchain-head

API Overview

Category	Script	Key Features
Accounts	accounts.sh	Balance, events, jettons, NFTs, traces, bulk, search
Blockchain	blockchain.sh	Blocks, transactions, config, validators, send message, run methods
Jettons	jettons.sh	Metadata, holders, bulk, transfer payloads
NFT	nft.sh	Items, collections, bulk, history
DNS	dns.sh	Resolve, bids, auctions
Events	events.sh	Events, account events, emulation
Traces	traces.sh	Execution traces, emulation
Staking	staking.sh	Pools, nominators, history
Rates	rates.sh	Token prices, charts, markets
Wallet	wallet.sh	Wallet info, seqno, TonConnect
Gasless	gasless.sh	Config, estimate, send gasless tx
Multisig	multisig.sh	Multisig info, orders
LiteServer	liteserver.sh	Raw ADNL proxy (16 endpoints)
Streaming	streaming.sh	SSE: blocks, transactions, traces, mempool
Webhooks	webhooks.sh	Webhook CRUD, subscriptions, opcodes
Utilities	utilities.sh	Status, address parse, TonConnect

Scripts

check_connection.sh

Verify token and TonAPI availability.

bash scripts/check_connection.sh
bash scripts/check_connection.sh --testnet

accounts.sh

Account info, balances, events, jettons, NFTs.

# Account info
bash scripts/accounts.sh --action get --account <ADDR>

# Bulk accounts
bash scripts/accounts.sh --action bulk --accounts <ADDR1>,<ADDR2>

# Search by domain
bash scripts/accounts.sh --action search --query "wallet"

# Jetton balances
bash scripts/accounts.sh --action jettons --account <ADDR>

# Specific jetton
bash scripts/accounts.sh --action jetton --account <ADDR> --jetton <JETTON_ADDR>

# NFTs owned
bash scripts/accounts.sh --action nfts --account <ADDR> --limit 50

# Events history
bash scripts/accounts.sh --action events --account <ADDR> --limit 20

# Balance diff
bash scripts/accounts.sh --action diff --account <ADDR> --start-date 1700000000 --end-date 1700100000

# Public key
bash scripts/accounts.sh --action publickey --account <ADDR>

# Traces
bash scripts/accounts.sh --action traces --account <ADDR>

# Jetton transfer history
bash scripts/accounts.sh --action jettons-history --account <ADDR>

# NFT transfer history
bash scripts/accounts.sh --action nfts-history --account <ADDR>

# Reindex cache
bash scripts/accounts.sh --action reindex --account <ADDR>

Param	Description
--action	get, bulk, search, dns, events, jettons, jetton, nfts, traces, subscriptions, publickey, diff, jettons-history, nfts-history, multisigs, reindex
--account	Account address
--accounts	Comma-separated addresses (bulk)
--jetton	Jetton master address
--query	Search query
--limit	Max results
--offset	Offset
--before-lt	Cursor: before logical time
--start-date	Unix timestamp start
--end-date	Unix timestamp end

blockchain.sh

Blocks, transactions, methods, send messages.

# Masterchain head
bash scripts/blockchain.sh --action masterchain-head

# Transaction by hash
bash scripts/blockchain.sh --action transaction --tx-hash <HASH>

# Account transactions
bash scripts/blockchain.sh --action account-transactions --account <ADDR> --limit 10

# Run smart contract method
bash scripts/blockchain.sh --action run-method --account <ADDR> --method get_wallet_address --args "0:addr..."

# Send message
bash scripts/blockchain.sh --action send --boc <BASE64_BOC>

# Validators
bash scripts/blockchain.sh --action validators

# Blockchain config
bash scripts/blockchain.sh --action config

# Inspect contract
bash scripts/blockchain.sh --action inspect --account <ADDR>

Param	Description
--action	masterchain-head, block, block-transactions, shards, blocks, transactions, config, config-by-block, transaction, msg-transaction, account-raw, account-transactions, inspect, run-method, send, validators, reduced-blocks
--block-id	Block ID
--seqno	Masterchain seqno
--tx-hash	Transaction hash
--msg-hash	Message hash
--account	Account address
--method	Smart contract method name
--args	Comma-separated method args
--boc	Base64-encoded BOC
--batch	Comma-separated BOCs (max 5)
--limit	Max results (max 1000)
--before-lt / --after-lt	Cursor
--sort-order	asc or desc

jettons.sh

Jetton token data and holders.

# List all jettons
bash scripts/jettons.sh --action list --limit 20

# Jetton metadata
bash scripts/jettons.sh --action get --jetton <MASTER_ADDR>

# Holders
bash scripts/jettons.sh --action holders --jetton <MASTER_ADDR> --limit 50

# Bulk metadata
bash scripts/jettons.sh --action bulk --addresses <ADDR1>,<ADDR2>

nft.sh

NFT items and collections.

# Get NFT item
bash scripts/nft.sh --action get --address <NFT_ADDR>

# List collections
bash scripts/nft.sh --action collections --limit 20

# Collection items
bash scripts/nft.sh --action collection-items --address <COLLECTION_ADDR> --limit 50

# Bulk NFTs
bash scripts/nft.sh --action bulk --addresses <ADDR1>,<ADDR2>

dns.sh

TON DNS domains and auctions.

# Domain info
bash scripts/dns.sh --action info --domain wallet.ton

# DNS resolve
bash scripts/dns.sh --action resolve --domain wallet.ton

# Domain bids
bash scripts/dns.sh --action bids --domain wallet.ton

# All auctions
bash scripts/dns.sh --action auctions

events.sh

High-level events (human-readable transaction actions).

# Event by ID
bash scripts/events.sh --action get --event-id <ID>

# Account events
bash scripts/events.sh --action account-events --account <ADDR> --limit 10

# Emulate
bash scripts/events.sh --action emulate --boc <BASE64>

traces.sh

Full execution traces.

# Trace by ID or tx hash
bash scripts/traces.sh --action get --trace-id <ID>

# Emulate trace
bash scripts/traces.sh --action emulate --boc <BASE64> --ignore-signature

staking.sh

Staking pools and nominators.

# All pools
bash scripts/staking.sh --action pools

# Pool info
bash scripts/staking.sh --action pool --account <POOL_ADDR>

# Nominator's pools
bash scripts/staking.sh --action nominator-pools --account <ADDR>

rates.sh

Token prices and charts.

# TON price
bash scripts/rates.sh --action get --tokens ton --currencies usd,eur

# Jetton price
bash scripts/rates.sh --action get --tokens <JETTON_ADDR> --currencies usd

# Price chart
bash scripts/rates.sh --action chart --token ton --currency usd --points 100

# Markets
bash scripts/rates.sh --action markets

wallet.sh

Wallet operations and TonConnect.

# Wallet info
bash scripts/wallet.sh --action get --account <ADDR>

# Seqno
bash scripts/wallet.sh --action seqno --account <ADDR>

# Wallets by pubkey
bash scripts/wallet.sh --action by-pubkey --pubkey <HEX>

# Emulate wallet message
bash scripts/wallet.sh --action emulate --boc <BASE64>

gasless.sh

Gasless (fee-free) transactions.

# Gasless config
bash scripts/gasless.sh --action config

# Estimate
bash scripts/gasless.sh --action estimate --master <JETTON_ADDR> \
  --wallet <WALLET_ADDR> --pubkey <HEX> --boc <HEX_MSG>

# Send
bash scripts/gasless.sh --action send --pubkey <HEX> --boc <BASE64>

multisig.sh

Multisig wallets.

bash scripts/multisig.sh --action get --account <ADDR>
bash scripts/multisig.sh --action order --account <ORDER_ADDR>

liteserver.sh

Raw Lite Server proxy (low-level).

bash scripts/liteserver.sh --action masterchain-info
bash scripts/liteserver.sh --action account-state --account <ADDR>
bash scripts/liteserver.sh --action time

streaming.sh

SSE real-time streaming.

# Stream all transactions
bash scripts/streaming.sh --action transactions --accounts ALL

# Stream specific accounts
bash scripts/streaming.sh --action transactions --accounts <ADDR1>,<ADDR2>

# Stream blocks
bash scripts/streaming.sh --action blocks --workchain -1

# Stream mempool
bash scripts/streaming.sh --action mempool

webhooks.sh

Webhook management (rt.tonapi.io).

# Create webhook
bash scripts/webhooks.sh --action create --endpoint https://your-server.com/webhook

# List webhooks
bash scripts/webhooks.sh --action list

# Subscribe to account transactions
bash scripts/webhooks.sh --action subscribe-tx --webhook-id <ID> --accounts <ADDR1>,<ADDR2>

# Subscribe to opcode
bash scripts/webhooks.sh --action subscribe-opcode --webhook-id <ID> --opcode 0x0524c7ae

# Delete webhook
bash scripts/webhooks.sh --action delete --webhook-id <ID>

utilities.sh

Service status and address parsing.

# Service status
bash scripts/utilities.sh --action status

# Parse address (all formats)
bash scripts/utilities.sh --action parse-address --address <ADDR>

Key Concepts

Concept	Description
nanoTON	1 TON = 10^9 nanoTON. All amounts in nanoTON
Addresses	Raw (0:hex) or base64url (EQ.../UQ...). Use utilities.sh parse-address to convert
BOC	Bag of Cells — binary TON serialization, base64-encoded
Logical Time (lt)	Transaction ordering, used for cursor pagination
Events	High-level human-readable actions (display only, structure may change)
Traces	Full execution trees of transactions

Rate Limits

Condition	Limit
Without API key	0.25 RPS (1 req / 4 sec)
With API key	Per plan (see pricing)
Testnet + mainnet	Shared limits

Detailed Reference

Full endpoint list with schemas, params, and response formats: references/api-reference.md