概覽
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
| 領域 | 類型 | 說明 |
|---|---|---|
| 時間 | 字串 | 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
| 領域 | 類型 | 說明 |
|---|---|---|
| 硬幣 | 字串 | 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 |
| 時間戳記 | 整數 | 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_idfield can be used to correlate with individual fills in the Trades dataset (wheretwapIdfield references thistwap_id) - Execution Progress: Compare
executedSz至szto determine completion percentage - Randomization: When
randomize是true, order execution timing is randomized to avoid predictable patterns - Reduce-Only Orders: When
reduceOnly是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
executedSzless thansz)