---
doc_id: "cmc.charts.market_overview.v3"
surface_type: "cmc_web_surface"
canonical_url: "https://coinmarketcap.com/charts/"
current_url: "https://coinmarketcap.com/charts/"
url_type: "canonical_page"
mirror_or_canonical: "canonical"
authoritative_for:
  - "MarketOverviewSnapshot schema"
  - "Per-widget typed states"
  - "Widget cell state enum"
  - "Snapshot metadata contract"
  - "Toggle identity rules"
  - "Hub diff semantics"
  - "Placeholder classification"
  - "Extraction policy"
  - "Page section order"
  - "FAQ titles"
  - "Navigation strips"
not_authoritative_for:
  - "\"Invalid Date\" / \"$0.00\" / \"$---.--\" as numeric values"
  - "KPIs without capture timestamp"
  - "Research article content (ephemeral)"
  - "Marketing / editorial copy"
  - "Legal terms"
source_precedence: "methodology_api > network_response > live_structured_dom > rendered_ui > marketing_copy"
freshness_class: "live"
requires_hydration: true
pricing_may_change: false
locale_sensitive: true
related_docs:
  - "fear-and-greed-index.md"
  - "bitcoin-dominance.md"
  - "coinmarketcap-api-documentation/pro-api-reference/global-metrics.md"
  - "charts-spot-market.md"
  - "charts-derivatives-market.md"
  - "altcoin-season-index.md"
  - "cmc_agent_standards-update.md"
last_reviewed: "2026-04-30"
---

# Crypto Market Overview (Charts hub) — Agent Spec


## TL;DR

The Crypto Market Overview is the main charts hub at coinmarketcap.com/charts/. It surfaces global market cap, volume, dominance widgets, and links to sub-chart surfaces (Fear & Greed, Altcoin Season, CMC100, etc.). Widgets are independently hydrated and can come from mixed source paths.

---

## Human Verification Summary *(non-normative)*

<!-- For human reviewers only. Agents must use formal contracts below. -->

- What this page is: The CMC charts hub — a dashboard of market-wide aggregate widgets and entry points to individual chart surfaces.
- Primary purpose: Global market snapshot and navigation hub to deeper chart pages.
- What is authoritative: Individual widget values post-hydration, with source resolution checked per widget. Some widgets map to global-metrics APIs; others are DOM-rendered summaries or link-outs to dedicated surfaces.
- What is NOT authoritative: Widget display labels may differ from API field names. Editorial copy in hero sections.
- Common misinterpretations: This page is a hub — it links to deeper surfaces (Fear & Greed, Altcoin Season) which have their own specs. Do not extract those surfaces from this page.
- Adjacency: Parent hub for all chart sub-pages. Each widget links to a dedicated spec (fear-and-greed-index.md, altcoin-season-index.md, cmc100-index_agent.md, etc.).

---


Canonical URL: `https://coinmarketcap.com/charts/`
Browser title: `Live Cryptocurrency Charts & Market Data | CoinMarketCap`


## Global State Rules
<!-- Controlled vocabulary for the state of any module or data element on this surface. -->

| Value | Agent Action |
|---|---|
| `present` | Extract widget values as active |
| `loading` | Block extraction per widget → each retries independently after 5s → timeout after 30s: emit `null` + `reason=timeout` per widget |
| `unsupported` | Widget not available in this locale/build — emit null |
| `unknown` | Refetch once after 2s → if still unknown: emit `null` + `reason=unknown`. Never guess. |

**Hard rule:** position is not rank — page position or row ordinal reflects display order only. Never treat ordinal position as quality, tier, or priority signal.

**Hard rule:** widgets hydrate independently — a page that appears loaded may still have individual widgets in loading state.

---
## Extraction Policy
<!-- Operational priority — what to extract, when, and what to skip. -->

### Always extract
- Global market cap widget
- 24h volume widget
- BTC/ETH dominance widgets
- `captured_at` timestamp

