अवलोकन

The TWAP stream contains Time-Weighted Average Price (TWAP) order status updates from the Hyperliquid exchange. TWAP orders are algorithmic orders that execute gradually over a specified time period to minimize market impact.

Stream Type: TWAP
API Availability: gRPC Streaming API + JSON-RPC/WebSocket APIs
Volume: Low - Most blocks are empty; only updates when TWAP orders change status

Data Structure

Most blocks are empty as TWAP status updates only occur when orders are activated, finished, or terminated. Each event represents a status change for a TWAP order.

{
  "local_time": "2025-12-04T17:00:22.590883578",
  "block_time": "2025-12-04T17:00:22.417074898",
  "block_number": 817824346,
  "events": [
    {
      "time": "2025-12-04T17:00:22.417074898",
      "twap_id": 1430699,
      "state": {
        "coin": "HYPE",
        "user": "0x9d6a5ab97a8eed617bde9968d9ab6fcf72fde1b8",
        "side": "A",
        "sz": "108.36",
        "executedSz": "0.0",
        "executedNtl": "0.0",
        "minutes": 10,
        "reduceOnly": false,
        "randomize": false,
        "timestamp": 1764867622417
      },
      "status": "activated"
    }
  ]
}

Event Fields

मैदान	Type	विवरण
time	डोरी	Event timestamp (ISO 8601 format)
twap_id	पूर्णांक	Unique identifier for the TWAP order
state	वस्तु	Current state of the TWAP order
स्थिति	डोरी	TWAP order status (see Status Types below)

State Object Fields

मैदान	Type	विवरण
सिक्का	डोरी	Trading pair identifier (e.g., "HYPE", "xyz:NVDA", "@107")
user	डोरी	User address who created the TWAP order
ओर	डोरी	Order side: "B" (Buy) or "A" (Ask/Sell)
sz	डोरी	Total target size for the TWAP order
executedSz	डोरी	Amount executed so far
executedNtl	डोरी	Notional value executed (price × size)
minutes	पूर्णांक	Duration of TWAP order in minutes
reduceOnly	बूलियन	Whether order can only reduce position (cannot increase)
randomize	बूलियन	Whether execution timing is randomized to avoid detection
TIMESTAMP	पूर्णांक	TWAP order creation timestamp (Unix milliseconds)

Status Types

TWAP orders progress through different status states during their lifecycle, from initial creation to completion or cancellation.

स्थिति	विवरण
activated	TWAP order has been created and is actively executing
finished	TWAP order completed successfully (entire size executed)
terminated	TWAP order was cancelled before completion (partial execution possible)

Example Records

Activated TWAP Order

{
  "time": "2025-12-04T17:00:22.417074898",
  "twap_id": 1430699,
  "state": {
    "coin": "HYPE",
    "user": "0x9d6a5ab97a8eed617bde9968d9ab6fcf72fde1b8",
    "side": "A",
    "sz": "108.36",
    "executedSz": "0.0",
    "executedNtl": "0.0",
    "minutes": 10,
    "reduceOnly": false,
    "randomize": false,
    "timestamp": 1764867622417
  },
  "status": "activated"
}

Finished TWAP Order

{
  "time": "2025-12-04T17:00:39.012600357",
  "twap_id": 1430683,
  "state": {
    "coin": "xyz:NVDA",
    "user": "0x130506ec2875c51eaf6fa2632ee952205a3dd793",
    "side": "A",
    "sz": "1.0",
    "executedSz": "1.0",
    "executedNtl": "183.83588",
    "minutes": 5,
    "reduceOnly": false,
    "randomize": false,
    "timestamp": 1764867337234
  },
  "status": "finished"
}

Terminated TWAP Order (Partially Executed)

{
  "time": "2025-12-04T17:05:55.357168702",
  "twap_id": 1430645,
  "state": {
    "coin": "HYPE",
    "user": "0xdce7148dd9418e01129192095954a5ad3d75b0cc",
    "side": "B",
    "sz": "100.59",
    "executedSz": "25.94",
    "executedNtl": "897.98844",
    "minutes": 120,
    "reduceOnly": false,
    "randomize": true,
    "timestamp": 1764866098571
  },
  "status": "terminated"
}

Long Duration TWAP (210 minutes)

{
  "time": "2025-12-04T17:03:28.969809817",
  "twap_id": 1430703,
  "state": {
    "coin": "xyz:NVDA",
    "user": "0xa993ad31ef46873c0193448dbb2f04c0d3854731",
    "side": "B",
    "sz": "27.11",
    "executedSz": "0.0",
    "executedNtl": "0.0",
    "minutes": 210,
    "reduceOnly": false,
    "randomize": false,
    "timestamp": 1764867808969
  },
  "status": "activated"
}

Outcome Market TWAP (HIP-4)

Outcome assets (HIP-4) appear as #N-prefixed coins in TWAP records. The structure is identical to standard TWAPs.

{
  "time": "2026-05-02T10:55:26.396453316",
  "twap_id": 1783904,
  "state": {
    "coin": "#0",
    "user": "0x81a39aa0b0d6fa8513aa79929e7c01dfaa232fce",
    "side": "B",
    "sz": "10000.0",
    "executedSz": "0.0",
    "executedNtl": "0.0",
    "minutes": 5,
    "reduceOnly": false,
    "randomize": false,
    "timestamp": 1777719326396
  },
  "status": "activated"
}

API Usage

gRPC Streaming

// Subscribe to TWAP updates
const request = {
  subscribe: {
    stream_type: 'TWAP',
    filters: {
      user: { values: ['0x123...'] },
      coin: { values: ['BTC', 'ETH'] },
      status: { values: ['activated', 'finished'] }
    }
  }
};

JSON-RPC

# Get latest TWAP 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": "twap",
      "count": 10
    },
    "id": 1
  }'

WebSocket

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

Important Notes

• Sparse Data: Most blocks have empty event arrays - TWAP updates only occur when orders are created, completed, or cancelled
• TWAP ID Linking: The twap_id field can be used to correlate with individual fills in the Trades dataset (where twapId field references this twap_id)
• Execution Progress: Compare executedSz को sz to determine completion percentage
• Randomization: When randomize is true, order execution timing is randomized to avoid predictable patterns
• Reduce-Only Orders: When reduceOnly is true, the TWAP order can only reduce existing positions
• Duration Range: TWAP orders can range from very short (5 minutes) to very long (210+ minutes or 3.5+ hours)
• Partial Execution: Terminated orders may have partial execution (non-zero executedSz less than sz)

Related Streams

• Trades - View individual fills that comprise TWAP execution (matching twapId field)
• Orders - See the individual child orders created by TWAP algorithm
• Events - Monitor system events that may affect TWAP execution