Positioning

Rank or group a whole venue by positioning in one request: for every listed perp, the change in open interest and mark over a trailing window, taker buy and sell volume, liquidations on each side, how large each of those moves usually is for that market, and the positioning state the window ends in. Positioning covers Hyperliquid core and HIP-3, returns the current window only, and comes with the Build, Pro, Scale and Enterprise plans.

The window

window is required: 1h, 4h or 24h. Every record covers [window_start, window_end). The window ends at the newest 5-minute boundary that is at least 4 minutes old, so a response at 20:05 UTC describes the window ending at 20:00. meta.as_of names that boundary and equals every record’s window_end. History is not served. The route refuses every parameter other than window with 400 and error_code invalid_parameter, naming it: a request with end is told that history is not served rather than silently given the current window. Shortly after a new boundary, a response can still describe the previous one for a short time while the next is prepared. Compare meta.as_of across responses rather than assuming the newest boundary.

Routes

Dataset	Route and endpoint reference
Hyperliquid core	`/v1/hyperliquid/positioning`: Get Hyperliquid positioning
HIP-3	`/v1/hyperliquid/hip3/positioning`: Get HIP-3 positioning

The Hyperliquid core route returns every listed perp. The HIP-3 route returns every HIP-3 perp with open interest above zero in the last hour. Delisted markets are not included. Records are sorted by symbol and the response is not paged. HIP-4, Spot and Lighter paths answer 404 with error_code unsupported_for_venue.

Plans and credits

Positioning comes with the Build, Pro, Scale and Enterprise plans. A Free key receives 403 with error_code forbidden, the datatype (positioning), the required_plans and an upgrade_url. A refused request is not charged. Each request costs 1 credit, for every market in the response.

Example response

curl "https://api.0xarchive.io/v1/hyperliquid/positioning?window=4h" \
  -H "X-API-Key: $OXARCHIVE_API_KEY" \
  -H "0xArchive-Version: 2026-10-01"

{
  "success": true,
  "data": [
    {
      "symbol": "BTC",
      "window": "4h",
      "window_start": "2026-11-04T18:30:00.000Z",
      "window_start_ms": 1793817000000,
      "window_end": "2026-11-04T22:30:00.000Z",
      "window_end_ms": 1793831400000,
      "oi_start": 39958.9094,
      "oi_end": 38206.18464,
      "mark_start": 80563.0,
      "mark_end": 80637.0,
      "oi_buckets": 48,
      "buy_usd": 274605275.98,
      "sell_usd": 266745711.64,
      "liq_long_usd": 131487.73,
      "liq_short_usd": 0.0,
      "liq_long_count": 32,
      "liq_short_count": 0,
      "typical_price": 0.003534518682044352,
      "typical_oi": 0.010502399375040827,
      "typical_flow": 0.10112064812967125,
      "typical_windows": 1952,
      "typical_delta": 31793605.17999813,
      "bar_enter": 4.99613359240813,
      "bar_exit": 3.4086739537905455,
      "state": "quiet"
    }
  ],
  "meta": {
    "count": 179,
    "as_of": "2026-11-04T22:30:00.000Z",
    "request_id": "126d0db9-a1ea-4b58-afb9-5d1aae6baf33"
  }
}

The response above is trimmed to one of its 179 records.

Response fields

Field	Meaning
`symbol`	The market. HIP-3 symbols carry their builder prefix, such as `xyz:XYZ100`
`window`, `window_start`, `window_end`	The requested window and its bounds, with `*_ms` twins in Unix milliseconds
`oi_start`, `oi_end`	Open interest in contracts at the 5-minute reading before the window and at its last 5-minute reading
`mark_start`, `mark_end`	Mark price at the same two readings
`oi_buckets`	Number of 5-minute open interest readings inside the window
`buy_usd`, `sell_usd`	Taker buy and sell notional in the window, USD to the cent
`liq_long_usd`, `liq_short_usd`	Notional of long and short positions liquidated in the window, USD to the cent
`liq_long_count`, `liq_short_count`	Number of long and short liquidations in the window
`typical_price`, `typical_oi`, `typical_flow`	The market’s typical move over windows of the same length, described below
`typical_windows`	Windows counted for the typical moves
`typical_delta`	The market’s median absolute net taker USD, `buy_usd - sell_usd`, over the same windows
`bar_enter`, `bar_exit`	The length of the positioning vector at the 92nd and the 80th percentile of the market’s own windows
`state`	The positioning state the window ends in, described in Positioning state
`meta.as_of`	The 5-minute boundary the records describe

Read the cross-section correctly

