Overview

The trades stream (also known as fills) contains executed trade data from the Hyperliquid exchange.

Stream Type: TRADES
API Availability: gRPC Streaming API + JSON-RPC/WebSocket APIs
Volume: High - Multiple trades per block during active trading

Data Structure

Each block contains an array of trade events. Trades always come in pairs (maker and taker sides of the same trade).

{
  "local_time": "2025-12-04T17:52:45.734593237",
  "block_time": "2025-12-04T17:52:45.554315846",
  "block_number": 817863403,
  "events": [
    [
      "0x<user_address>",
      {
        "coin": "BTC",
        "px": "92385.0",
        "sz": "0.00361",
        "side": "B",
        "time": 1764867600518,
        "startPosition": "0.0",
        "dir": "Open Long",
        "closedPnl": "0.0",
        "hash": "0x<transaction_hash>",
        "oid": 258166309475,
        "crossed": true,
        "fee": "0.190767",
        "tid": 1081368440085115,
        "feeToken": "USDC",
        "cloid": "0x<client_order_id>",
        "builder": "0x<builder_address>",
        "builderFee": "0.046691",
        "twapId": 1430535
      }
    ]
  ]
}

Field Definitions

Required Fields

Field	Type	Description
coin	string	Trading pair identifier (e.g., "BTC", "ETH", "xyz:HOOD", "@198", "#0")
px	string	Execution price
sz	string	Trade size/quantity
side	string	Trade side: "B" (Buy) or "A" (Ask/Sell)
time	integer	Execution timestamp (Unix milliseconds)
startPosition	string	User's position before this trade
dir	string	Trade direction/type (see Direction Types below)
closedPnl	string	Realized PnL from closing positions
hash	string	Transaction hash
oid	integer	Order ID
crossed	boolean	Whether order crossed the spread (true = taker, false = maker)
fee	string	Trading fee charged
tid	integer	Trade ID (unique identifier for the trade)
feeToken	string	Token used for fee payment (e.g., "USDC", "HYPE", "USDT0"); any spot token can appear. Outcome fills use the format "+N" where N is the numeric outcome side index matching the coin's #N identifier (e.g., "+0", "+1", "+440").
twapId	integer or null	TWAP order identifier (if part of TWAP execution)

Optional Fields

Field	Type	Description
cloid	string	Client order ID (custom identifier set by user)
builder	string	Builder address (MEV builder/order flow provider)
builderFee	string	Fee paid to the builder
deployerFee	string	Fee paid to the market deployer; present on HIP-3 market trades (xyz:, vntl:, cash:, etc.) where a deployer fee applies; absent on standard perp and spot trades
priorityGas	string	Gossip priority gas paid by the user to get priority ordering in the current auction slot (HYPE-denominated, absent when not used)
liquidation	object	Present only on liquidation trades; contains liquidatedUser, markPx, and method fields

Liquidation Data

The trades stream is the primary source for liquidation events. When a trade is part of a liquidation, it includes a liquidation object with detailed information:

Field	Type	Description
liquidation.liquidatedUser	string	Address of the user being liquidated
liquidation.markPx	string	Mark price at the time of liquidation
liquidation.method	string	Liquidation method (e.g., "market")

Filtering for liquidations:

{"streamType": "trades", "filters": {"liquidation": ["*"]}}

Builder Fee Data

Builder fees show MEV builder involvement in trades:

Field	Type	Description
builder	string	MEV builder address (when present)
builderFee	string	Fee paid to the builder

Filtering for builder trades:

{"streamType": "trades", "filters": {"builder": ["*"]}}

Direction Types

The dir field indicates the type of trade action:

Direction	Description
Buy	Spot market buy
Sell	Spot market sell
Open Long	Open a long perpetual position
Open Short	Open a short perpetual position
Close Long	Close a long perpetual position
Close Short	Close a short perpetual position
Long > Short	Flip from long position to short position
Short > Long	Flip from short position to long position
Net Child Vaults	Internal vault rebalancing/netting
Negate Outcome	Outcome market: cancel/negate an existing outcome position
Merge Outcome	Outcome market: merge complementary Yes/No positions to redeem collateral
Split Outcome	Outcome market: split collateral into Yes/No outcome positions
Merge Question	Outcome market: merge all sub-outcomes of a resolved question

Example Trades

Spot Buy

{
  "coin": "@198",
  "px": "0.0123",
  "sz": "871.9",
  "side": "B",
  "time": 1764867600701,
  "startPosition": "4.207665",
  "dir": "Buy",
  "closedPnl": "0.0",
  "hash": "0x57a93d7773a45a5359220430bf015702042f005d0ea77925fb71e8ca32a8343d",
  "oid": 258166311363,
  "crossed": true,
  "fee": "0.585916",
  "tid": 433967339133223,
  "feeToken": "WOULD",
  "twapId": null
}

Open Long Position

{
  "coin": "HEMI",
  "px": "0.016385",
  "sz": "754.0",
  "side": "B",
  "time": 1764867600054,
  "startPosition": "4496.0",
  "dir": "Open Long",
  "closedPnl": "0.0",
  "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "oid": 258166267029,
  "crossed": false,
  "fee": "0.0",
  "tid": 67363762501869,
  "cloid": "0x20251204000000000000000000381433",
  "feeToken": "USDC",
  "twapId": null
}

Position Flip (Short to Long)

