Hyperliquid data for agents: perp analytics through one tool family

1. The same three tools, one more venue

The Portal's tools follow a pattern across virtual machines. For each chain there is a way to pull raw records, a way to get a market-level analytics summary, and, where it makes sense, a way to build OHLC candles. Hyperliquid is not a special case bolted on the side; it uses the same verbs.

2. A whole-market snapshot

portal_hyperliquid_get_analytics with coin: ["BTC"] over a one-hour window answers "what is the BTC perp market doing right now" in a single call. A recent run returned the headline figures below, alongside ranked sections for top traders by volume and the realized-PnL winners and losers.

That is a market overview an agent can reason about directly: participation, notional, liquidation pressure, and directional bias, without stitching together raw rows. The ranked sections give it the leading accounts to drill into next.

3. Candles without a candle service

portal_hyperliquid_get_ohlc turns the same fill tape into chart-ready candles, with open, high, low, close, volume, VWAP, and a per-bucket fill count, derived from trades rather than from a separate candle feed. A six-hour BTC request, run on 2026-06-19, returned 24 fifteen-minute buckets, all populated. This tool always covers recent history, so your buckets will differ; the shape and the per-bucket detail are the point:

Because the candles come from the underlying fills, the VWAP and fill count per bucket are exact for the data set rather than approximations, and the same OHLC tool shape works on EVM DEX trades. This is the read-only counterpart to building your own candle table, which the Pipes SDK leaderboard guide does by streaming the same tape into ClickHouse.

4. Down to the fill

When the agent needs the underlying trades, portal_hyperliquid_query_fills returns raw rows, the same fills you can pull straight from the Stream API. Each carries the trader, coin, side (B is buy, A is sell), direction, price, size, fee, closedPnl, a shared trade id (tid), and a crossed flag that marks the taker. Here is the curl and a real pair of fills from one execution, the maker and taker sides:

Both rows share one tid, which is what proves they are the two sides of a single execution; crossed: true marks the taker (the aggressor), while the resting maker side carries the negative fee, a rebate, against the taker's positive fee. The maker's closedPnl is the realized result of closing part of a short. Net realized PnL for a trader is the sum of closedPnl across their closing fills minus the sum of fee, both read from the records, not reconstructed from positions. Fees are signed, so a negative maker rebate adds to the total and a positive taker fee subtracts; ignore the field and you misstate the result whenever fees are in play. That boundary matters: the dataset is executed trades, so it does not report open positions or balances. The full fill schema and the way Hyperliquid classifies its crypto, TradFi, and HIP-3 markets are covered in the Hyperliquid perps data guide.

5. The pagination gotcha

The analytics tools return a preview page. The ranked sections, top traders and PnL winners and losers, can have more rows behind a cursor, and the response carries a _pagination.next_cursor plus a has_more flag per section. An agent that reads only the first page and reports "the top trader is X" may be right about the page and wrong about the window.

The rule for the agent is to follow the cursor until has_more is false before treating a ranking as complete. One smaller thing in the same spirit: the coin filter is an array, so a single market is ["BTC"], not "BTC".

6. Why this is harder elsewhere

For the conceptual pattern behind agents calling these tools, see AI agents and onchain data, and to wire the tools into an editor, the Portal MCP setup. To own the fill data in your own warehouse, the Pipes SDK leaderboard guide is the build companion.