---
name: analyzing-on-chain-data
description: 'Process perform on-chain analysis including whale tracking, token flows, and network activity.

  Use when performing crypto analysis.

  Trigger with phrases like "analyze crypto", "check blockchain", or "monitor market".'
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(crypto:onchain-*)
version: 1.29.0
author: Jeremy Longshore <jeremy@intentsolutions.io>
license: MIT
tags:
  - crypto
  - monitoring
  - analyzing-on
compatibility: Designed for Claude Code
title: analyzing-on-chain-data
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data
last_updated: 2026-10-23T05:08:30.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [ARD.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/ARD.md), [config/settings.yaml](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/config/settings.yaml), [PRD.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/PRD.md), [references/errors.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/references/errors.md), [references/examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/references/examples.md), [references/implementation.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/references/implementation.md), [scripts/data_fetcher.py](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/scripts/data_fetcher.py), [scripts/formatters.py](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/scripts/formatters.py), [scripts/metrics_calculator.py](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/scripts/metrics_calculator.py), [scripts/onchain_analytics.py](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/scripts/onchain_analytics.py).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/analyzing-on-chain-data`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/analyzing-on-chain-data`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/analyzing-on-chain-data --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/analyzing-on-chain-data --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Analyzing On-Chain Data

## Overview

Analyze DeFi protocol metrics, chain-level TVL, fee revenue, DEX volumes, yield opportunities, and stablecoin market caps using DeFiLlama as the primary data source. Designed for DeFi researchers, protocol analysts, and yield farmers who need programmatic access to on-chain analytics without writing custom subgraph queries.

## Prerequisites

- Python 3.8+ with `requests` library installed
- DeFiLlama API access (free, no key required for most endpoints)
- Optional: CoinGecko API key for supplementary token price data
- `onchain_analytics.py` CLI script available in the plugin directory
- `data_fetcher.py` and `metrics_calculator.py` modules for programmatic usage

## Instructions

1. Run `python onchain_analytics.py protocols` to retrieve the top DeFi protocols ranked by total value locked (TVL).
2. Filter protocol results by category using `--category lending`, `--category dex`, or `--category "liquid staking"` to narrow the scope.
3. Filter by chain with `--chain ethereum` or `--chain arbitrum` to isolate chain-specific protocol data.
4. Sort results by alternative metrics using `--sort market_share` or `--sort tvl_to_mcap` to surface undervalued protocols.
5. Run `python onchain_analytics.py chains` to retrieve chain-level TVL rankings across all tracked networks.
6. Run `python onchain_analytics.py fees --protocol aave` to pull fee and revenue data for a specific protocol.
7. Run `python onchain_analytics.py dex --chain ethereum` to analyze DEX trading volumes filtered by chain.
8. Run `python onchain_analytics.py yields --min-tvl 5000000 --chain ethereum` to identify yield opportunities above a minimum TVL threshold.
9. Run `python onchain_analytics.py trends --threshold 5` to detect protocols with significant TVL changes (threshold is percentage).
10. Export results in JSON or CSV format using `--format json` or `--format csv` and redirect to file for downstream analysis.

See [`references/implementation.md`](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/analyzing-on-chain-data/references/implementation.md) for the full four-step implementation workflow.

## Output

- Protocol rankings table with name, TVL, market share percentage, and TVL-to-market-cap ratio
- Chain TVL rankings showing aggregate locked value per network
- Fee and revenue reports per protocol with daily/weekly/monthly breakdowns
- DEX volume tables with per-chain and per-DEX breakdowns
- Yield opportunity listings filtered by minimum TVL and chain, including APY and pool details
- Trending protocol alerts showing TVL percentage changes above the configured threshold
- Stablecoin market cap summaries
- JSON (`output.json`) or CSV (`output.csv`) export files for programmatic consumption

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `Request timeout` | DeFiLlama API slow or unreachable | Wait and retry; check  for outages; use cached data if available |
| `Protocol not found: invalid-name` | Protocol slug does not match DeFiLlama database | Run `python onchain_analytics.py protocols` to find the exact slug; slugs are case-sensitive |
| `No data returned for query` | Filter too restrictive or data unavailable | Remove filters and retry; verify the category or chain exists; try a broader time range |
| `TVL data unavailable for some protocols` | New protocols or data collection gaps | Check DeFiLlama directly; data typically appears within 24 hours of listing |
| `Data may be stale (last updated: X hours ago)` | Local cache not refreshed | Clear cache with `rm ~/.onchain_analytics_cache.json`; use `--verbose` to check cache status |
| `Showing top 50 of 1000+ protocols` | Output truncated for readability | Use `--limit` to increase count or `--format json` for full untruncated data |
| `UnicodeEncodeError` | Terminal encoding mismatch | Use `--format json` for safe output or set `LANG=en_US.UTF-8` |

## Examples

### Daily DeFi Overview

```bash
python onchain_analytics.py protocols --limit 20
python onchain_analytics.py chains
python onchain_analytics.py trends
```

Produces a snapshot of the top 20 protocols by TVL, all chain rankings, and any protocols trending above the default threshold.

### Research a Lending Protocol

```bash
python onchain_analytics.py protocols --category lending --sort tvl_to_mcap
python onchain_analytics.py fees --protocol aave
```

Ranks all lending protocols by TVL-to-market-cap ratio (identifying potentially undervalued protocols), then pulls detailed fee and revenue data for Aave.

### Find High-TVL Yield Opportunities on Ethereum

```bash
python onchain_analytics.py yields --min-tvl 10000000 --chain ethereum --limit 50  # 10000000 = 10M limit
```

Returns up to 50 yield pools on Ethereum with at least $10M in TVL, sorted by APY. Export with `--format csv > yields.csv` for spreadsheet analysis.

## Resources

- [DeFiLlama API Documentation](https://defillama.com/docs/api) -- primary data source for TVL, fees, yields, and DEX volumes
- DeFiLlama Status Page -- check API availability and outage reports
- [CoinGecko API](https://www.coingecko.com/en/api/documentation) -- supplementary token price and market cap data
- [Dune Analytics](https://dune.com/) -- custom SQL queries against on-chain data for deeper analysis
- [The Graph](https://thegraph.com/) -- decentralized indexing protocol for querying blockchain data via GraphQL