Null is not zero. oi_start, oi_end, mark_start and mark_end are null when their 5-minute bucket has no reading. Flows and liquidations are sums, so 0.0 there means none. Typical moves make markets comparable. Each typical_* figure is the median absolute move over every window of the same length, sliding by 5 minutes through the last 2,000 five-minute buckets, about 6.9 days: the mark’s relative change for typical_price, the relative change in open interest for typical_oi, and the taker imbalance (buy - sell) / (buy + sell) for typical_flow. Divide a market’s move in this window by its typical move to compare a quiet market with a busy one. Under 288 counted windows the three are null. A 503 is retryable. While the cross-section is still being prepared, the route answers 503 with error_code upstream_unavailable and Retry-After. Retry after the delay.

Positioning state

state names what open interest, taker flow and price did together, judged against the market’s own history rather than one threshold for every market:

`state`	Meaning
`long-buildup`	Net taker buying while open interest rises, and price moved up
`short-covering`	Net taker buying while open interest falls, and price moved up
`short-buildup`	Net taker selling while open interest rises, and price moved down
`long-unwinding`	Net taker selling while open interest falls, and price moved down
`mixed`	Open interest and taker flow moved by at least `bar_enter`, but price moved against the flow or not at all
`quiet`	Below `bar_enter`, and not holding one of the four states above

Every window of the same length in the last 2,000 five-minute buckets gets a vector: its relative change in open interest divided by the market’s median one, and its net taker USD divided by typical_delta. The vector’s length is the square root of the sum of their squares. bar_enter is the length at the 92nd percentile of the market’s own windows and bar_exit the length at the 80th, so only a market’s largest moves for its own size can enter a state. The windows are walked oldest first. A window enters the state of its signs when its length reaches bar_enter and price moved the way taker flow leans. A held state continues while the next window has the same signs of open interest change and net taker flow, at a length of at least bar_exit, so a state does not switch on and off around the entry bar. A window that is not counted ends any held state. state is the state of the window that ends at window_end. A window is counted when open interest and the mark were read, and not zero, at both of its ends, and it had at least one trade. The four fields are null in three cases:

Under 288 counted windows, all four are null, as the typical moves are.
When the market’s median open interest change or median net taker USD is zero, typical_delta is served and the other three are null.
When the window ending at window_end is not counted, state is null.

Access

Each venue’s plans and the SDK, CLI and MCP names for the same data come from GET /v1/capabilities. Send 0xArchive-Version: 2026-10-01 for the current response contract; see API conventions.

Venue	Availability
Hyperliquid	No history: the current window only REST only, no WebSocket channel Plans: Build, Pro, Scale and Enterprise only No fixed page limit Every listed perp’s open interest change, taker buy and sell volume and liquidations over a trailing window (window required: 1h, 4h or 24h), with each market’s typical move over windows of that length: the median absolute move over the last 2,000 five-minute steps, null under 288 counted windows, and its positioning state (long-buildup, short-covering, short-buildup, long-unwinding, mixed or quiet) from its open interest and net taker flow against its own typical moves. The window ends at the newest 5-minute close; open interest and marks are null when a bucket has no reading, never 0. Current window only: history is not served. One record per perp, unpaged.
HIP-3	No history: the current window only REST only, no WebSocket channel Plans: Build, Pro, Scale and Enterprise only No fixed page limit Every listed perp’s open interest change, taker buy and sell volume and liquidations over a trailing window (window required: 1h, 4h or 24h), with each market’s typical move over windows of that length: the median absolute move over the last 2,000 five-minute steps, null under 288 counted windows, and its positioning state (long-buildup, short-covering, short-buildup, long-unwinding, mixed or quiet) from its open interest and net taker flow against its own typical moves. The window ends at the newest 5-minute close; open interest and marks are null when a bucket has no reading, never 0. Current window only: history is not served. One record per perp, unpaged.

Surface	Names
Python SDK	`client.hyperliquid.positioning.current(window=...)`; HIP-3 `client.hyperliquid.hip3.positioning.current(...)`
TypeScript SDK	`client.hyperliquid.positioning.current({ window })`; HIP-3 `client.hyperliquid.hip3.positioning.current(...)`
Rust SDK	`client.hyperliquid.positioning.current`; HIP-3 `client.hyperliquid.hip3.positioning.current`
CLI	`oxa positioning current --window 1h\|4h\|24h --exchange hyperliquid\|hip3`
MCP tools	`get_positioning`, `get_hip3_positioning`

Stream it live

There is no positioning WebSocket channel. A new cross-section is ready every 5 minutes; poll on that cadence and check meta.as_of.

Endpoint reference

Requests and responses

Datasets

Venues

OpenAPI and schemas

Guides

The window

Routes

Plans and credits

Example response

Response fields

Read the cross-section correctly

Positioning state

Access

Stream it live

Use it from an agent

Next step

​The window

​Routes

​Plans and credits

​Example response

​Response fields

​Read the cross-section correctly

​Positioning state

​Access

​Stream it live

​Use it from an agent

​Next step

The window

Routes

Plans and credits

Example response

Response fields

Read the cross-section correctly

Positioning state

Access

Stream it live

Use it from an agent

Next step