### Extract only if explicitly requested
- Individual sub-chart deep links (Fear & Greed, CMC100, Altcoin Season)
- DeFi/stablecoin volume share widgets

### Ignore by default
- Editorial prose in hero section
- Widget tooltips and footnotes
- Sub-chart previews (use dedicated specs for those surfaces)

---
## Non-Authoritative Content
<!-- What this surface's content may and must never be used for. -->

| Content | May be used for | Must never be used for |
|---------|----------------|----------------------|
| Widget values | Market snapshot context | Replacing dedicated surface specs |
| Sub-chart links | Navigation to dedicated surface | Data extraction (use the linked spec) |
| Editorial hero copy | Context | Market data |

---
## Field Contracts

| Field | Type | Null means | Notes |
|-------|------|-----------|-------|
| `fear_greed_value` | integer\|null | Widget not loaded | 0–100. Use dedicated spec for full contract. |
| `altcoin_season_score` | integer\|null | Widget not loaded | 0–100. Use dedicated spec for full contract. |
| `cmc20_value` | number\|null | Widget not loaded | Index value. Use dedicated spec. |
| `btc_dominance` | number\|null | Widget not loaded | Percentage |
| `open_interest` | number\|null | Widget not loaded | USD aggregate |
| `eth_gas` | number\|null | Widget not loaded | Gwei |

**Hard rule:** this hub shows summary widget values — for full field contracts use each surface's dedicated spec.

---


**Hard rule:** each widget on this hub hydrates independently — a page appearing loaded may still have individual widgets in loading state.

**Hard rule:** for full field contracts on any widget, use the dedicated surface spec — this hub spec covers only summary values.

## Automation Contract
<!-- Operational settings for automated extraction. -->

| Item | Value |
|------|-------|
| Fetch target | `https://coinmarketcap.com/charts/` |
| Hydration gate | Each widget hydrates independently |
| Cache TTL | Per widget (1–60 min) |
| Diff key | `widget_id + value + captured_at per widget` |

## Goal of This Spec

This spec exists to prevent:

- - Extracting sub-chart data from this hub instead of their dedicated specs
- - Treating editorial hero numbers as primary data
- - Assuming all widgets are hydrated simultaneously

---

## 1. Hard rules
<!-- Non-negotiable rules — widget values require post-hydration extraction. -->

- DO emit exactly ONE `MarketOverviewSnapshot` per capture.
- DO emit `widget_state` for every module present in DOM, even if fields are null.
- DO NOT treat `Invalid Date`, `$0.00`, `$---.--`, or `-` as numeric values.
- DO NOT diff snapshots without matching `active_toggles` for every relevant widget.
- DO NOT invent modules; if absent from DOM, omit or explicitly `null`.
- DO record `module_dom_order` *(always an array — empty `[]` if no modules detected, never `null`)* to detect layout rollouts.
- DO cite `GET /v1/global-metrics/quotes/latest` and `/historical` as on-page API references; verify against `global-metrics.md` before equating field names.

## 2. Source precedence
<!-- Data source hierarchy for this surface. -->

```
methodology_api  >  network_response  >  live_structured_dom  >  rendered_ui  >  marketing_copy
```

## 3. Widget cell state enum
<!-- States each widget can be in during load. -->

| State | Meaning |
|---|---|
| `loading` | Skeleton, "Loading …", or unbound placeholders (`$---.--`, `$0.00`, `Invalid Date`, `-`) before confirmed hydration. |
| `present` | Values bound and usable. |
| `empty` | Intentional empty / no data per UI. |
| `unknown` | Contradictory KPIs, error boundary, or ambiguous post-wait DOM. |

## 4. Snapshot metadata contract
<!-- Required envelope fields for every capture. -->

