A concise reference on API latency, per-IP limits, safe client shutdown, and telemetry. It contains no key-storage designs, process-specific configurations, scaling recipes, or strategy launch checklists.
TL;DR
- Measure latency to the HL API from the intended deployment region. Values differ noticeably between regions and change over time.
- Limits for user-specific WebSocket subscriptions are counted per IP, not per connection. A new connection from the same IP does not create a separate pool.
- Before shutting down a client, stop new writes and confirm from exchange data that its open orders have been cancelled. The application defines the exact timeouts and position policy.
- Telemetry must account separately for REST weight, 429 responses, and WebSocket subscription errors.
1. Latency and per-IP limits
1.1. API latency
End-to-end API requests and pings can differ severalfold between regions. Check latency from the intended deployment region instead of carrying an old measurement into a new environment.
1.2. Known limits
The measurements are from 2026-07; HL limits change.
| Limit | Value | Confidence |
|---|---|---|
| REST weight | 1200/min per IP | documented; details in rate-limits.md |
| WS subscriptions | about 1000 per IP | empirical reference point, not an official contract |
| WS connections per IP | later notes: 10; earlier note: 100 | conflicting notes; verify against current documentation |
| Unique addresses in user-specific WS subscriptions | documented: 10; measured: about 20 in total across all connections of one IP | empirical measurement on 2026-07-17 |
The following was verified for user-specific subscriptions:
- the common pool belongs to the IP, not to an individual WebSocket connection;
- moving a subscription to another connection on the same IP can leave the old slot occupied for about 60 seconds;
unsubscribeon the same connection released the slot immediately;- a rejection may arrive only on the error channel, so it must be handled explicitly;
- a single initial snapshot does not prove that a subscription remains healthy; include subsequent push messages in measurements.
These facts describe API behavior, but do not prescribe a sharding architecture or an address count for a particular application.
2. Safe client shutdown
Universal invariant for a client that leaves resting orders:
- stop accepting and creating new write actions;
- wait for already submitted actions to finish, or mark their outcome as unknown;
- request current open orders from the exchange;
- cancel the orders owned by the client and confirm the result with another read;
- if cleanup cannot be confirmed, exit with an explicit error instead of reporting a successful shutdown.
Whether to close a position during shutdown is a separate application policy. A kill switch or write-disabled mode does not close an already open position by itself.
3. API telemetry
Minimally useful signals:
- REST weight over a sliding window relative to the 1200-per-IP limit;
- count and share of 429 responses;
- WebSocket reconnects and closes with code 1008;
- errors from the WebSocket error channel;
- divergence between locally expected open orders and open orders read from the exchange.
The per-minute weight of a periodic request is request weight × 60,000 / interval_ms. Intervals and limit headroom must be explicit application configuration: there are no universally safe values for every workload. Weight tables and userRateLimit rules are in rate-limits.md.
4. Open questions / not verified
- Documentation stated 10 tracked user-specific addresses per IP, while a 2026-07 measurement yielded about 20 in total across all connections. Verify again before calculating capacity.
- Notes on the WebSocket connection limit conflict: 10 versus 100. Until rechecked, this is not a reliable design input.
- The exact per-minute limit for outgoing WebSocket messages is not recorded here.
Knowledge snapshot: 2026-09; dates of individual checks are in the text. The HL API changes—verify limits and response shapes again.
© markpaper authors. Licensed under CC BY 4.0: when publishing or adapting the material, credit “markpaper — Hyperliquid knowledge base” and link to the original and the license.