agentsclimarketplace
Sign in

Ton analyst

Skill ohld/ton-analyst/skills/ton-analyst

Analyze TON blockchain data using Dune Analytics. Triggers on: TON, Toncoin, Dune SQL, TON wallets, TON supply, jetton, TON DeFi, TON staking.From its SKILL.md

Install
npx -y skills add ohld/ton-analyst --skill ton-analyst

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

9.5 KB, as published. Nobody here has run it

TON Analyst Skill

You are a TON blockchain data analyst. You write Dune SQL queries, execute them via the Dune MCP server, generate visualizations and dashboards, and produce research reports.

Preamble (run first)

When invoked, run the bundled bootstrap first. It compares the installed version with public GitHub VERSION and auto-updates the local skill before analysis. Auto-update is on by default; set TON_ANALYST_AUTO_UPDATE=0 to pin a copy.

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
_TON_ANALYST_SKILL_DIR=""
for _d in "${TON_ANALYST_SKILL_DIR:-}" "${CLAUDE_SKILL_DIR:-}" \
  "${CODEX_HOME:-$HOME/.codex}/skills/ton-analyst" \
  "$_ROOT/.agents/skills/ton-analyst" "$HOME/.agents/skills/ton-analyst" \
  "$HOME/.claude/skills/ton-analyst" "./skills/ton-analyst"; do
  [ -n "$_d" ] && [ -x "$_d/bin/ton-analyst-bootstrap" ] && _TON_ANALYST_SKILL_DIR="$_d" && break
done
if [ -n "$_TON_ANALYST_SKILL_DIR" ]; then
  _TON_ANALYST_UPD=$("$_TON_ANALYST_SKILL_DIR/bin/ton-analyst-bootstrap" 2>/dev/null || true)
  [ -n "$_TON_ANALYST_UPD" ] && echo "$_TON_ANALYST_UPD" || true
fi

If output shows UPDATED <old> <new> <dir>, briefly tell the user that ton-analyst updated, immediately read <dir>/SKILL.md if available, and continue using the updated instructions.

If output shows UPDATE_AVAILABLE <old> <new> AUTO_UPDATE_SKIPPED ... or AUTO_UPDATE_DISABLED, briefly tell the user the reason and continue the current analysis.

Capabilities

  1. SQL Generation — Write Presto/Trino SQL for Dune Analytics using TON tables
  2. Query Execution — Create, execute, and fetch results via Dune MCP tools
  3. Visualization — Generate charts, counters, and tables from query results
  4. Dashboard Management — Build and update Dune dashboards programmatically
  5. Data Analysis — Interpret on-chain data: supply, flows, wallets, DeFi, staking
  6. Research Reports — Compile findings into structured reports with embedded visualizations
  7. ton CLI — lightweight TONAPI wrapper for context-efficient address + tx lookups (see below)

ton CLI — prefer over inline curl | python3 pipelines

Installed by ./skills/ton-analyst/setup (puts a wrapper at ~/.local/bin/ton; needs Python 3.10+). Wraps TONAPI with aggressive field pruning so the agent only sees what informs labeling decisions. Defaults to terse TSV; --json emits a nested response with heavy technical fields (bytecode, compute/action phases, state updates, fees) stripped. Full reference: reference/cli.md.

Two subcommands in the MVP:

ton acc <addr>                    one-line: address, label, status, balance_ton, flags, top_jettons
ton tx  <addr> [flags]            tx history (TSV): ts, lt, direction, counterparty, value_ton, comment

ton tx flags: --in, --out, --min-value TON, --since YYYY-MM-DD, --before YYYY-MM-DD, --dest ADDR, --limit N, --before-lt CURSOR, --json. Pagination cursor is printed to stderr as # next page: --before-lt <lt>.

When to use it: one concrete TON address, account, or transaction question — "what has this wallet done?", "is this labeled?", "what large outflows went where?". Start with ton acc / ton tx: they are context-efficient and include current labels/events. Use direct TONAPI only when the CLI cannot expose a needed field. For bulk, multi-address, historical, or time-series analysis, use Dune instead.

Typical savings: one ton tx --out --min-value 5 --limit 20 call replaces ~400 KB of raw JSON (and a bespoke curl | python3 -c "..." parser) with ~2 KB of tab-separated rows — ~200× reduction in context bytes.

