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

# HIP-3 historical market data REST API

> Run HIP-3 builder-perp REST routes under Hyperliquid for trades, order books, candles, funding, OI, liquidations, and L4 data.

Pull HIP-3 builder-perp data on Hyperliquid under `/v1/hyperliquid/hip3/*`: trades, order books, candles, funding, open interest, CVD, liquidations, oracle prices, and L4 depth. HIP-3 symbols carry a builder prefix, such as `xyz:TSLA` or `km:US500`, and the prefix stays part of the symbol in every request and stored record. Find a market with [List HIP-3 instruments](/api-reference/hip-3-builder-perps--instruments/list-hip-3-instruments), and check each data type's history start in [Venue coverage](/venue-coverage).

## First request

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/hip3/trades/xyz:TSLA?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

With no window, the route returns the last 24 hours. For a longer window, follow [Pull historical market data](/guides/historical-market-data). For HIP-3 history as Parquet files, use the [Data Catalog](/data-catalog).

## Symbols

A builder-prefixed symbol such as `xyz:TSLA` is a different kind of instrument from a core Hyperliquid `BTC`, even though both sit under the Hyperliquid venue. Keep the prefix and its case exactly as the instruments route lists it, and do not URL-decode the colon in a way that changes the symbol. A namespaced symbol given without a venue most likely belongs to HIP-3. Store `venue_family=hip3`, or an equivalent field, with persisted results.

HIP-3 serves the same data families as core perps: order books, trades, candles, funding, open interest, CVD, liquidation events, liquidation levels, and freshness. Only the namespace and symbol differ. Exact routes and parameters are in the [HIP-3 endpoint reference](/api-reference/hip3).

## Aliases and historical continuity

Similar tickers or namespaces are not presumed predecessors. Do not stitch histories across distinct market IDs. REST routes accept `xyz:WTIOIL` as an alias for canonical `xyz:CL`; both names refer to the same market identity. Use `xyz:CL` for discovery and coverage checks. This is one same-identity REST alias, not a general alias or predecessor registry. Do not assume this alias works for WebSocket subscriptions or Data Catalog exports.

## Analytics and oracle routes

| Need | Route |
| - | - |
| CVD buckets | `/v1/hyperliquid/hip3/cvd/{symbol}` |
| Projected liquidation levels | `/v1/hyperliquid/hip3/liquidations/{symbol}/levels` |
| Trigger-order map | `/v1/hyperliquid/hip3/orders/{symbol}/trigger-levels` |
| External oracle price | `/v1/hyperliquid/hip3/oracle/external-price/{symbol}` |
| Oracle discovery bounds | `/v1/hyperliquid/hip3/oracle/discovery-bounds/{symbol}` |

These routes add cumulative volume delta, projected liquidation levels, pending trigger-order clustering around price, and HIP-3 oracle state to trades, candles, funding, open interest, and depth. Both projected liquidation-level routes also serve `/history` variants with cursor pagination; snapshots are retained from 2026-07-27. CVD buckets run from `1m` to `1w` and page with `cursor` and `limit`, like the core CVD route; see [Pagination](/rest-api/pagination) for joining pages.

## Breadth above session VWAP

These aggregate routes track the share of eligible HIP-3 instruments trading above their current UTC-session VWAP:

| Need | Route |
| - | - |
| Current snapshot | `GET /v1/hyperliquid/hip3/breadth/above-vwap/current` |
| Historical snapshots | `GET /v1/hyperliquid/hip3/breadth/above-vwap` |

Each eligible instrument contributes one vote. The routes return aggregate breadth only, not per-symbol VWAPs. Eligibility excludes instruments with no current-session volume or with a last completed 1-minute candle close older than 5 minutes, so eligibility changes with trading activity and candle freshness.

Data collection begins 2026-08-28. There is no synthetic pre-launch history, so earlier ranges contain no backfilled snapshots. When `counts.eligible` is zero, `value_pct` is `null`, not `0`.

The history route accepts `start` and `end` as Unix timestamps in milliseconds. Its optional `interval` selects the last stored snapshot in each bucket; percentages are never averaged, because the eligible denominator can vary. Pass the `cursor` from `meta.next_cursor` unchanged and treat it as exclusive. [Market breadth](/rest-api/breadth) covers the methodology, response fields, and how HIP-3 breadth differs from core-perps breadth.

## Next step

Check a HIP-3 window for gaps before a long pull with [Data quality](/data-quality).


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