| Key | Type | Required | Notes |
|---|---|---|---|
| `canonical_url` | string | yes | Must equal canonical URL. |
| `captured_at` | RFC 3339 UTC | yes | |
| `locale` | BCP 47 | yes | |
| `display_currency` | string | yes | Session currency for money widgets. |
| `hydration_state` | enum | yes | `loading` \| `partial` \| `ready` (whole document). |
| `source_type` | enum | yes | `methodology_api` \| `network_response` \| `live_structured_dom` \| `rendered_ui` \| `mixed` |
| `active_toggles` | object | yes | MUST mirror visible UI. Keys: `market_cap.view_mode`, `market_cap.horizon`, `etf_net_flow.horizon`, plus any new module toggles. Explicit `null` for unset. |
| `module_dom_order` *(always an array — empty `[]` if no modules detected, never `null`)* | string[] | yes | Stable module ids in DOM order (e.g. `["top_coins","market_cap","etf_net_flow","dominance","open_interest","volmex","eth_gas"]`). |
| `hub_page_source_resolution_status` | enum | yes | `exact` \| `partial` \| `none`. Default `partial`. |

## 5. `MarketOverviewSnapshot` schema
<!-- Full JSON schema for a market overview capture. -->

One object per capture. Every field optional in JSON, but MUST be populated with at least `{ widget_state }` when the module exists in DOM.

| Field | Type | Notes |
|---|---|---|
| `top_coins` | `TopCoinsRow[]` | §5.1 |
| `altcoin_season` | `AltcoinSeasonWidgetState` | §5.2 |
| `cmc20` | `Cmc20IndexWidgetState` | §5.3 |
| `market_cap` | `MarketCapWidgetState` | §5.4 |
| `etf_net_flow` | `EtfNetFlowWidgetState` | §5.5 |
| `dominance` | `DominanceWidgetState` | §5.6 |
| `open_interest` | `OpenInterestHubWidgetState` | §5.7 |
| `volmex` | `VolmexWidgetState` | §5.8 |
| `eth_gas` | `EthGasWidgetState` | §5.9 |
| `faq_titles` | string[] | Verbatim; §11. |
| `research_articles` | `{ title, href, age_label }[]` | Ephemeral. |

### 5.1 `TopCoinsRow`

| Field | Type | Notes |
|---|---|---|
| `asset_label` | string | Bitcoin, Ethereum, BNB, Solana, XRP, ... |
| `price_display` | string \| null | |
| `pct_change_display` | string \| null | 24h-style line when shown. |
| `widget_state` | enum (§3) | |

### 5.2 `AltcoinSeasonWidgetState`

| Field | Type | Notes |
|---|---|---|
| `index_readout` | string \| null | e.g. `"38/100"`. |
| `season_label` | string \| null | `"Bitcoin Season"` \| `"Altcoin Season"`. |
| `widget_state` | enum (§3) | |

### 5.3 `Cmc20IndexWidgetState`

| Field | Type | Notes |
|---|---|---|
| `index_price_display` | string \| null | `$---.--` ⇒ `loading`. |
| `widget_state` | enum (§3) | |

### 5.4 `MarketCapWidgetState`

| Field | Type | Allowed values |
|---|---|---|
| `view_mode` | `"overview"` \| `"breakdown"` \| null | Toggle as displayed. |
| `horizon` | `"30d"` \| `"1y"` \| `"all"` \| null | |
| `market_cap_display` | string \| null | `$0.00` ⇒ `loading`. |
| `volume_display` | string \| null | |
| `chart_slot_state` | enum (§3) | Primary chart region. |
| `widget_state` | enum (§3) | Aggregate. |

### 5.5 `EtfNetFlowWidgetState`

| Field | Type | Notes |
|---|---|---|
| `horizon` | `"30d"` \| `"1y"` \| `"all"` \| null | |
| `tile_states` | object | Keyed per tile; `Invalid Date` / `-` ⇒ `loading` or `unknown` per §3. |
| `widget_state` | enum (§3) | |

### 5.6 `DominanceWidgetState`

| Field | Type |
|---|---|
| `btc_pct` | string \| null |
| `eth_pct` | string \| null |
| `others_pct` | string \| null |
| `widget_state` | enum (§3) |

