Skip to main content

Trades Dataset

Updated on
Jan 08, 2026

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")
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", "WOULD", "UXPL", "USDH")
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

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
liquidation.liquidatedUser
Type
string
Description
Address of the user being liquidated
Field
liquidation.markPx
Type
string
Description
Mark price at the time of liquidation
Field
liquidation.method
Type
string
Description
Liquidation method (e.g., "market")

Filtering for liquidations:

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

Builder Fee Data​

Builder fees show MEV builder involvement in trades:

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

Filtering for builder trades:

{"streams": ["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

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
}

API Usage​

gRPC Streaming
// Subscribe to trades
const request = {
  subscribe: {
    stream_type: 'TRADES',
    start_block: 0,
    filters: {
      "coin": ["BTC", "ETH"],
      "user": ["0x123..."]
    }
  }
};
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": {
    "streams": ["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 can also be paid in native tokens like HYPE, WOULD, UXPL, or USDH
  • 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

  • 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
Last updated on
Share this doc