> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/ecosystem/analytics",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Analytics and data providers

export const Aside = ({type = "note", title = "", icon = "", iconType = "regular", children}) => {
  const asideVariants = ["note", "tip", "caution", "danger"];
  const asideComponents = {
    note: {
      outerStyle: "border-sky-500/20 bg-sky-50/50 dark:border-sky-500/30 dark:bg-sky-500/10",
      innerStyle: "text-sky-900 dark:text-sky-200",
      calloutType: "note",
      icon: <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="w-4 h-4 text-sky-500" aria-label="Note">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
        </svg>
    },
    tip: {
      outerStyle: "border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10",
      innerStyle: "text-emerald-900 dark:text-emerald-200",
      calloutType: "tip",
      icon: <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="text-emerald-600 dark:text-emerald-400/80 w-3.5 h-auto" aria-label="Tip">
          <path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path>
        </svg>
    },
    caution: {
      outerStyle: "border-amber-500/20 bg-amber-50/50 dark:border-amber-500/30 dark:bg-amber-500/10",
      innerStyle: "text-amber-900 dark:text-amber-200",
      calloutType: "warning",
      icon: <svg className="flex-none w-5 h-5 text-amber-400 dark:text-amber-300/80" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-label="Warning">
          <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path>
        </svg>
    },
    danger: {
      outerStyle: "border-red-500/20 bg-red-50/50 dark:border-red-500/30 dark:bg-red-500/10",
      innerStyle: "text-red-900 dark:text-red-200",
      calloutType: "danger",
      icon: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor" className="text-red-600 dark:text-red-400/80 w-4 h-4" aria-label="Danger">
          <path d="M17.1 292c-12.9-22.3-12.9-49.7 0-72L105.4 67.1c12.9-22.3 36.6-36 62.4-36l176.6 0c25.7 0 49.5 13.7 62.4 36L494.9 220c12.9 22.3 12.9 49.7 0 72L406.6 444.9c-12.9 22.3-36.6 36-62.4 36l-176.6 0c-25.7 0-49.5-13.7-62.4-36L17.1 292zm41.6-48c-4.3 7.4-4.3 16.6 0 24l88.3 152.9c4.3 7.4 12.2 12 20.8 12l176.6 0c8.6 0 16.5-4.6 20.8-12L453.4 268c4.3-7.4 4.3-16.6 0-24L365.1 91.1c-4.3-7.4-12.2-12-20.8-12l-176.6 0c-8.6 0-16.5 4.6-20.8 12L58.6 244zM256 128c13.3 0 24 10.7 24 24l0 112c0 13.3-10.7 24-24 24s-24-10.7-24-24l0-112c0-13.3 10.7-24 24-24zM224 352a32 32 0 1 1 64 0 32 32 0 1 1 -64 0z"></path>
        </svg>
    }
  };
  let variant = type;
  let gotInvalidVariant = false;
  if (!asideVariants.includes(type)) {
    gotInvalidVariant = true;
    variant = "danger";
  }
  const iconVariants = ["regular", "solid", "light", "thin", "sharp-solid", "duotone", "brands"];
  if (!iconVariants.includes(iconType)) {
    iconType = "regular";
  }
  return <>
      <div className={`callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border ${asideComponents[variant].outerStyle}`} data-callout-type={asideComponents[variant].calloutType}>
        <div className="mt-0.5 w-4" data-component-part="callout-icon">
          {}
          {icon === "" ? asideComponents[variant].icon : <Icon icon={icon} iconType={iconType} size={14} />}
        </div>
        <div className={`text-sm prose min-w-0 w-full ${asideComponents[variant].innerStyle}`} data-component-part="callout-content">
          {gotInvalidVariant ? <p>
              <span className="font-bold">
                Invalid <code>type</code> passed!
              </span>
              <br />
              <span className="font-bold">Received: </span>
              {type}
              <br />
              <span className="font-bold">Expected one of: </span>
              {asideVariants.join(", ")}
            </p> : <>
              {title && <p className="font-bold">{title}</p>}
              {children}
            </>}
        </div>
      </div>
    </>;
};

Developers often need to run analytical queries on top of on-chain data — for example, to track historical changes and aggregate data from multiple accounts.

Since blockchains are not designed for analytical workloads, you need to build an indexing pipeline and run off-chain analytical queries.

Creating such pipelines from scratch can be resource-consuming, so we recommend using one of the tools mentioned on this page.

## Dune analytics

