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

# Trade intent

> Why a Hyperliquid or HIP-3 market traded, per interval: volume of new positions, profit taking, stops and flips, market-maker volume, and the aggregate position and flow of its winners and losers. Build plan and above.

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

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

```bash theme={"theme":"github-dark"}
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"
```

```json theme={"theme":"github-dark"}
{
  "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](#how-a-trade-is-classified) |
| Winners and losers | As in [Winners and losers](#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`](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-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.

## Use it from an agent

**Ask why a market moved**

Through the [MCP server](https://docs.0xarchive.io/mcp-server.md), name the market and the venue, Hyperliquid core or HIP-3, and ask for trade intent over a window, on a Build plan or above.

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

## Next step

**Read the trades behind a bucket**

Open the fills of the same market and window to see the individual trades that make up a trade intent bucket.

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


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