---
name: chain-defi-ecosystem-analysis
description: "Size a chain's DeFi ecosystem, TVL, gaps, and build PMF."
version: 1.0.0
author: agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [defi, tvl, defillama, ecosystem, pmf, chain-research, morpho, perps]
    related_skills: [evm-contract-research, oracle-desk, verification-gate, retrieval-first-answering]
---

> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.


# Chain DeFi Ecosystem Analysis

Use when the question is about a **chain**, not a token or a contract:

- "what DeFi protocols are on chain X" / "top TVL on X"
- "which are native to X vs just deployed there"
- "what's missing / where's the gap in X's ecosystem"
- "is there product-market fit for building X on this chain"
- "is this chain's TVL real or rented"

Sibling lanes: contract/router/calldata work → `evm-contract-research`.
Swap and bridge cost comparison → `oracle-desk`.

## Non-negotiables

1. **Every number comes from a live API pull this turn.** No memory, no search
   snippets. Chain facts go stale in days on a young chain.
2. **Reconcile sum-of-parts against the headline before publishing any table.**
   If they disagree, you have a double-count and must explain it.
3. **Falsify before you recommend.** A build recommendation you did not try to
   kill is a guess with a table attached. See "The falsification pass".
4. State confidence per claim: high / moderate / low / unknown. Separate
   "the numbers" (usually high) from "the judgment" (usually moderate).

## Workflow

### 1. Chain totals first
Establish the frame before naming a single protocol:

| Metric | Endpoint |
|---|---|
| Chain TVL | `api.llama.fi/v2/chains` (match on `name`/`chainId`) |
| TVL history | `api.llama.fi/v2/historicalChainTvl/<Chain%20Name>` |
| DEX volume | `api.llama.fi/overview/dexs/<Chain%20Name>` |
| Chain fees | `api.llama.fi/overview/fees/<Chain%20Name>` |
| Stablecoins | `stablecoins.llama.fi/stablecoinchains` |

**Fees are the strongest realness signal.** TVL can be farmed and volume can be
wash-traded; fees paid are revealed willingness to pay. Also read fees for *who*
earns them — a launchpad ranking #3 chain-wide tells you extraction, not utility,
is the economy.

**Always pull both TVL trend and volume trend.** TVL rising while volume falls is
capital rotating in for yield, not users arriving. Reporting only the rising one is
how a dying chain gets written up as growing.

### 2. Protocol census + double-count reconciliation
Pull `api.llama.fi/protocols` once (~8MB), filter in Python, never print raw.
Select protocols whose `chainTvls` has a plain key for the chain (exclude
`-borrowed`, `-staking`, `-pool2` suffixed keys).

Then **reconcile**: sum of per-protocol TVL vs the chain headline. A large gap is
normal and must be explained, not smoothed over. Curators, vault wrappers, yield
frontends and capital allocators sit *on top of* a base venue and re-count the same
deposits. DefiLlama does **not** reliably set the `doublecounted` flag, so infer the
overlap from the gap and name the specific offenders.

Recipe and reconciliation worked example: `references/defillama-chain-census.md`.
Re-runnable: `scripts/chain-census.py "<Chain Name>"`.

### 3. Native vs multichain split
`len(protocol["chains"]) == 1` ⇒ built only for this chain. This one line separates
"the chain has an ecosystem" from "the chain has deployments." Report both sums.
A chain can hold hundreds of millions while its entire native builder scene is
low-single-digit millions.

### 4. Category gap diff
Aggregate category → (TVL, count) for the target chain and for two mature
comparators (Base, Arbitrum). Diff the category sets into three tables:
**absent entirely**, **present but dead (<$100k)**, **healthy**.

### 5. Concentration analysis on whichever number carries the thesis
Never let a headline TVL number stand unexamined. For the dominant venue pull
depositor/position distribution: holder counts, median position, top-1/5/10 share,
and whether large holders are EOAs or contracts.

Supply and borrow sides routinely have **opposite** distributions — a broad retail
supply base with a handful of whales levered on top. Those imply different things
about stickiness, so measure them separately.

### 6. The falsification pass
Before recommending anything be built, spend the tool calls to kill it:

