Trade intent

Split a market’s volume by why it traded: new longs and shorts, profit taken, positions stopped out, and flips through zero, with market makers counted apart. Each bucket also shows what the market’s winners and losers over the last 72 hours hold and trade, as aggregates. Trade intent covers Hyperliquid core and HIP-3 markets, one market per request, and comes with the Build, Pro, Scale and Enterprise plans.

How a trade is classified

Every fill has two sides, and both are counted. Each side lands in one bucket by what it did to its own position:

Bucket	Volume, in USD
`open_long`, `open_short`	Opened or increased a long (a buy) or a short (a sell)
`tp_long`, `tp_short`	Reduced or closed a long (a sell) or a short (a buy) at a profit: closed PnL above zero, not forced
`stop_long`, `stop_short`	Reduced or closed a long or a short at a loss or break-even, or by liquidation or auto-deleveraging
`flip_ls`, `flip_sl`	Took a position from long to short (a sell) or from short to long (a buy) in one fill
`mm_usd`	Traded by a wallet classified as a market maker, in place of any of the buckets above

A wallet is a market maker for a fill when, over its fills on that market in the 7 days before, it has at least 200 fills, at least 80% of its notional filled as the resting (maker) side, and at least 20 flips. Because both sides count, the eight buckets plus mm_usd add up to twice the bucket’s traded notional. Delisting settlements are in no bucket.

Winners and losers

Winners and losers are the wallets up and down the most on the market over the trailing 72 hours, market makers excluded. A wallet counts in proportion to how far up or down it is, in full from the 50th-largest gain or loss on that market, and a large position close to break-even barely counts. They are served as aggregates only; no wallet is named.

Field	Meaning
`winners_net`, `losers_net`	The cohort’s net position in USD at the bucket’s end, long positive
`winners_gross`, `losers_gross`	The cohort’s gross position in USD at the bucket’s end
`winners_count`, `losers_count`	Wallets in the cohort at full weight
`winners_flow`, `losers_flow`	What the cohort bought less what it sold during the bucket, in USD. The cohort is weighted as it stood at the previous hour’s close, so wallets entering or leaving it do not move the flow

A cohort’s net position lags turns by construction: after a reversal, the wallets already positioned the new way become the winners. The flow does not have that lag.

Routes

Dataset	Route and endpoint reference
Hyperliquid core	`/v1/hyperliquid/trade-intent/{symbol}`: Get Hyperliquid trade intent
HIP-3	`/v1/hyperliquid/hip3/trade-intent/{symbol}`: Get HIP-3 trade intent

HIP-3 symbols keep their builder prefix and case, such as xyz:XYZ100. HIP-4, Spot and Lighter paths answer 404 with error_code unsupported_for_venue.

Plans and credits

Trade intent comes with the Build, Pro, Scale and Enterprise plans. A Free key receives 403 with error_code forbidden, the datatype (trade_intent), 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

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 `1s`, `5s`, `15s`, `1m`, `5m`, `15m`, `1h`, `4h`, `1d`. Defaults to `1h`. Buckets open on UTC epoch boundaries, so `1d` is the UTC day
`limit`	Optional. Buckets per page, default 500, maximum 2,000. A larger value is read as 2,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, so the bucket holding end is served whole. It never goes past the bucket holding now. Set both start and end when paging: without them each request takes the 24 hours before its own now, and a long walk slides. The default page starts at the beginning of that window, not at its newest buckets. Stop paging when meta.next_cursor is absent. A page can hold fewer buckets than limit, or none, and still carry a cursor, because quiet seconds and idle markets have no records.

Example response

curl "https://api.0xarchive.io/v1/hyperliquid/trade-intent/BTC?start=2026-10-23T00:00:00Z&end=2026-10-23T01:00:00Z&interval=1h" \
  -H "X-API-Key: $OXARCHIVE_API_KEY" \
  -H "0xArchive-Version: 2026-10-01"

{
  "success": true,
  "data": [
    {
      "timestamp": "2026-10-23T00:00:00.000Z",
      "timestamp_ms": 1792713600000,
      "close": 81448.0,
      "price_source": "mark",
      "open_long": 50638693.18,
      "open_short": 41296459.21,
      "tp_long": 8084342.05,
      "tp_short": 29240753.02,
      "stop_long": 30236676.09,
      "stop_short": 12304052.04,
      "flip_ls": 683012.29,
      "flip_sl": 334456.02,
      "mm_usd": 84960401.5,
      "winners_flow": -2861558.86,
      "losers_flow": -607408.26,
      "winners_net": -77011655.75,
      "winners_gross": 121926882.58,
      "losers_net": 46895101.67,
      "losers_gross": 155965344.67,
      "winners_count": 17,
      "losers_count": 16,
      "quality": "ok",
      "is_final": true,
      "preliminary": false,
      "preliminary_from": null,
      "preliminary_from_ms": null,
      "method": "who/3"
    }
  ],
  "meta": {
    "count": 2,
    "has_more": false,
    "built_through": "2026-11-04T19:00:00.000Z",
    "symbol": "BTC",
    "venue": "hyperliquid",
    "request_id": "416b037a-4c60-4344-a018-2223fd26a536"
  }
}