### 5.7 `OpenInterestHubWidgetState`

| Field | Type |
|---|---|
| `perpetuals_usd_display` | string \| null |
| `futures_usd_display` | string \| null |
| `widget_state` | enum (§3) |

### 5.8 `VolmexWidgetState`

| Field | Type |
|---|---|
| `btc_iv_display` | string \| null |
| `eth_iv_display` | string \| null |
| `widget_state` | enum (§3) |

### 5.9 `EthGasWidgetState`

| Field | Type |
|---|---|
| `slow_gwei` | string \| null |
| `standard_gwei` | string \| null |
| `fast_gwei` | string \| null |
| `eta_labels` | string[] |
| `widget_state` | enum (§3) |

## 6. Placeholder classification

| DOM pattern | Classification | Action |
|---|---|---|
| `$---.--` | `loading` | Record raw; emit numeric `null`. |
| `$0.00` on cap/volume pre-hydration | `loading` | Never commit as zero. |
| `Invalid Date` on ETF tile | `loading` \| `unknown` | Flag if persists post-hydration. |
| `-` on ETF tile | `loading` \| `empty` | Disambiguate only after hydration. |
| "Loading … This might take a few seconds." in chart slot | `loading` for `chart_slot_state` | Do not parse canvas. |

## 7. Toggle identity rules

- Hub diffs compare only snapshots with matching `active_toggles` per relevant widget.
- Cross-toggle comparison is invalid unless the differ documents normalization.
- `module_dom_order` *(always an array — empty `[]` if no modules detected, never `null`)* changes are a layout event, not a data event.

## 8. Hub diff semantics

| Event | Condition |
|---|---|
| `module_order_changed` | `module_dom_order` *(always an array — empty `[]` if no modules detected, never `null`)* differs. |
| `module_added` / `module_removed` | Widget absent vs present between A and B. |
| `widget_state_changed` | Same key; `widget_state` / `chart_slot_state` / `tile_states` changed. |
| `widget_value_changed` | Same key, `widget_state: present` in both; display string differs under normalization. |
| `toggle_changed` | `active_toggles` differ — isolate toggle diffs from data diffs. |

## 9. Extraction policy

| Policy | Surfaces |
|---|---|
| `always_extract` | `MarketOverviewSnapshot` skeleton; every module's `widget_state`; `active_toggles`; `module_dom_order` *(always an array — empty `[]` if no modules detected, never `null`)*; Markets strip URLs. |
| `extract_if_requested` | FAQ answers; Research article bodies; chart series scrape. |
| `ignore_by_default` | Duplicate "See API Details" beyond first; positioning heading; newsletter/CTA banners. |

## 10. Ignore list

- Positioning heading "CoinMarketCap is the trusted, industry leading source for crypto price charts".
- Newsletter / app-download / promo banners.
- Research article body text (retain only `{ title, href, age_label }`).

## 11. FAQ titles (verbatim, non-authoritative)

- Can I access live market data through an API?
- Can I access historical market data through an API?
- How can different crypto indexes help an investor to understand the crypto market?
- What should you look for when comparing crypto data providers and methodologies?
- Why does data accuracy matter when compiling crypto price data charts?

## 12. Page section order (DOM)

1. Hero — `# Crypto Market Overview` + See API Details + intro.
2. Top Coins rows.
3. Crypto Dashboard container (Altcoin Season Index readout).
4. `## CoinMarketCap 20 Index`.
5. `## Crypto Market Cap` (toggles + horizons).
6. `## Crypto ETFs Net Flow` (horizons + tiles).
7. `## Bitcoin Dominance` (BTC / ETH / Others).
8. `## Open Interest` (Perps / Futures USD).
9. `## Volmex Implied Volatility` (BTC / ETH).
10. `## ETH Gas` (Slow / Standard / Fast Gwei + ETA labels).
11. `### Frequently Asked Questions (FAQ)` — §11.
12. `### CoinMarketCap Research Articles` — ephemeral.

