How do I install the Tonapi skill?

Run npx skillmds@latest add elsvv/tonapi in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Tonapi skill do?

Use when the user needs to interact with TON blockchain via TonAPI — account balances, transactions, jetton/NFT data, smart contract methods, staking, DNS, rates, emulation, gasless transactions, webhooks, or streaming. Triggers: tonapi, ton api, TON blockchain, TON balance, jetton, NFT on TON, TON transaction, TON staking, TON DNS, .ton domain, TON wallet, TON rates, toncoin price, TON smart contract, TON emulation, gasless TON. It is listed under Integrations & APIs on SkillMD.

Is Tonapi safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Tonapi?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Tonapi free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Tonapi?

elsvv (@elsvv) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Tonapi by elsvv — Agent Skill

Name: Tonapi
Author: elsvv

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

Tonapi

File contents

tonapi

Config

Network

Quick Start

API Overview

Scripts

check_connection.sh

accounts.sh

blockchain.sh

jettons.sh

nft.sh

dns.sh

events.sh

traces.sh

staking.sh

rates.sh

wallet.sh

gasless.sh

multisig.sh

liteserver.sh

streaming.sh

webhooks.sh

utilities.sh

Key Concepts

Rate Limits

Detailed Reference

Frequently asked questions

Tonapi

File contents

tonapi

Config

Network

Quick Start

API Overview

Scripts

check_connection.sh

accounts.sh

blockchain.sh

jettons.sh

nft.sh

dns.sh

events.sh

traces.sh

staking.sh

rates.sh

wallet.sh

gasless.sh

multisig.sh

liteserver.sh

streaming.sh

webhooks.sh

utilities.sh

Key Concepts

Rate Limits

Detailed Reference

Related skills

Frequently asked questions

How do I install the Tonapi skill?

What does the Tonapi skill do?

Is Tonapi safe to use?

Which AI agents work with Tonapi?

Is Tonapi free to use?

Who published Tonapi?