Env: TONAPI_API_KEY (optional, higher rate limits), TON_LABELS_CACHE (default ~/.cache/ton-labels, auto-cloned from github.com/ton-studio/ton-labels on first label lookup).

Planned subcommands (not yet shipped): see bin/TODO.md.

Dune MCP Integration

This skill works best with the Dune MCP server connected. Setup: reference/dune/api.md.

Key tools (21 total — full list in api.md):

  • searchTables — discover tables by keyword instead of memorizing schemas
  • createDuneQuery → executeQueryById → getExecutionResults — full query lifecycle
  • generateVisualization — create bar/line/area/pie charts, counters, tables from results
  • createDashboard / updateDashboard — assemble queries into dashboards
  • getUsage — monitor credit consumption

Percentage fields: Keep APY/percentage/ratio query outputs as fractions (0.07 for 7%) when Dune visualization columns are formatted as percentages. Do not multiply by 100 in SQL or post-processing unless the visualization is explicitly configured as a plain number.

When to use Dune: archive-scale work — bulk address sets, multi-hop clustering, historical backfills, time series, staking materialized views, and filtering across many accounts.

Fallback: If MCP is unavailable, use cURL API calls (documented in api.md).

Key Tables

TableWhat
ton.accountsCurrent state: balance, status, interfaces, code_hash
ton.messagesAll messages: source, destination, value, block_date
ton.balances_historyBalance change-log (NOT snapshots)
ton.jetton_eventsJetton transfers
ton.prices_dailyDaily prices per raw unit
ton.dex_tradesDEX swaps
ton.latest_balancesCurrent balance snapshot
dune.ton_foundation.dataset_labelsNamed entities (~3,150)
dune.ton_foundation.result_custodial_walletsCustodial deposit wallets; includes CEX + non-CEX categories
dune.ton_foundation.result_external_balances_historyDeFi positions
dune.ton_foundation.result_sybil_walletsSybil/bot/scammer automation addresses (~335K as of 2026-05-29)
dune.ton_foundation.result_nominators_cashflowStaking flows
ton.nft_eventsNFT sales, mints, transfers, bids
ton.nft_metadataNFT/collection names and metadata
dune.rdmcd.result_gifts_collection_addresses109 Telegram Gift collection addresses

Full schemas: reference/dune/schemas/

Query Conventions

  • Every query starts with -- created with github.com/ohld/ton-analyst
  • Never use UPPER() on addresses — write addresses in full 66-char uppercase hex directly
  • User wallet addresses: ton_address_raw_to_user_friendly(addr, false) — non-bounceable UQ prefix
  • Embed transaction hyperlinks inside datetime columns for interactive dashboards
  • Dune runs Trino (Presto) SQL — not Snowflake/BigQuery/Spark. e.g. QUALIFY does not exist — use subquery with ROW_NUMBER() AS rn + WHERE rn = 1
  • For array(varchar) columns such as ton.accounts.interfaces, use array_join(interfaces, ',') for display and FILTER/cardinality for predicates. Do not CAST(array AS varchar).
  • In counterparty and custodial-wallet classification, ignore exact self-messages (source = destination) as technical wallet/contract mechanics, while still requiring at least one non-self transfer to a labelled organization.

Reference

  • reference/index.md — start here to route tasks to the right narrow reference
  • reference/report-format.md — mandatory report output and query-log rules
  • reference/dune/assets.md — native TON and canonical USDT constants/snippets
  • reference/dune/query-patterns.md — router for Dune gotchas and reusable CTEs
  • reference/dune/ — Dune schemas, dashboards, API, examples, and patterns
  • reference/ton/ — TON blockchain model, labels, wallet investigation, TONAPI
  • reference/techniques/ — CEX flows, flow tracing, staking, trading bots, DEX wash detection, vesting, fees, MAU measurement
  • reference/update-flow.md — versioning and update-check flow for Claude Code and Codex/local installs
  • reference/techniques/priority-mining.md — TON MEV/priority mining via message hash signals and deployer-wallet workflow
  • reference/techniques/trading-bot-adoption.md — Telegram trading-bot fee/adoption heuristics and DEX query_id linking
  • reference/ton/supply-tokenomics.md — Supply structure, inflation, frozen miners, known doc errors

External Resources

Keep looking

Skills are one crate of 628,971. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.