> ## Documentation Index > Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt > Use this file to discover all available pages before exploring further. # Market breadth > Percent of eligible Hyperliquid core perps or HIP-3 instruments above UTC-session VWAP, with eligibility counts, current snapshots, and minute history. Market breadth reports the percent of eligible instruments trading above their current session VWAP. It is a cross-sectional read on a whole venue family, not a per-symbol series: one snapshot describes the venue at one minute. The measure is equal-weighted by instrument. A heavily traded builder market and a thin one each count once. Every snapshot ships the counts it was computed from, so the denominator is auditable rather than implied. Breadth is published separately for Hyperliquid core perps and HIP-3 builder markets. There is no Spot breadth route, and HIP-4 is deliberately excluded because outcome markets are probability-priced binaries, where a percent-above-VWAP number would not carry the same meaning. ## How the number is computed The session is the UTC calendar day and resets at `00:00` UTC. Each instrument's VWAP is computed from candle quote volume divided by base volume for the session so far, not from a typical-price approximation. The comparison price is the close of the most recently completed one-minute candle. Snapshots are written every minute. `value_pct` is `100 * above / eligible`, so eligibility determines the denominator: | Instrument state | Effect | | ------------------------------------------------------------------ | ------------------------------------------- | | Traded this session, last completed candle within 5 minutes | Eligible; counted `above`, `at`, or `below` | | No volume this session | Excluded as `excluded_no_session_volume` | | Has session volume, but last completed candle older than 5 minutes | Excluded as `excluded_stale_price` | An instrument whose last close is exactly its VWAP is counted in `at`. It stays in the denominator and is not counted as above. Use the counts to check the denominator: ``` above + at + below = eligible eligible + excluded_no_session_volume + excluded_stale_price = candidates ``` ## Routes | Dataset | Route | Endpoint reference | | --------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Core perps: latest snapshot | `/v1/hyperliquid/breadth/above-vwap/current` | [Get current Hyperliquid breadth above session VWAP](/api-reference/hyperliquid--breadth/get-current-hyperliquid-breadth-above-session-vwap) | | Core perps: minute history | `/v1/hyperliquid/breadth/above-vwap` | [Get Hyperliquid breadth above session VWAP history](/api-reference/hyperliquid--breadth/get-hyperliquid-breadth-above-session-vwap-history) | | HIP-3: latest snapshot | `/v1/hyperliquid/hip3/breadth/above-vwap/current` | [Get current HIP-3 breadth above session VWAP](/api-reference/hip-3-builder-perps--breadth/get-current-hip-3-breadth-above-session-vwap) | | HIP-3: minute history | `/v1/hyperliquid/hip3/breadth/above-vwap` | [Get HIP-3 breadth above session VWAP history](/api-reference/hip-3-builder-perps--breadth/get-hip-3-breadth-above-session-vwap-history) | ## Get the latest snapshot The `/current` route takes no parameters and returns a single object with `meta.count` of `1`. ```bash theme={"theme":"github-dark"} curl "https://api.0xarchive.io/v1/hyperliquid/hip3/breadth/above-vwap/current" \ -H "X-API-Key: $OXARCHIVE_API_KEY" ``` Requests use the standard `X-API-Key` header described on [Authentication](/rest-api/authentication). Breadth is in the open catalog and available on all plans. Credits are row-based, so a full day of raw one-minute history is about 1,440 rows. ## Request parameters The `/current` route accepts no parameters. The history route accepts: | Parameter | Type | Required | Behavior | | ---------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | `start` | integer (ms) | No | Inclusive window start, Unix epoch milliseconds. Defaults to 24 hours before the current time, independently of `end` | | `end` | integer (ms) | No | Inclusive window end, Unix epoch milliseconds. Defaults to the current time | | `interval` | string | No | One of `5m`, `15m`, `30m`, `1h`, `4h`, `1d`. Omit for raw one-minute snapshots | | `limit` | integer | No | Snapshots per page. Default 100, clamped to 1000 | | `cursor` | string (epoch ms) | No | Exclusive continuation value from `meta.next_cursor`; pass it unchanged | History is returned in ascending time order. A `limit` above the maximum is clamped to 1000 silently rather than rejected, so read `meta.count` instead of assuming the request size was honored. An unsupported `interval` returns `400` and names the accepted values. The 24-hour default window is the parameter most likely to surprise. A request for `interval=1d&limit=30` without a `start` returns only the buckets inside the last day, not thirty days. Set `start` explicitly for any multi-day pull. For a historical window, supply both `start` and `end`: setting an older `end` alone does not move the default start and can return an empty series. ## Example response These bounded requests return one snapshot from each family at the same minute. Responses were retrieved from the live API; request IDs vary by request. ```bash theme={"theme":"github-dark"} curl "https://api.0xarchive.io/v1/hyperliquid/breadth/above-vwap?start=1788804060000&end=1788804060000&limit=1" \ -H "X-API-Key: $OXARCHIVE_API_KEY" ``` ```json theme={"theme":"github-dark"} { "success": true, "data": [ { "session_date": "2026-09-07", "calculated_at": "2026-09-07T18:01:00Z", "value_pct": 36.7816, "coverage_ratio": 0.33397312859884837, "counts": { "candidates": 521, "eligible": 174, "above": 64, "at": 0, "below": 110, "excluded_no_session_volume": 66, "excluded_stale_price": 281 }, "namespaces": { "eligible": {}, "above": {}, "at": {}, "below": {} } } ], "meta": { "count": 1, "next_cursor": "1788804060000", "request_id": "93641ce6-bcab-4e4e-a5e0-1a6bdb7c1a17" } } ``` ```bash theme={"theme":"github-dark"} curl "https://api.0xarchive.io/v1/hyperliquid/hip3/breadth/above-vwap?start=1788804060000&end=1788804060000&limit=1" \ -H "X-API-Key: $OXARCHIVE_API_KEY" ``` ```json theme={"theme":"github-dark"} { "success": true, "data": [ { "session_date": "2026-09-07", "calculated_at": "2026-09-07T18:01:00Z", "value_pct": 70.8333, "coverage_ratio": 0.3116883116883117, "counts": { "candidates": 231, "eligible": 72, "above": 51, "at": 0, "below": 21, "excluded_no_session_volume": 94, "excluded_stale_price": 65 }, "namespaces": { "eligible": { "io": 4, "mkts": 2, "para": 4, "xyz": 62 }, "above": { "io": 4, "mkts": 1, "para": 3, "xyz": 43 }, "at": {}, "below": { "mkts": 1, "para": 1, "xyz": 19 } } } ], "meta": { "count": 1, "next_cursor": "1788804060000", "request_id": "a2c36808-ae84-47c6-8cba-4c2c05a63ca7" } } ``` Core perps return empty `namespaces` maps because they have no builder namespace. In HIP-3, the maps include only namespaces with a nonzero count; an absent namespace key means zero. ## Response fields Responses use the `{ success, data, meta }` envelope. `/current` returns one object in `data`; history returns an array. | Field | Type | Meaning | | ----------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session_date` | string | UTC calendar day of the session the snapshot belongs to | | `calculated_at` | string | Snapshot cutoff time. Included candles closed at or before this time; a candle closing exactly at the cutoff is not guaranteed | | `value_pct` | number or null | `100 * above / eligible`, to four decimal places. `null` when `eligible` is `0` | | `coverage_ratio` | number | `eligible / candidates`, from 0 to 1 | | `counts.candidates` | integer | Candidate registry at calculation time, built from recorded open interest and instruments with session candles. Recomputed core history uses a point-in-time registry | | `counts.eligible` | integer | Instruments that passed both the session-volume and 5-minute freshness tests. The denominator of `value_pct` | | `counts.above` / `counts.below` | integer | Eligible instruments whose last close is above or below session VWAP | | `counts.at` | integer | Eligible instruments whose last close equals session VWAP exactly. In the denominator, not counted above | | `counts.excluded_no_session_volume` | integer | Candidates with no volume this session | | `counts.excluded_stale_price` | integer | Candidates with session volume whose last completed candle is older than 5 minutes. No-volume candidates are counted only in `excluded_no_session_volume` | | `namespaces` | object | Maps for `eligible`, `above`, `at`, and `below`. Empty for core perps; per-builder-namespace counts for HIP-3, omitting zero-count namespaces | | `meta.next_cursor` | string or null | Continuation cursor on history responses when another page may exist | | `meta.request_id` | string | Request identifier to retain for support and retry diagnostics | ## Read the number correctly Four behaviors will produce wrong charts if breadth is treated as an ordinary numeric series. **`value_pct` can be `null`, and null is not zero.** When nothing is eligible there is no denominator, and the API says so. Rendering that as `0%` asserts that eligible instruments existed and none was above VWAP, which is a different claim. Carry the null through to the chart as a gap. **Never average `value_pct` across snapshots.** Each snapshot has its own denominator, so the mean of percentages is not the percentage of the pooled set. To reduce resolution, use `interval`, which selects the last snapshot in each bucket server-side rather than averaging. **A missing minute means a skipped write, not a zero.** If a run fails or is skipped, there is no snapshot for that minute. `/current` returns the most recent stored snapshot with its original `calculated_at`. Compare `calculated_at` against your own clock before treating a `/current` read as fresh. **`coverage_ratio` moves with the clock, not only with the market.** Many HIP-3 products track underlying assets with fixed trading hours. Instruments leave the eligible set when their last completed candle is older than 5 minutes. Market hours can affect eligibility, but ingestion delays can also cause candles to become stale; the counts alone do not distinguish the cause. In the last snapshot of each UTC day from 2026-08-28 through 2026-09-07, `eligible` ranged from 62 to 115 against 225 to 231 `candidates`, and `coverage_ratio` ranged from 0.273 to 0.511. These are daily samples, not bounds on the minute series. At the `00:00` UTC session reset, no current-session candle has completed, so `eligible` is `0` and `value_pct` is `null`. Read `coverage_ratio` as a within-snapshot eligibility share rather than a quality score. The live writer uses a cumulative registry from recorded open interest plus session candles; recomputed core history uses a point-in-time registry. Changes to the registry can change the ratio without changing the eligible count. Compare `counts.eligible` and `counts.candidates` together, and do not assume either family has a fixed coverage ratio. ## Available history | Family | First snapshot | History provenance | | ---------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Core perps | `2026-08-24T00:00:00Z` | Values before `2026-08-31T13:43:00Z` were recomputed from canonical one-minute candles using a point-in-time instrument registry | | HIP-3 | `2026-08-28T20:49:00Z` | Stored live snapshots; HIP-3 has no pre-launch backfill | A `start` earlier than the first snapshot is accepted. A window ending before that snapshot returns an empty series; a window spanning it returns the available history. ## Stream it live There is no breadth WebSocket channel. Poll `/current` on a cadence matched to the one-minute write rather than treating it as a tick stream. See [WebSocket channels](/websocket/channels) for the families that do stream. ## Use it from an agent Connect through the [MCP server](/mcp-server), inspect the available tools, and specify core perps or HIP-3 explicitly when asking for breadth above session VWAP. Use the REST routes above when calling the API directly. ## Export in bulk There is no breadth export schema. Use the cursor-paginated history route for retained snapshots. ## Next Use [Candles](/rest-api/candles) for the per-symbol price series breadth is derived from, [Hyperliquid REST](/rest-api/hyperliquid) for core perps, [HIP-3 REST](/rest-api/hip3) for builder markets, or [Data quality](/data-quality) before a breadth series feeds alerts.