The response above is trimmed to its first bucket. Every USD figure is rounded to the cent.

Response fields

Field	Meaning
`timestamp`, `timestamp_ms`	Bucket open, RFC 3339 UTC and Unix milliseconds
`close`	The price the bucket’s end is marked at. Null at second intervals
`price_source`	Where `close` comes from: `mark`, `oracle` (a HIP-3 market without a stored mark), `carried` (the last of those when none is recent) or `trade`. Null at second intervals
Intent buckets and `mm_usd`	USD volume, as in How a trade is classified
Winners and losers	As in Winners and losers. Positions and counts are null at second intervals
`quality`	`ok`; `partial` while the method’s 7-day lookbacks were not yet full; `quarantined` when an input failed a continuity check, in which case the winners’ and losers’ figures are null. The intent buckets are always served
`is_final`	The bucket is complete and will not change
`preliminary`, `preliminary_from`, `preliminary_from_ms`	The bucket holds figures computed live after the archive’s end, from `preliminary_from` on. They are replaced by the archived figures once those hours are built
`method`	The method version, `who/3`, or `who/2` on older rows
`meta.built_through`	How far the series is built
`meta.preliminary_row_count`	Number of preliminary buckets in the page, when there are any

Read the series correctly

A missing bucket is a gap, not zero. A market that did not trade for more than 7 days has no buckets for that time. A second without trades has no record: up to meta.built_through it had no trades, and after it nothing is known yet. Second intervals carry the additive figures only. At 1s, 5s and 15s a record has the intent buckets, mm_usd and the cohort flows, but no close, price_source, cohort positions or counts. Wait for is_final before storing. Buckets after the archive’s end, normally the current hour, are preliminary and change as the archive is built. A bucket marked is_final does not change. A 503 is retryable. If a read runs out of time the route answers 503 with error_code upstream_unavailable and Retry-After. Retry, or lower limit or narrow start and end.

Available history

Interval	Coverage
`1h`, `4h`, `1d`	Hyperliquid core from 2025-05-25 15:00 UTC; HIP-3 from 2025-10-13 12:00 UTC
`1m`, `5m`, `15m`	Both venues from 2026-07-14 00:00 UTC
`1s`, `5s`, `15s`	Both venues, the last 3 days, starting on the hour

A window that ends before its interval’s coverage returns an empty page with meta.coverage_from and meta.notice; a window that straddles it is served from it. At the HIP-3 start, a 4h or 1d bucket opens before 12:00 UTC and holds the rows from 12:00 on.

Access

Each venue’s start date, plans and page limit come from GET /v1/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.

Venue	Availability
Hyperliquid	From 2025-05-25 15:00 UTC REST only, no WebSocket channel Plans: Build, Pro, Scale and Enterprise only Up to 2,000 rows a page Why volume traded, per interval: USD of new longs and shorts, profit taken, stopped out and flips (both sides of every trade; market makers apart, in mm_usd), and the aggregate position and flow of the market’s trailing-72h winners and losers. Hourly intervals from available_from, minute intervals from 2026-07-14 00:00 UTC, second intervals for the last 3 days. A market idle for more than 7 days has no buckets there: a gap, not zero.
HIP-3	From 2025-10-13 12:00 UTC REST only, no WebSocket channel Plans: Build, Pro, Scale and Enterprise only Up to 2,000 rows a page Why volume traded, per interval: USD of new longs and shorts, profit taken, stopped out and flips (both sides of every trade; market makers apart, in mm_usd), and the aggregate position and flow of the market’s trailing-72h winners and losers. Hourly intervals from available_from, minute intervals from 2026-07-14 00:00 UTC, second intervals for the last 3 days. A market idle for more than 7 days has no buckets there: a gap, not zero.

Surface	Names
Python SDK	`client.hyperliquid.trade_intent.history(symbol, ...)`; HIP-3 `client.hyperliquid.hip3.trade_intent.history(...)`
TypeScript SDK	`client.hyperliquid.tradeIntent.history(symbol, ...)`; HIP-3 `client.hyperliquid.hip3.tradeIntent.history(...)`
Rust SDK	`client.hyperliquid.trade_intent.history`; HIP-3 `client.hyperliquid.hip3.trade_intent.history`
CLI	`oxa trade-intent history <symbol> --exchange hyperliquid\|hip3`
MCP tools	`get_trade_intent`, `get_hip3_trade_intent`

Stream it live

There is no trade intent WebSocket channel. Poll the route for the preliminary buckets of the current hour, and read them again once is_final is true.

Endpoint reference

Requests and responses

Datasets

Venues

OpenAPI and schemas

Guides

How a trade is classified

Winners and losers

Routes

Plans and credits

Request parameters

Example response

Response fields

Read the series correctly

Available history

Access

Stream it live

Use it from an agent

Next step

​How a trade is classified

​Winners and losers

​Routes

​Plans and credits

​Request parameters

​Example response

​Response fields

​Read the series correctly

​Available history

​Access

​Stream it live

​Use it from an agent

​Next step

How a trade is classified

Winners and losers

Routes

Plans and credits

Request parameters

Example response

Response fields

Read the series correctly

Available history

Access

Stream it live

Use it from an agent

Next step