Présentation générale

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

Stream Type: MÉTIERS
Disponibilité de l'API : gRPC Streaming API + JSON-RPC/WebSocket APIs
Volume: High - Multiple trades per block during active trading

Structure de données

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

Champ	Type	Description
pièce de monnaie	chaîne de caractères	Trading pair identifier (e.g., "BTC", "ETH", "xyz:HOOD", "@198", "#0")
px	chaîne de caractères	Execution price
sz	chaîne de caractères	Trade size/quantity
côté	chaîne de caractères	Trade side: "B" (Buy) or "A" (Ask/Sell)
temps	entier	Execution timestamp (Unix milliseconds)
startPosition	chaîne de caractères	User's position before this trade
dir	chaîne de caractères	Trade direction/type (see Direction Types below)
closedPnl	chaîne de caractères	Realized PnL from closing positions
hachage	chaîne de caractères	Transaction hash
oid	entier	Order ID
crossed	booléen	Whether order crossed the spread (true = taker, false = maker)
frais	chaîne de caractères	Trading fee charged
tid	entier	Trade ID (unique identifier for the trade)
feeToken	chaîne de caractères	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

Champ	Type	Description
cloïde	chaîne de caractères	Référence de la commande client (identifiant personnalisé défini par l'utilisateur)
builder	chaîne de caractères	Builder address (MEV builder/order flow provider)
builderFee	chaîne de caractères	Fee paid to the builder
deployerFee	chaîne de caractères	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	chaîne de caractères	Gossip priority gas paid by the user to get priority ordering in the current auction slot (HYPE-denominated, absent when not used)
liquidation	objet	Present only on liquidation trades; contains liquidatedUser, markPx, and method fields

Liquidation Data

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

Champ	Type	Description
liquidation.liquidatedUser	chaîne de caractères	Address of the user being liquidated
liquidation.markPx	chaîne de caractères	Mark price at the time of liquidation
liquidation.method	chaîne de caractères	Liquidation method (e.g., "market")

Filtering for liquidations:

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

Builder Fee Data

Builder fees show MEV builder involvement in trades:

Champ	Type	Description
builder	chaîne de caractères	MEV builder address (when present)
builderFee	chaîne de caractères	Fee paid to the builder

Filtering for builder trades:

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

Direction Types

Le 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
}

Utilisation de l'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
}));

Remarques importantes

• Trades come in pairs: Each trade has a buyer side ("B") and a seller side ("A") with the same tid (trade ID) and hachage
• 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 (par exemple, "+0", "+1") where N is the outcome side index
• Coin Prefixes: The pièce de monnaie field uses prefix conventions: standard perps have no prefix (e.g., « BTC »), prediction market stocks use xyz: (par exemple, "xyz:NVDA"), cash-settled RWA tokens use cash: (par exemple, "cash:AMZN"), spot tokens use @N (token index), and outcome sides use #N (par exemple, "#0" pour Oui, "#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 et Short > Long indicate position direction changes in a single trade

Streams associés

• 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