## 13. On-page API references (global metrics)

- `GET https://pro-api.coinmarketcap.com/v1/global-metrics/quotes/latest`
- `GET https://pro-api.coinmarketcap.com/v1/global-metrics/quotes/historical`

Verify field semantics against `coinmarketcap-api-documentation/pro-api-reference/global-metrics.md`. Do not alias API field names to UI labels without explicit documentation.

## 14. Navigation strips

Markets charts dashboard:

| Label | URL |
|---|---|
| Overview | https://coinmarketcap.com/charts/ |
| Spot | https://coinmarketcap.com/charts/spot-market/ |
| Derivatives | https://coinmarketcap.com/charts/derivatives-market/ |
| Cryptocurrencies | https://coinmarketcap.com/charts/number-of-cryptocurrencies-tracked/ |
| BTC Treasuries | https://coinmarketcap.com/charts/bitcoin-treasuries/ |
| BNB Treasuries | https://coinmarketcap.com/charts/bnb-treasuries/ |
| Exchange Inflows/Outflows | https://coinmarketcap.com/charts/exchange-inflows-outflows/ |

Indicators IA (separate): see `fear-and-greed-index.md`, `altcoin-season-index.md`.

## 15. Widget presence / absence rules

Every widget key in the `MarketOverviewSnapshot` has exactly three legal states. Use this table to pick the serialization form.

| Reality | Serialization | `widget_state` | Notes |
|---|---|---|---|
| Widget absent from DOM | Key = `null` in snapshot | n/a (omitted with field itself) | Add `integrity_flags += "<widget>_absent"` at envelope level. |
| Widget present, still loading | Key = object with nulled display fields | `loading` | Keep raw placeholder text (`$---.--`, `Invalid Date`) in separate `raw_display` when non-empty. |
| Widget present, empty by design | Key = object with nulled displays | `empty` | Rare; document the copy observed. |
| Widget present, bound | Key = object with populated displays | `present` | Canonical case. |
| Widget present, ambiguous post-wait | Key = object with nulled displays | `unknown` | Add per-widget `integrity_flags`. |

## 16. Per-widget source resolution

Each widget carries its own `widget_source_resolution_status` alongside the page-level one. Default `partial` or `none`; override per integration.

| Widget | Default status | Typical fallbacks |
|---|---|---|
| `top_coins` | `partial` | `live_structured_dom` → `rendered_ui` |
| `altcoin_season` | `partial` | `rendered_ui` |
| `cmc20` | `partial` | `rendered_ui` |
| `market_cap` | `partial` | `live_structured_dom` → `rendered_ui` |
| `etf_net_flow` | `partial` | `rendered_ui` |
| `dominance` | `partial` | `methodology_api` (global-metrics) → `rendered_ui` |
| `open_interest` | `partial` | `rendered_ui` |
| `volmex` | `none` \| `partial` | `rendered_ui` |
| `eth_gas` | `partial` | `rendered_ui` |
| `research_articles` | `none` | — |

## 17. Output contract (serialization)

### 17.1 Serialization rules

| Condition | Emit |
|---|---|
| Widget absent from DOM | Widget key = `null`; envelope `integrity_flags += "<widget>_absent"`. |
| Widget present | Widget object with `widget_state` + display fields. NEVER omit. |
| Display string unbound (`$---.--`, `$0.00`, `Invalid Date`, `-`) | `display: null`, `cell_state: loading`, raw preserved in `raw_display`. |
| `module_dom_order` *(always an array — empty `[]` if no modules detected, never `null`)* missing modules | List only what was observed; do not pad. |
| `active_toggles` unset for a widget | Explicit `null` (not missing key). |
| Numeric parse attempted | Store in `parsed_value` sibling; `display` always preserved. |
| Article rail empty | `research_articles: []`. |
| FAQ absent | `faq_titles: []`. |

### 17.2 Output guarantees

