Resumen

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

Tipo de arroyo: OFICIOS
Disponibilidad de la API: gRPC Streaming API + JSON-RPC/WebSocket APIs
Volumen: High - Multiple trades per block during active trading

Estructura de datos

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

Campo	Tipo	Descripción
moneda	cadena	Trading pair identifier (e.g., "BTC", "ETH", "xyz:HOOD", "@198", "#0")
px	cadena	Execution price
sz	cadena	Trade size/quantity
lado	cadena	Trade side: "B" (Buy) or "A" (Ask/Sell)
tiempo	entero	Execution timestamp (Unix milliseconds)
posiciónInicial	cadena	User's position before this trade
dir	cadena	Trade direction/type (see Direction Types below)
panel cerrado	cadena	Realized PnL from closing positions
hash	cadena	Transaction hash
oide	entero	Order ID
cruzado	booleano	Whether order crossed the spread (true = taker, false = maker)
cuota	cadena	Trading fee charged
tid	entero	Trade ID (unique identifier for the trade)
feeToken	cadena	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

Campo	Tipo	Descripción
cloide	cadena	ID del pedido del cliente (identificador personalizado establecido por el usuario)
builder	cadena	Builder address (MEV builder/order flow provider)
comisión del constructor	cadena	Fee paid to the builder
deployerFee	cadena	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	cadena	Gossip priority gas paid by the user to get priority ordering in the current auction slot (HYPE-denominated, absent when not used)
liquidation	objeto	Present only on liquidation trades; contains liquidatedUser, markPx, and method fields

Liquidation Data

El 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:

Campo	Tipo	Descripción
liquidation.liquidatedUser	cadena	Address of the user being liquidated
liquidation.markPx	cadena	Mark price at the time of liquidation
liquidation.method	cadena	Liquidation method (e.g., "market")

Filtering for liquidations:

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

Builder Fee Data

Builder fees show MEV builder involvement in trades:

Campo	Tipo	Descripción
builder	cadena	MEV builder address (when present)
comisión del constructor	cadena	Fee paid to the builder

Filtering for builder trades:

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

Direction Types

El dir field indicates the type of trade action:

Direction	Descripción
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
}

Uso de la API

gRPC

// 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({
  "jsonrpc": "2.0",
  "method": "hl_subscribe",
  "params": {
    "streamType": "trades"
  },
  "id": 1
}));

Notas importantes

• 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: El cruzado 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: El moneda 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 y Short > Long indicate position direction changes in a single trade

Streams relacionados

• 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