> ## 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.

# Breadth above the moving average

> Share of Hyperliquid core or HIP-3 perps above their 5, 20, 50 or 200-day moving average, with how far above or below, as minute history or the newest reading. Build plan and above.

Measure how much of a venue is in an uptrend: the share of Hyperliquid core perps, or of HIP-3 perps, trading above their n-day moving average, and the quartiles of how far above or below they are. Choose the length, 5, 20, 50 or 200 days, read the newest reading or a history at intervals from one minute to one day, and compare the venue with itself over time. Breadth above the moving average comes with the Build, Pro, Scale and Enterprise plans.

It is a separate measure from [breadth above session VWAP](https://docs.0xarchive.io/rest-api/breadth.md), which compares each instrument with its VWAP for the current UTC day and is on every plan.

## How a reading is computed

The method is `ma-breadth/1`, named in every record.

| Step | Rule |
| - | - |
| Candidates | Every perp the venue has listed, from its first one-minute candle on. Delisted perps stay candidates |
| Price | The perp's last one-minute close before the reading |
| Average | The mean of the perp's daily closes over the n UTC days before the reading's day. A day's close is its last one-minute close, carried through a day without one |
| Stale price | No one-minute close in the 24 hours before the reading: counted in `excluded_stale_price`. A delisted perp is counted here from 24 hours after its last trade |
| Short history | Younger than n UTC days before the reading's day: counted in `excluded_short_history` |
| Value | `value_pct` is `100 * above / eligible`, to 4 decimals |
| Distance | The 25th, 50th and 75th percentiles of `price / average - 1` over the eligible perps, to 6 decimals, with linear interpolation |

The counts check each other:

```
above + at + below = eligible
eligible + excluded_stale_price + excluded_short_history = candidates
```

## Routes

| Dataset | Route and endpoint reference |
| - | - |
| Core perps: newest reading | `/v1/hyperliquid/breadth/above-ma/current`: [Get current Hyperliquid breadth above the moving average](https://docs.0xarchive.io/api-reference/hyperliquid--breadth/get-current-hyperliquid-breadth-above-the-moving-average.md) |
| Core perps: history | `/v1/hyperliquid/breadth/above-ma`: [Get Hyperliquid breadth above the moving average history](https://docs.0xarchive.io/api-reference/hyperliquid--breadth/get-hyperliquid-breadth-above-the-moving-average-history.md) |
| HIP-3: newest reading | `/v1/hyperliquid/hip3/breadth/above-ma/current`: [Get current HIP-3 breadth above the moving average](https://docs.0xarchive.io/api-reference/hip-3-builder-perps--breadth/get-current-hip-3-breadth-above-the-moving-average.md) |
| HIP-3: history | `/v1/hyperliquid/hip3/breadth/above-ma`: [Get HIP-3 breadth above the moving average history](https://docs.0xarchive.io/api-reference/hip-3-builder-perps--breadth/get-hip-3-breadth-above-the-moving-average-history.md) |

There is no Spot or HIP-4 series: those paths answer `404` with `error_code` `unsupported_for_venue`.

## Plans and credits

Breadth above the moving average comes with the Build, Pro, Scale and Enterprise plans. A Free key receives `403` with `error_code` `forbidden`, the `datatype` (`breadth_ma`), the `required_plans` and an `upgrade_url`. A refused request is not charged. Each request costs 1 credit, whatever its number of buckets.

## Request parameters

`n` is required on every route: `5`, `20`, `50` or `200`. There is no default, because the lengths answer different questions, a 5-day and a 200-day reading of the same venue often point opposite ways, and each length starts on its own date. A missing or other value returns `400` with `error_code` `invalid_parameter` and the accepted `valid_values`.

`/current` takes `n` only and returns the newest one-minute reading. Any window parameter returns `400`, naming the history route. The history route also accepts:

| Parameter | Behavior |
| - | - |
| `start` | Optional, Unix milliseconds or RFC 3339. Defaults to 24 hours before `end` |
| `end` | Optional, Unix milliseconds or RFC 3339. Defaults to now |
| `interval` | Optional. One of `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`. Defaults to `1m`. Buckets open on UTC epoch boundaries, so `1d` is the UTC day |
| `limit` | Optional. Buckets per page, default 100, maximum 1,000. A larger value is read as 1,000 |
| `cursor` | Optional. `meta.next_cursor` from the previous page, passed back with the other parameters unchanged |

A page holds the buckets whose open is in `[start, end]`, oldest first. Set both `start` and `end` when paging, because the default window moves with the clock, and keep paging while `meta.has_more` is `true`. The cursor is opaque: it is not a `calculated_at` value, so do not reuse the paging logic of breadth above session VWAP.

## Example response

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/breadth/above-ma?n=50&interval=1d&start=2026-10-20T00:00:00Z&end=2026-10-21T00:00:00Z" \
  -H "X-API-Key: $OXARCHIVE_API_KEY" \
  -H "0xArchive-Version: 2026-10-01"
```

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "timestamp": "2026-10-20T00:00:00.000Z",
      "timestamp_ms": 1792454400000,
      "calculated_at": "2026-10-21T00:00:00.000Z",
      "calculated_at_ms": 1792540800000,
      "n": 50,
      "method": "ma-breadth/1",
      "value_pct": 34.4633,
      "coverage_ratio": 0.8009,
      "counts": {
        "candidates": 221,
        "eligible": 177,
        "above": 61,
        "at": 0,
        "below": 116,
        "excluded_stale_price": 43,
        "excluded_short_history": 1
      },
      "distance": {
        "p25": -0.09803,
        "median": -0.027606,
        "p75": 0.036555
      },
      "is_final": true
    }
  ],
  "meta": {
    "count": 2,
    "has_more": false,
    "request_id": "e1d7bd80-c7f3-41bd-8d5e-435a257b5797"
  }
}
```

The response above is trimmed to its first bucket. `/current` returns one record as an object in `data`, with `meta.count` of `1`.

## Response fields

| Field | Meaning |
| - | - |
| `timestamp`, `timestamp_ms` | Bucket open, RFC 3339 UTC and Unix milliseconds |
| `calculated_at`, `calculated_at_ms` | The reading's instant: the bucket's end, or, for the bucket still forming, the newest settled minute |
| `n` | The moving average's length in days |
| `method` | The method version, `ma-breadth/1` |
| `value_pct` | Number or null. `100 * above / eligible`. Null when nothing is eligible |
| `coverage_ratio` | `eligible / candidates`, from 0 to 1, to 4 decimals |
| `counts` | `candidates`, `eligible`, `above`, `at`, `below`, `excluded_stale_price`, `excluded_short_history` |
| `distance` | `p25`, `median` and `p75` of `price / average - 1`. Each null when nothing is eligible |
| `is_final` | Every candle the reading uses is final |

## Read the number correctly

**A bucket carries its last reading.** Each bucket holds the reading as of its end, and the bucket still forming holds the reading as of the newest settled minute, about 4 minutes behind now. `/current` is that newest minute. Percentages are never averaged across buckets; to reduce resolution, pick a longer `interval`.

**Null is not zero.** `value_pct` and the quartiles are null when nothing is eligible. Carry the null through as a gap.

**`coverage_ratio` is not a quality score.** It depends on n, because younger perps are excluded at longer lengths, and it falls as perps delist, because delisted perps stay candidates. It is not comparable with the `coverage_ratio` of breadth above session VWAP.

**A final reading can still be rebuilt.** `is_final` means the candles behind the reading are final. If those candles are rebuilt, or a listing reaches the candidate list late, the reading can change.

**A 503 is retryable.** While a series is still being prepared, or when many history pages below `1h` are requested at once, the route answers `503` with `error_code` `upstream_unavailable` and `Retry-After`. Retry after the delay.

## Available history

Each length starts on its own date, n days after the venue's first candle day. A window that ends before its length's start returns an empty page with `meta.coverage_from` and `meta.notice`; a window that straddles it is served from it.

| Length | Start |
| - | - |
| `n=5` | Hyperliquid core 2025-03-27; HIP-3 2025-12-27 |
| `n=20` | Hyperliquid core 2025-04-11; HIP-3 2026-01-11 |
| `n=50` | Hyperliquid core 2025-05-11; HIP-3 2026-02-10 |
| `n=200` | Hyperliquid core 2025-10-08; HIP-3 2026-07-10 |

Each start is 00:00 UTC. In `GET /v1/capabilities`, the row's `available_from` is the `n=5` start, and its notes give the others.

## Access

Each venue's start date, plans and page limit come from [`GET /v1/capabilities`](https://docs.0xarchive.io/capabilities), followed by the SDK, CLI and MCP names for the same data. Send `0xArchive-Version: 2026-10-01` for the current response contract; see [API conventions](https://docs.0xarchive.io/conventions.md).

| Venue | Availability |
| - | - |
| Hyperliquid | From 2025-03-27 REST only, no WebSocket channel Plans: Build, Pro, Scale and Enterprise only Up to 1,000 rows a page Share of perps above their n-day moving average (n required: 5, 20, 50 or 200), with the quartiles of how far above or below. Method ma-breadth/1: a delisted perp stays a candidate, counted in excluded\_stale\_price from 24 hours after its last trade, and a perp younger than n days in excluded\_short\_history, so coverage\_ratio is not a data-quality ratio and is not comparable with above-VWAP's; the average is of the daily closes over the n UTC days before the reading's day. available\_from is n = 5; n = 20 from 2025-04-11, 50 from 2025-05-11, 200 from 2025-10-08. A bucket carries its last reading; percentages are never averaged. |
| HIP-3 | From 2025-12-27 REST only, no WebSocket channel Plans: Build, Pro, Scale and Enterprise only Up to 1,000 rows a page Share of HIP-3 perps above their n-day moving average (n required: 5, 20, 50 or 200), with the quartiles of how far above or below. Method ma-breadth/1: a delisted perp stays a candidate, counted in excluded\_stale\_price from 24 hours after its last trade, and a perp younger than n days in excluded\_short\_history, so coverage\_ratio is not a data-quality ratio and is not comparable with above-VWAP's; the average is of the daily closes over the n UTC days before the reading's day. available\_from is n = 5; n = 20 from 2026-01-11, 50 from 2026-02-10, 200 from 2026-07-10. A bucket carries its last reading; percentages are never averaged. |

| Surface | Names |
| - | - |
| Python SDK | `client.hyperliquid.breadth_ma.history(n=..., ...)`, `.breadth_ma.current(n=...)`; HIP-3 `client.hyperliquid.hip3.breadth_ma` |
| TypeScript SDK | `client.hyperliquid.breadthMa.history({ n, ... })`, `.breadthMa.current({ n })`; HIP-3 `client.hyperliquid.hip3.breadthMa` |
| Rust SDK | `client.hyperliquid.breadth_ma.history`, `.breadth_ma.current`; HIP-3 `client.hyperliquid.hip3.breadth_ma` |
| CLI | `oxa breadth above-ma history --exchange hyperliquid\|hip3 --n <n>`, `oxa breadth above-ma current --exchange hyperliquid\|hip3 --n <n>` |
| MCP tools | `get_breadth_above_ma`, `get_breadth_above_ma_current`, `get_hip3_breadth_above_ma`, `get_hip3_breadth_above_ma_current` |

## Stream it live

There is no WebSocket channel for this series. Poll `/current` once a minute at most; a new reading appears each minute.

## Use it from an agent

**Ask for breadth at the length you need**

Through the [MCP server](https://docs.0xarchive.io/mcp-server.md), name core perps or HIP-3 and the length, 5, 20, 50 or 200 days, when asking for breadth above the moving average.

[Connect your agent](https://docs.0xarchive.io/mcp-server.md)

## Next step

**Compare with breadth above session VWAP**

Read the intraday measure next to the trend measure to see whether a session's strength is reaching the longer averages.

[Open market breadth](https://docs.0xarchive.io/rest-api/breadth.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.