{
  "coin": "xyz:XYZ100",
  "px": "25600.0",
  "sz": "0.0027",
  "side": "B",
  "time": 1764867600518,
  "startPosition": "-0.0001",
  "dir": "Short > Long",
  "closedPnl": "0.000351",
  "hash": "0x7f08a6e55e57ee1180820430bf015402066100caf95b0ce322d152381d5bc7fc",
  "oid": 258166169652,
  "crossed": false,
  "fee": "0.015814",
  "builderFee": "0.013824",
  "tid": 931158683853203,
  "cloid": "0x49a6df9ed40b4efa8f93535dd8803465",
  "feeToken": "USDC",
  "builder": "0x999a4b5f268a8fbf33736feff360d462ad248dbf",
  "twapId": null
}

Liquidation Trade

{
  "coin": "CRV",
  "px": "0.39626",
  "sz": "1076.0",
  "side": "B",
  "time": 1766671523811,
  "startPosition": "-2777.0",
  "dir": "Close Short",
  "closedPnl": "-19.5294",
  "hash": "0xbce01e7d41ad9ff1be5904321300250201890062dca0bec360a8c9d000a179dc",
  "oid": 278847514653,
  "crossed": true,
  "fee": "0.191869",
  "tid": 620686698918268,
  "liquidation": {
    "liquidatedUser": "0x7a475736bf02d67bf51b00414ab766ef4da9214d",
    "markPx": "0.39617",
    "method": "market"
  },
  "feeToken": "USDC",
  "twapId": null
}

Builder Fee Trade

{
  "coin": "CRV",
  "px": "0.39645",
  "sz": "909.9",
  "side": "A",
  "time": 1766671523811,
  "startPosition": "109083.8",
  "dir": "Close Long",
  "closedPnl": "11.865096",
  "hash": "0xbce01e7d41ad9ff1be5904321300250201890062dca0bec360a8c9d000a179dc",
  "oid": 278847504835,
  "crossed": false,
  "fee": "0.059158",
  "builderFee": "0.036072",
  "tid": 856474671603519,
  "cloid": "0x94be780c945d077a58273f343342f4c3",
  "liquidation": {
    "liquidatedUser": "0xd0be131babb6abb6da97ceee4a6207ada82d9aa8",
    "markPx": "0.39617",
    "method": "market"
  },
  "feeToken": "USDC",
  "builder": "0x6530512a6c89c7cfcebc3ba7fcd9ada5f30827a6",
  "twapId": null
}

Outcome Market Fill (HIP-4)

Outcome assets (HIP-4) trade as #N-prefixed coins. For any outcome index O, Yes is coin #(O*10) and No is coin #(O*10+1). Multi-price question markets group multiple binary sub-outcomes (named price buckets plus a fallback), each with its own Yes/No coin pair. Both sides of a matched outcome trade appear as Buy fills; the protocol pairs two buyers rather than a buyer and seller. Opening outcome fills carry zero fees; fees are charged on closing and settlement fills. feeToken uses the +N format (the index matching the coin).

{
  "coin": "#1",
  "px": "0.4",
  "sz": "40.0",
  "side": "B",
  "time": 1777709066444,
  "startPosition": "44.0",
  "dir": "Buy",
  "closedPnl": "0.0",
  "hash": "0xe0d75028e77608d3e251043a76a4d9016a00680e827927a5849ffb7ba679e2be",
  "oid": 407302564659,
  "crossed": false,
  "fee": "0.0",
  "tid": 583268316112767,
  "feeToken": "+1",
  "twapId": null
}

API Usage

gRPC Streaming

// Subscribe to trades
const request = {
  subscribe: {
    stream_type: 'TRADES',
    filters: {
      coin: { values: ['BTC', 'ETH'] },
      side: { values: ['B'] }
    }
  }
};

JSON-RPC

# Get latest trade blocks
curl -X POST https://your-endpoint.hype-mainnet.quiknode.pro/your-token/hypercore \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "hl_getLatestBlocks",
    "params": {
      "stream": "trades",
      "count": 10
    },
    "id": 1
  }'

WebSocket

// Subscribe to trades
ws.send(JSON.stringify({
  "method": "hl_subscribe",
  "params": {
    "streamType": "trades"
  }
}));

Important Notes

• Trades come in pairs: Each trade has a buyer side ("B") and a seller side ("A") with the same tid (trade ID) and hash
• Maker vs Taker: The crossed field indicates taker (true) or maker (false) status
• Fee Tokens: Most fees are paid in USDC, but any spot token can appear (e.g., HYPE, USDT0). Outcome fills use +N (e.g., "+0", "+1") where N is the outcome side index
• Coin Prefixes: The coin field uses prefix conventions: standard perps have no prefix (e.g., "BTC"), prediction market stocks use xyz: (e.g., "xyz:NVDA"), cash-settled RWA tokens use cash: (e.g., "cash:AMZN"), spot tokens use @N (token index), and outcome sides use #N (e.g., "#0" for Yes, "#1" for No)
• Builder Fees: When present, indicate MEV builder involvement in the trade
• TWAP Orders: Non-null twapId values indicate the trade is part of a TWAP execution
• Position Flips: Long > Short and Short > Long indicate position direction changes in a single trade

Related Streams

• Orders - View the order lifecycle events that lead to these trades
• Book Updates - See how these trades affect the order book
• TWAP - Track TWAP algorithm progress for trades with twapId