[Dune analytics](https://dune.com/) is one of the leading platforms for running analytical queries and building dashboards. It comes with 100+ blockchain integrations, and TON is among them. Basically, one needs to be familiar with SQL language to write queries, but the [Dune AI](https://docs.dune.com/learning/how-tos/dune-ai-prompt-engineering) prompt engine allows users to start working with data even without SQL knowledge.

### Raw and decoded tables

Dune analytics consumes data from the public [TON Data Lake](#public-data-lake) (see below) and comes with a variety of raw and decoded tables.

The [raw tables](https://dune.com/queries?category=canonical\&namespace=ton) include:

* [Blocks](https://docs.dune.com/data-catalog/ton/blocks)
* [Transactions](https://docs.dune.com/data-catalog/ton/transactions)
* [Messages](https://docs.dune.com/data-catalog/ton/messages) — includes raw body and `StateInit` data.
* [Balances history](https://docs.dune.com/data-catalog/ton/balances_history) — allows you to get a precise point-in-time balance for any account.
* [Jetton events](https://docs.dune.com/data-catalog/ton/jetton_events) — comes with transfers, burns, and mints.

<Aside>
  Since mints are not covered by the [TEP-74](https://github.com/ton-blockchain/TEPs/blob/master/text/0074-jettons-standard.md) standard, it is not possible to reconstruct balances based solely on jetton events, so the balance history should be used.
</Aside>

Apart from raw tables, there are decoded tables that allow you to work with high-level structures in a unified manner:

* [NFT events](https://dune.com/queries?category=canonical\&namespace=ton\&id=ton.nft_events) — comprehensive source of NFT-related data, including
  sales, transfers, and mints.
* [DEX trades](https://docs.dune.com/data-catalog/ton/dex_trades) — includes a unified data model for DEX trades. The full list of
  supported DEXs is available [here](https://github.com/ton-studio/ton-etl/blob/main/datalake/README.md#dex-trades).
* [DEX pools](https://docs.dune.com/data-catalog/ton/dex_pools) — comes with the full history of DEX pool balances and TVL estimations.

Finally, two tables with off-chain metadata are available:

* [Jetton metadata](https://docs.dune.com/data-catalog/ton/jetton_metadata)
* [NFT metadata](https://dune.com/queries?category=canonical\&namespace=ton\&id=ton.nft_metadata).

### Bespoke data marts

Dune analytics allows projects to build bespoke data marts for each protocol — it is widely used for EVMs with the help of ABIs.

#### Decoding raw data

Since TON handles complex [data structures](/foundations/serialization/cells/) and doesn't have ABIs, a [special decoding framework](https://github.com/duneanalytics/spellbook/blob/main/dbt_subprojects/daily_spellbook/macros/project/ton/README.md) was created. It works on top of the [Spellbook](https://github.com/duneanalytics/spellbook) — a powerful tool for building custom tables with [`dbt`](https://github.com/dbt-labs/dbt-core) and Jinja macros. It helps decode important information from raw protocol message payloads.

The following protocols are decoded using this framework and serve as examples:

* [EVAA](https://dune.com/queries?category=abstraction\&namespace=evaa) ([implementation](https://github.com/duneanalytics/spellbook/tree/main/dbt_subprojects/daily_spellbook/models/evaa/ton))
* [Affluent](https://dune.com/queries?category=abstraction\&namespace=affluent) ([implementation](https://github.com/duneanalytics/spellbook/tree/main/dbt_subprojects/daily_spellbook/models/affluent/ton))
* [StormTrade](https://dune.com/queries?category=abstraction\&namespace=stormtrade) ([implementation](https://github.com/duneanalytics/spellbook/tree/main/dbt_subprojects/daily_spellbook/models/stormtrade/ton))
* [TON DNS](https://dune.com/queries?category=abstraction\&namespace=dns_ton) ([implementation](https://github.com/duneanalytics/spellbook/tree/main/dbt_subprojects/daily_spellbook/models/ton/dns))

#### Custom views

In addition to decoding raw data, the Spellbook allows building custom materialized views. Some of them are widely used and maintained to be up to date:

* [ton.prices\_daily](https://dune.com/queries?category=abstraction\&namespace=ton\&id=ton.prices_daily) — prices calculated based on all other tables. The prices include jettons traded on DEXs, LP tokens for DEXs, perpetuals, tsUSDe, and other core assets. It is recommended to use this table if you need to build an estimation of assets denominated in TON or USD.
* [ton.accounts](https://dune.com/queries?category=abstraction\&namespace=ton\&id=ton.accounts) — materialized view with information about all accounts. It comes with the latest TON balance, interface (if any), funding information, and other fields.
* [ton.latest\_balances](https://dune.com/queries?category=abstraction\&namespace=ton\&id=ton.latest_balances) — helper table to get the latest balances for TON and Jettons.

<Aside>All tables mentioned above are updated daily.</Aside>

### Getting started with Dune

If you're just starting to explore TON data on Dune, we recommend checking these articles first:

<Columns cols={2}>
  <Card title="TON data quick start" arrow href="https://dune.com/ton_foundation/ton-quick-start" />

  <Card title="TON on-chain data analysis: quickstart on Dune" arrow href="https://blog.ton.org/ton-on-chain-data-analysis-dune" />

  <Card title="How to Analyze TON Users and Token Flows on Dune: A Practical Guide" arrow href="https://blog.ton.org/how-to-analyze-ton-users-and-token-flows-on-dune" />
</Columns>

For inspiration to build your own dashboards, check out these examples:

<Columns cols={2}>
  <Card title="Application Activity" arrow href="https://dune.com/ton_foundation/application-activity" />

  <Card title="TON & Ethena Boost Rewards Campaign" arrow href="https://dune.com/ton_foundation/tonandethena-staking-rewards-campaign" />

  <Card title="Telegram Gifts Dashboard" arrow href="https://dune.com/rdmcd/telegram-gifts" />
</Columns>

## Public Data Lake

Dune integration runs on the public data lake from the [TON-ETL](https://github.com/re-doubt/ton-etl/blob/main/datalake/README.md) project.

[TON-ETL](https://github.com/re-doubt/ton-etl/blob/main/datalake/README.md) is built on top of [TON Center](https://github.com/toncenter) indexer and allows extraction of data from TON Node into data formats suitable for MPP (Massively Parallel Processing) engines: Presto, Apache Spark, etc.

<Aside>
  You can deploy it on your own infrastructure or use publicly available data from the S3 bucket: `s3://aws-public-blockchain/v1.1/ton/`. This dataset is part of the [AWS Public Blockchain Data](https://registry.opendata.aws/aws-public-blockchain/) project and is optimized for use within the AWS big data stack.

  Examples of AWS Athena and AWS Bedrock integration can be found in this [article](https://repost.aws/articles/AR3ABC81yvTPW2ktfHiHPWIA/new-dataset-added-to-the-aws-public-blockchain-data-ton-the-open-network).
</Aside>

The TON-ETL extracts raw data and performs decoding to create a unified view of high-level on-chain activity. The most important part is decoding DEX activity.

The decoding implementation must solve the following tasks:

* Decoding of swap events. The code must check the authenticity of the swap. For example, you cannot rely on the opcode alone since anyone can generate messages with your opcode.
* Extracting all swap-related fields: tokens sold and bought, amounts, query IDs, trader, router (if any), and pool.
* Fetching pool reserves and LP token supply, if applicable.

To add support for a new DEX and decode its activity, you need to prepare a relevant PR on GitHub [to TON-ETL's repo](https://github.com/ton-studio/ton-etl). Use those past PRs as a reference: [BidAsk](https://github.com/ton-studio/ton-etl/pull/186), [CoffeeSwap](https://github.com/ton-studio/ton-etl/pull/171/files), [MemesLab](https://github.com/ton-studio/ton-etl/pull/144).

## Real-time streams

In addition to bulk data export, TON-ETL provides real-time data streaming via Kafka. A [public endpoint](https://github.com/ton-studio/ton-etl/blob/main/datalake/README.md#near-real-time--data-streaming-via-pulic-kafka-topics) is available free of charge for non-profit projects.

For projects that don't meet the non-profit criteria or require an in-house solution, you can deploy the infrastructure yourself by:

1. Running your own [TON node](/ecosystem/nodes/overview)
2. Launching [ton-etl](https://github.com/re-doubt/ton-etl/blob/main/README.md)
3. Setting up [ton-index-worker](https://github.com/ton-studio/ton-index-worker)

## TON Labels

While data availability and integrations are essential, building insightful dashboards requires enriching data with address labels.

The [TON Labels](https://github.com/ton-studio/ton-labels) project simplifies this process by providing a comprehensive taxonomy of addresses in TON Ecosystem. It covers active addresses across various categories, including centralized exchanges (CEXs), decentralized applications (dApps), and DeFi protocols.

You can access the latest labels either directly from [the build branch](https://github.com/ton-studio/ton-labels/blob/build/assets.json) or through Dune analytics using the [`dune.ton_foundation.dataset_labels`](https://dune.com/queries?category=uploaded_data\&id=dune.ton_foundation.dataset_labels) table.

## Other platforms

* [Chainbase](https://docs.chainbase.com/catalog/Ton/Overview) offers a set of raw and decoded tables with TON data. It allows you to run SQL queries and fetch results via API.
* [TON Console](https://docs.tonconsole.com/tonconsole/analytics) provides analysts with Analytics Service.
* [TokenTerminal](https://tokenterminal.com/explorer/projects/the-open-network) comes with high-level metrics across TON Ecosystem.
* [Artemis](https://app.artemisanalytics.com/project/ton?from=projects) contains key metrics for TON and allows you to build customized charts.
* [Spice harvester](https://github.com/txsociety/spice-harvester) supports high-load transaction monitoring and asset tracking on TON through a self-hosted API with access to invoice states and metadata.