TON blockchain data analysis skill for Claude Code, Codex, and local agents. Built around Dune Analytics, TONAPI, and context-efficient reference files.
- Generates Dune SQL queries for TON on-chain analysis
- Executes queries via Dune API and analyzes results
- Covers supply distribution, wallet analysis, token flows, DeFi activity, staking, CEX flows, trading-bot adoption, DEX bots/MEV
- Includes battle-tested SQL patterns for 13-category supply classification, real user filtering, whale tiers
Install once, then restart the agent so it reloads available skills.
Install from the Claude Code marketplace:
/plugin marketplace add ohld/ton-analyst
/plugin install ton-analyst@ton-analyst
This adds the repo as a marketplace source and installs the skill.
Codex loads skills from ${CODEX_HOME:-~/.codex}/skills. Clone the repo once,
then install the skill:
git clone https://github.com/ohld/ton-analyst.git
cd ton-analyst
./setup --host codex
Relaunch Codex after installation so the skill is reloaded. The installer is idempotent: rerunning it updates the symlink if the checkout moved.
For agents that read ~/.agents/skills, run:
./setup --host agents
For a local Claude-style personal skill install, run:
./setup --host claude
Auto-update is enabled by default. On every skill invocation, ton-analyst checks
the published VERSION file before analysis starts.
- Git-backed installs fast-forward from
origin/mainwhen the checkout is clean. - Copied/plugin installs download the GitHub archive and replace local skill files with a backup.
- To pin a local copy temporarily, set
TON_ANALYST_AUTO_UPDATE=0.
Full flow: skills/ton-analyst/reference/update-flow.md.
To update manually in Claude Code:
/plugin marketplace update ton-analyst
/plugin update ton-analyst@ton-analyst
/reload-plugins
Claude Code can also auto-update marketplaces at startup when auto-update is enabled for the marketplace in /plugin → Marketplaces.
For Codex/local git installs, manual update is still:
git -C /path/to/ton-analyst pull --ff-only
After installing, ask your agent:
"What is the current TON supply breakdown by holder type?"
"How many real wallets hold 10K+ TON over time?"
"Show me net value flows between Binance and DeDust in the last 30 days"
The skill provides table schemas, reusable CTEs, and SQL conventions so Claude can generate correct queries on the first try.
Ships alongside the skill. Replaces the common curl https://tonapi.io/... | python3 -c "..." pattern with a single command that outputs terse TSV and aggressively prunes heavy technical fields (bytecode, phases, state updates, fees). Typical ton tx call returns ~80× less data than the raw TONAPI response.
ton acc <addr> address, label, status, balance_ton, flags, top_jettons
ton tx <addr> [--out/--in/--min-value/--since/--before/--dest/--limit/--before-lt/--json]
Install (one command, creates a venv and drops a wrapper at ~/.local/bin/ton):
./skills/ton-analyst/setup
Python 3.10+, deps = httpx + pytoniq-core. Optional env: TONAPI_API_KEY (higher rate limits), TON_LABELS_CACHE (default ~/.cache/ton-labels). Full reference: skills/ton-analyst/reference/cli.md. Future subcommand ideas: skills/ton-analyst/bin/TODO.md.
skills/ton-analyst/
├── SKILL.md # Entry point — update check, routing, core rules
├── VERSION # Runtime version used by the update checker
├── bin/
│ ├── ton # TONAPI CLI wrapper
│ ├── ton-analyst-bootstrap # update-before-use entrypoint
│ ├── ton-analyst-update-check
│ ├── ton-analyst-upgrade # git/archive updater
│ └── TODO.md # deferred subcommand ideas
├── setup # venv + wrapper installer
├── pyproject.toml # CLI dependencies and pytest config
├── uv.lock
├── tests/ # pytest suite, httpx.MockTransport — no network
└── reference/
├── index.md # Route tasks to the smallest useful reference
├── cli.md # `ton` CLI reference
├── report-format.md # mandatory report + query-log rules
├── update-flow.md # Versioning and local/marketplace update flow
├── local-learnings.md # Repeated mistakes before promotion to refs
├── dune/ # MCP/API workflow, asset constants, schemas, examples, patterns
├── ton/ # TON model, TONAPI, labels, Fragment, wallet investigation
└── techniques/ # CEX flows, staking, vesting, MEV, MAU, fees
ton.accounts,ton.messages,ton.balances_history,ton.jetton_eventston.prices_daily,ton.dex_trades,ton.latest_balancesdune.ton_foundation.dataset_labels— named entities (~3,150)dune.ton_foundation.result_custodial_wallets— custodial deposit wallets; includes CEX and non-CEX categoriesdune.ton_foundation.result_external_balances_history— DeFi positionsdune.ton_foundation.result_sybil_wallets,result_nominators_cashflow
- Clone the repo
- Install locally:
./setup --host codex,./setup --host agents, or./setup --host claude - Edit files in
skills/ton-analyst/ - Run validation:
python3 scripts/validate-skill.py - Run tests:
cd skills/ton-analyst && uv run pytest - Submit a PR with your changes
Architecture backlog: docs/professionalization-plan.md.
- New SQL examples — add
.sqlfiles inreference/dune/examples/ - New table schemas or gotchas — edit
reference/dune/schemas/or the narrowreference/dune/patterns/page - New labels or address discoveries — edit the narrow
reference/ton/page - Bug fixes in existing SQL — edit the relevant file
- Dune TON Tables Overview
- TON Documentation
- TON Verticals Dashboard
- TON DEX traders smart-contract evolution
- Trading Bots on TON
- Dune Spellbook — TON models
- ton-studio/ton-labels — address labels source
- TON On-Chain Data Analysis on Dune
- How to Analyze TON Users and Token Flows
PRs welcome! If you find a new code_hash, a missing label, or a better SQL pattern — please contribute.
x.com/danokhlopkov | t.me/danokhlopkov
MIT