- Exactly ONE `MarketOverviewSnapshot` per capture.
- MUST carry sibling snapshot-metadata envelope (§4).
- Every widget key is ALWAYS present in the snapshot object (value may be `null`).
- `module_dom_order` *(always an array — empty `[]` if no modules detected, never `null`)* reflects ONLY observed modules.
- Widget substructures (`TopCoinsRow`, `MarketCapWidgetState`, etc.) NEVER emitted outside their parent widget key.
- Toggle changes are isolated from value changes in diffs (§8).

### 17.3 Canonical JSON example (abbreviated)

```json
// ⚠ EXAMPLE DATA — values below are illustrative only.
// Do NOT use these numbers as current data. They will be stale.
// Always fetch live values from the API or live page at capture time.
{
  "snapshot_metadata": {
    "canonical_url": "https://coinmarketcap.com/charts/",
    "captured_at": "<YYYY-MM-DDTHH:MM:SSZ>",
    "locale": "en-US",
    "display_currency": "USD",
    "hydration_state": "ready",
    "source_type": "rendered_ui",
    "active_toggles": {
      "market_cap.view_mode": "overview",
      "market_cap.horizon": "30d",
      "etf_net_flow.horizon": "1y"
    },
    "module_dom_order": [
      "top_coins","altcoin_season","cmc20","market_cap",
      "etf_net_flow","dominance","open_interest","volmex","eth_gas"
    ],
    "hub_page_source_resolution_status": "partial"
  },
  "market_overview_snapshot": {
    "top_coins": [
      { "asset_label": "Bitcoin",  "price_display": "<string: live price display>", "pct_change_display": "<string: live % display>", "widget_state": "present" },
      { "asset_label": "Ethereum", "price_display": "<string: live price display>",  "pct_change_display": "<string: live % display>", "widget_state": "present" }
    ],
    "altcoin_season": { "index_readout": "38/100", "season_label": "Bitcoin Season", "widget_state": "present" },
    "cmc20":          { "index_price_display": "<string: live index display>", "widget_state": "present" },
    "market_cap": {
      "view_mode": "overview",
      "horizon": "30d",
      "market_cap_display": "<string: live USD display>",
      "volume_display": "<string: live USD display>",
      "chart_slot_state": "present",
      "widget_state": "present"
    },
    "etf_net_flow": {
      "horizon": "1y",
      "tile_states": { "bitcoin_etf": "present", "ethereum_etf": "loading" },
      "widget_state": "partial"
    },
    "dominance": {
      "btc_pct": "59.6%", "eth_pct": "10.9%", "others_pct": "29.5%", "widget_state": "present"
    },
    "open_interest": {
      "perpetuals_usd_display": "<string: live USD display>", "futures_usd_display": "<string: live USD display>", "widget_state": "present"
    },
    "volmex": {
      "btc_iv_display": "42.1", "eth_iv_display": "58.3", "widget_state": "present"
    },
    "eth_gas": {
      "slow_gwei": "11", "standard_gwei": "14", "fast_gwei": "18",
      "eta_labels": ["~45 sec", "~18 sec", "~6 sec"],
      "widget_state": "present"
    },
    "faq_titles": [
      "Can I access live market data through an API?",
      "Can I access historical market data through an API?"
    ],
    "research_articles": []
  }
}
```

## 18. Automation contract

| Item | Value |
|---|---|
| Fetch target | `https://coinmarketcap.com/charts/` |
| Hydration gate | Most numeric modules require hydration; record `widget_state` per §3. |
| Cache TTL | Short (≤2 min class) when scraping UI. |
| Diff contract | §8, only with aligned `active_toggles` and `module_dom_order` *(always an array — empty `[]` if no modules detected, never `null`)*. |
| Provenance | Persist `source_type`, `hub_page_source_resolution_status`, `captured_at`. |
| Fallback specs | `charts-spot-market.md`, `charts-derivatives-market.md`, `bitcoin-dominance.md`, `altcoin-season-index.md`. |