Hyperliquid Realtime Monitor

Real-time cryptocurrency wallet data streaming API powered by Hyperliquid. Stream live wallet updates including futures positions, spot balances, open orders, and account metrics for any Hyperliquid wallet address.

🚀 Overview

This Standby-only Actor provides real-time access to Hyperliquid wallet data. Simply provide a wallet address, and this Actor will stream real-time updates for that wallet's trading activity, positions, and balances.

The service operates as a lightweight, always-on web server delivering instant wallet updates via Server-Sent Events (SSE).

✨ Key Features

• 🔄 Apify Standby Mode: Always-on, fast-responding web server
• 🔴 Real-Time Event Streaming: Instant delivery via Server-Sent Events (SSE)
• 👛 Wallet Monitoring: Track any Hyperliquid wallet address
• 📊 Comprehensive Data:
  • Futures wallet (positions, margin, PnL)
  • Spot wallet (balances, holdings)
  • Open orders and TWAP states
  • Account metrics (cumulative ledger, vault info)
• ⚡ High Performance: Sub-second event delivery optimized for Standby mode
• 💪 Multi-Client Scalable: Connection pooling for same wallets, each client receives only their subscribed data
• 🔌 Smart Connection Pooling: Multiple clients watching the same wallet share a single upstream connection

🌐 Available Endpoints

Endpoint	Description	Use Case
/events/hyperliquid/wallet	Wallet data updates	Real-time wallet monitoring
/health	Service health check	Monitor service status

🔧 Quick Start

Standby Mode Only

This Actor only works in Standby mode. It cannot be run in normal mode.

🎯 How to Use

1. Get Wallet Address: Obtain the Hyperliquid wallet address you want to monitor (must start with 0x and be 42 characters long)
2. Stream Data: Pass this address as the wallet_address parameter to the /events/hyperliquid/wallet endpoint

Basic Usage Examples

# Monitor a specific wallet
curl -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
     -N "https://muhammetakkurtt--hyperliquid-realtime-position-monitor.apify.actor/events/hyperliquid/wallet?wallet_address=0x5b5d51203a0f9079f8aeb098a6523a13f298c060"

# Check service health
curl -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
     "https://muhammetakkurtt--hyperliquid-realtime-position-monitor.apify.actor/health"

Wallet Address Format

The wallet address must follow these requirements:

• Start with 0x: All Ethereum-compatible addresses begin with 0x
• 42 characters total: 0x prefix + 40 hexadecimal characters
• Valid hex characters: Only 0-9 and a-f (case-insensitive)

Valid examples:

• 0x5b5d51203a0f9079f8aeb098a6523a13f298c060
• 0xABCDEF1234567890ABCDEF1234567890ABCDEF12

Invalid examples:

• 5b5d51203a0f9079f8aeb098a6523a13f298c060 (missing 0x prefix)
• 0x5b5d51203a0f9079f8aeb098a6523a13f298c0 (too short)
• 0xGHIJKL... (invalid hex characters)

🔍 Health Monitoring

Health Endpoint Response

{
  "status": "ok",
  "timestamp": "2026-01-20T00:00:00.000Z",
  "connections": {
    "total": 5,
    "unique_wallets": 2,
    "by_wallet": {
      "0x5b5d51203a0f9079f8aeb098a6523a13f298c060": 3,
      "0xabcdef1234567890abcdef1234567890abcdef12": 2
    }
  },
  "messages_processed": 12500
}

📊 Event Data Structure

Each SSE event contains a JSON object with the real-time wallet data:

