knowledge/hl/ops-and-deploy.md
vregistry-c914171 · 4.4 KB
# Hyperliquid — API operational facts
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](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;
- `unsubscribe` on 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:
1. stop accepting and creating new write actions;
2. wait for already submitted actions to finish, or mark their outcome as unknown;
3. request current open orders from the exchange;
4. cancel the orders owned by the client and confirm the result with another read;
5. 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](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.
---
<!-- license-footer -->
_© markpaper authors. Licensed under [CC BY 4.0](LICENSE.md): when publishing or adapting the material, credit “markpaper — Hyperliquid knowledge base” and link to the original and the license._