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

# Positioning

> Every listed Hyperliquid core or HIP-3 perp over a trailing 1h, 4h or 24h window in one call: open interest change, taker flow, liquidations, typical moves and positioning state. Build plan and above.

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](https://docs.0xarchive.io/api-reference/hyperliquid--positioning/get-hyperliquid-positioning.md) |
| HIP-3 | `/v1/hyperliquid/hip3/positioning`: [Get HIP-3 positioning](https://docs.0xarchive.io/api-reference/hip-3-builder-perps--positioning/get-hip-3-positioning.md) |

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

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

```json theme={"theme":"github-dark"}
{
  "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](#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`](https://docs.0xarchive.io/capabilities). Send `0xArchive-Version: 2026-10-01` for the current response contract; see [API conventions](https://docs.0xarchive.io/conventions.md).

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

## Use it from an agent

**Ask which markets are being positioned**

Through the [MCP server](https://docs.0xarchive.io/mcp-server.md), name core perps or HIP-3 and the window, 1h, 4h or 24h, and ask for the markets in a given positioning state, or with the largest open interest change or taker imbalance against their typical move.

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

## Next step

**Follow one market back in time**

Positioning shows the current window only. For one market's history, read its open interest series at 5-minute resolution.

[Explore open interest](https://docs.0xarchive.io/rest-api/open-interest.md)


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