{
    "data": {
        "futures_wallet": {
            "marginSummary": {
                "accountValue": "41189807.8065249994",
                "totalNtlPos": "99443683.9535219967",
                "totalRawUsd": "140633491.7600469887",
                "totalMarginUsed": "12486232.7771869991"
            },
            "crossMarginSummary": {
                "accountValue": "41189807.8065249994",
                "totalNtlPos": "99443683.9535219967",
                "totalRawUsd": "140633491.7600469887",
                "totalMarginUsed": "12486232.7771869991"
            },
            "crossMaintenanceMarginUsed": "3466971.0827370002",
            "withdrawable": "28119890.2815879993",
            "assetPositions": [
                {
                    "type": "oneWay",
                    "position": {
                        "coin": "BTC",
                        "szi": "-131.31825",
                        "leverage": {
                            "type": "cross",
                            "value": 10
                        },
                        "entryPx": "91332.8",
                        "positionValue": "12207607.1565000005",
                        "unrealizedPnl": "-213937.220574",
                        "returnOnEquity": "-0.178375111",
                        "liquidationPx": "376678.2594701097",
                        "marginUsed": "1220760.7156499999",
                        "maxLeverage": 40,
                        "cumFunding": {
                            "allTime": "-16025402.4860759992",
                            "sinceOpen": "-16025402.4860759992",
                            "sinceChange": "-23231.089857"
                        }
                    }
                },
                {
                    "type": "oneWay",
                    "position": {
                        "coin": "ETH",
                        "szi": "-13296.8347",
                        "leverage": {
                            "type": "cross",
                            "value": 10
                        },
                        "entryPx": "3240.32",
                        "positionValue": "42672201.9192399979",
                        "unrealizedPnl": "413926.759716",
                        "returnOnEquity": "0.0960696104",
                        "liquidationPx": "5990.5516594754",
                        "marginUsed": "4267220.1919240002",
                        "maxLeverage": 25,
                        "cumFunding": {
                            "allTime": "-14051243.2001499999",
                            "sinceOpen": "-14051243.2001499999",
                            "sinceChange": "-10150.205651"
                        }
                    }
                },
                {
                    "type": "oneWay",
                    "position": {
                        "coin": "SOL",
                        "szi": "-5184.85",
                        "leverage": {
                            "type": "cross",
                            "value": 10
                        },
                        "entryPx": "132.887",
                        "positionValue": "694821.7485",
                        "unrealizedPnl": "-5822.420297",
                        "returnOnEquity": "-0.0845054568",
                        "liquidationPx": "7232.1454398685",
                        "marginUsed": "69482.17485",
                        "maxLeverage": 20,
                        "cumFunding": {
                            "allTime": "-2693983.481987",
                            "sinceOpen": "-2693983.481987",
                            "sinceChange": "-379.393821"
                        }
                    }
                },
                {
                    "type": "oneWay",
                    "position": {
                        "coin": "INJ",
                        "szi": "-36877.3",
                        "leverage": {
                            "type": "cross",
                            "value": 3
                        },
                        "entryPx": "13.05957",
                        "positionValue": "176255.05535",
                        "unrealizedPnl": "305346.70125",
                        "returnOnEquity": "1.9020696897",
                        "liquidationPx": "938.1949065958",
                        "marginUsed": "58751.685116",
                        "maxLeverage": 10,
                        "cumFunding": {
                            "allTime": "242.195908",
                            "sinceOpen": "242.195908",
                            "sinceChange": "1215.245571"
                        }
                    }
                },
                {
                    "type": "oneWay",
                    "position": {
                        "coin": "SUI",
                        "szi": "-0.5",
                        "leverage": {
                            "type": "cross",
                            "value": 10
                        },
                        "entryPx": "3.67761",
                        "positionValue": "0.7849",
                        "unrealizedPnl": "1.053906",
                        "returnOnEquity": "5.7314692251",
                        "liquidationPx": "70405159.1780599952",
                        "marginUsed": "0.07849",
                        "maxLeverage": 10,
                        "cumFunding": {
                            "allTime": "-120714.036345",
                            "sinceOpen": "-120714.036345",
                            "sinceChange": "-0.007054"
                        }
                    }
                },
                {
                    "type": "oneWay",
                    "position": {
                        "coin": "XRP",
                        "szi": "-5850010.0",
                        "leverage": {
                            "type": "cross",
                            "value": 20
                        },
                        "entryPx": "1.901026",
                        "positionValue": "11673694.9550000001",
                        "unrealizedPnl": "-552671.8955",
                        "returnOnEquity": "-0.9939227579",
                        "liquidationPx": "8.2520614418",
                        "marginUsed": "583684.74775",
                        "maxLeverage": 20,
                        "cumFunding": {
                            "allTime": "-77372.937614",
                            "sinceOpen": "-77372.937614",
                            "sinceChange": "-77431.141518"
                        }
                    }
                },
                {
                    "type": "oneWay",
                    "position": {
                        "coin": "HYPE",
                        "szi": "-1298703.8899999999",
                        "leverage": {
                            "type": "cross",
                            "value": 5
                        },
                        "entryPx": "42.0004",
                        "positionValue": "30839022.5719400011",
                        "unrealizedPnl": "23707087.2365880013",
                        "returnOnEquity": "2.1731235573",
                        "liquidationPx": "50.1519330189",
                        "marginUsed": "6167804.5143879997",
                        "maxLeverage": 5,
                        "cumFunding": {
                            "allTime": "-6131529.6742280005",
                            "sinceOpen": "-6131529.6742280005",
                            "sinceChange": "-455664.357409"
                        }
                    }
                },
                {
                    "type": "oneWay",
                    "position": {
                        "coin": "FARTCOIN",
                        "szi": "-3637827.7000000002",
                        "leverage": {
                            "type": "cross",
                            "value": 10
                        },
                        "entryPx": "0.6115",
                        "positionValue": "1174872.833992",
                        "unrealizedPnl": "1049670.8911009999",
                        "returnOnEquity": "4.7185896113",
                        "liquidationPx": "9.9850931266",
                        "marginUsed": "117487.283399",
                        "maxLeverage": 10,
                        "cumFunding": {
                            "allTime": "-204277.78926",
                            "sinceOpen": "-189502.824389",
                            "sinceChange": "-32835.971663"
                        }
                    }
                },
                {
                    "type": "oneWay",
                    "position": {
                        "coin": "PUMP",
                        "szi": "-2022108.0",
                        "leverage": {
                            "type": "cross",
                            "value": 5
                        },
                        "entryPx": "0.006521",
                        "positionValue": "5206.9281",
                        "unrealizedPnl": "7980.410854",
                        "returnOnEquity": "3.025785142",
                        "liquidationPx": "17.4113099248",
                        "marginUsed": "1041.38562",
                        "maxLeverage": 10,
                        "cumFunding": {
                            "allTime": "-254446.385589",
                            "sinceOpen": "-254446.385589",
                            "sinceChange": "-71.009778"
                        }
                    }
                }
            ],
            "time": 1768861336374
        },
        "spot_wallet": {
            "balances": [
                {
                    "coin": "USDC",
                    "token": 0,
                    "total": "99985.60216063",
                    "hold": "0.0",
                    "entryNtl": "0.0"
                },
                {
                    "coin": "HYPE",
                    "token": 150,
                    "total": "1196889.7221968099",
                    "hold": "0.0",
                    "entryNtl": "41392211.95883324"
                },
                {
                    "coin": "UBTC",
                    "token": 197,
                    "total": "0.0",
                    "hold": "0.0",
                    "entryNtl": "0.0"
                },
                {
                    "coin": "LATINA",
                    "token": 223,
                    "total": "45658.0657",
                    "hold": "0.0",
                    "entryNtl": "0.0"
                },
                {
                    "coin": "FUND",
                    "token": 232,
                    "total": "18.69",
                    "hold": "0.0",
                    "entryNtl": "14.0446005"
                },
                {
                    "coin": "USDT0",
                    "token": 268,
                    "total": "7.99944001",
                    "hold": "0.0",
                    "entryNtl": "8.01251937"
                },
                {
                    "coin": "UFART",
                    "token": 269,
                    "total": "3712110.7959690001",
                    "hold": "0.0",
                    "entryNtl": "2272336.2559538898"
                },
                {
                    "coin": "UPUMP",
                    "token": 299,
                    "total": "4014.188103",
                    "hold": "0.0",
                    "entryNtl": "11.81897403"
                },
                {
                    "coin": "LICKO",
                    "token": 307,
                    "total": "35585.49249208",
                    "hold": "0.0",
                    "entryNtl": "0.21351295"
                },
                {
                    "coin": "UBONK",
                    "token": 320,
                    "total": "2331863.8051100001",
                    "hold": "0.0",
                    "entryNtl": "21.06872538"
                },
                {
                    "coin": "USDH",
                    "token": 360,
                    "total": "0.01001646",
                    "hold": "0.0",
                    "entryNtl": "0.01001723"
                }
            ]
        },
        "user": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
        "agentAddress": "0xccc011fe21055a3fb9ef7fca21456d0763233509",
        "agentValidUntil": 1770016215929,
        "cumLedger": "-73365442.3100000024",
        "isVault": false,
        "leadingVaults": [],
        "totalVaultEquity": "0.0",
        "openOrders": [],
        "twapStates": []
    },
    "event_type": "wallet_data",
    "timestamp": "2026-01-19T22:22:17.063Z"
}