- Pull the **venue's own docs** for the mechanism you plan to exploit.
- Pull **historical data** and test the effect empirically, split by the condition
  you claim creates it.
- If a market for your idea already exists, check whether it exists **and is empty**.

Only then write the recommendation.

## Pitfalls

- **Sum of protocols ≠ chain TVL.** Curator / risk-manager / yield-wrapper /
  capital-allocator rows re-count base-venue deposits. Never add a curator's TVL to
  the venue it curates. Reconcile the delta out loud.
- **"Absent category" and "built and rejected" are opposite conclusions.** An empty
  category may be whitespace. A *deployed market sitting at near-zero* is a demand
  refusal — capital looked and declined. Check which one you have before calling it
  an opportunity; the second one means you must first solve why it was refused.
- **Category false positives in any DefiLlama diff.** `CEX` is exchange
  proof-of-reserve wallets, not deployable protocols — it is the single biggest
  fake opportunity in a category diff. `Chain` and `Bug Bounty` are bookkeeping
  rows. Strike them explicitly.
- **Always compute top-2 concentration per category before calling it a market.**
  A category can show large TVL and be one protocol's book; the real addressable
  market is then ~1% of the headline.
- **Protocol count is a mirage.** Count the long tail's combined TVL. Thirty DEXes
  where three hold 92% is one DEX plus twenty-seven forks.
- **Never call TVL "mercenary" without measuring it.** Distribution decides:
  tens of thousands of holders with a four-figure median is retail and sticky;
  ten addresses holding most of it is not. Check whether top holders are smart
  accounts belonging to an app's wallet infrastructure — that is a distribution
  asset, and often the most valuable thing on a young chain.
- **Markets can exist and never launch.** Filter for zero price / zero volume before
  quoting a venue's market count. "43 markets" including seven that never opened and
  sixteen doing under $25k/day is a different venue than the headline.
- **DefiLlama per-chain `overview/derivatives/<chain>` is paywalled** ("Upgrade to
  the paid API plan") while `overview/dexs/` and `overview/fees/` are free. Use the
  full URL-encoded chain name (`Robinhood%20Chain`), not a lowercase slug — a slug
  returns the paywall string for every category and looks like a plan limit.
- **Do not loop a public data API inside one Python process** when sweeping many
  symbols; you get uniform errors for every symbol and it reads like the API is
  down. Fetch with `curl` into files with a small sleep, then parse the files in a
  separate pass. This turned 20 failures into 20 successes.

## Venue docs discovery

Modern docs sites (Mintlify and similar) publish a machine index and a markdown
twin of every page. This is the fastest path to a venue's real API and mechanism
docs:

```
curl -sL https://docs.<venue>/llms.txt        # full page index w/ descriptions
grep -iE "funding|oracle|margin|liquidat" llms.txt
curl -sL https://docs.<venue>/<path>.md       # markdown twin of a page
```

The bare HTML page URL may 404 while the `.md` twin returns 200. The `llms.txt`
index also reveals REST/WS hostnames and endpoint paths without reverse-engineering
JS bundles.

## Reporting shape (DEMI)

- Lead with the verdict or the number. Tables over paragraphs.
- Give the de-duplicated view, not just the raw one — show what the chain
  *actually* is once wrappers are collapsed.
- Name what is dead: zero-TVL protocols, never-launched markets, empty categories.
- Say plainly when your own earlier claim was overturned by new data, and why.
- End with the risk that would flip the answer.

## References

- `references/defillama-chain-census.md` — endpoint map, Python filtering patterns,
  double-count reconciliation worked example, category-diff false positives.
- `references/morpho-blue-graphql.md` — Morpho Blue API schema quirks that cost
  ~8 failed round trips: `vaults` vs `vaultV2s`, field-name traps, pagination.
- `references/perp-venue-funding-regimes.md` — how to read a perp venue's funding
  mechanism before trading it, incl. RWA off-hours rate locks and price bands, and
  the worked falsification of a weekend-basis thesis.

## Scripts

- `scripts/chain-census.py` — re-runnable census: chain totals, protocol list,
  native/multichain split, category rollup, and sum-vs-headline reconciliation.
  `python3 scripts/chain-census.py "Robinhood Chain"`