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