Data Fields Explanation

Futures Wallet (futures_wallet)

• marginSummary: Account value, positions, and margin usage
• assetPositions: Array of open futures positions with details:
  • Position size, entry price, unrealized PnL
  • Leverage settings and liquidation price
  • Cumulative funding payments

Spot Wallet (spot_wallet)

• balances: Array of spot token balances:
  • Total balance and amount on hold
  • Entry notional value

Account Info

• user: Wallet address
• cumLedger: Cumulative ledger balance
• isVault: Whether the account is a vault
• openOrders: Active orders
• twapStates: Time-weighted average price states

🚨 Connection Management

Connection Features

• Auto-reconnection: Automatic recovery from disconnects
• Connection cleanup: Removal of inactive clients
• Graceful shutdown: Clean disconnect notifications
• Connection Pooling: Clients watching the same wallet share a single upstream connection
• Wallet-Based Routing: Each client only receives data for their subscribed wallet address

Multi-Client Architecture

• Multiple clients can connect simultaneously with different wallet addresses
• Clients watching the same wallet share an upstream connection

Connection Event Types

Successful Connection:

event: connected
data: {"message":"Connected to wallet endpoint","connection_id":"conn_xxx","endpoint":"wallet","wallet_address":"0x5b5d51203a0f9079f8aeb098a6523a13f298c060"}

Ping/Keep-alive:

event: ping
data: {"ping":"alive"}

Server Shutdown:

event: shutdown
data: {"message":"Server shutting down"}

🎯 Use Cases

💹 Trading & Portfolio Management

• Real-Time Position Monitoring: Track live futures positions and PnL
• Balance Tracking: Monitor spot wallet balances across tokens
• Margin Monitoring: Keep track of margin usage and liquidation risk
• Order Management: Watch open orders and execution

📊 Analytics & Research

• Wallet Analysis: Study trading patterns and strategies
• Performance Tracking: Build historical performance databases
• Risk Management: Monitor leverage and exposure

🔔 Monitoring & Alerts

• Position Alerts: Trigger notifications on position changes
• Balance Alerts: Get notified on balance movements
• Liquidation Warnings: Alert on approaching liquidation prices
• Dashboard Integration: Feed real-time data to monitoring dashboards

🛠️ Development & Integration

• Trading Bots: Integrate live wallet data into trading algorithms
• Portfolio Trackers: Build live portfolio monitoring tools
• Risk Management Systems: Power risk monitoring with real-time data