> ## Documentation Index
> Fetch the complete documentation index at: https://docs.legend.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Respect Legend admission and Hyperliquid request capacity.

Legend applies request throttling across API instances, per API credential, and per exchange account. These controls do not impose financial trading budgets.

## Hyperliquid limits

Hyperliquid documents a shared REST limit of 1,200 weight per minute per IP. Exchange requests cost `1 + floor(batch_length / 40)`; address-based limits count each batched action separately. `orderStatus` and clearinghouse-state reads cost 2; metadata reads generally cost 20. Some history reads also charge according to response size.

Address allowance is venue-managed. Exhausted addresses normally receive one action every ten seconds; cancellations have a larger allowance. See [Hyperliquid’s rate-limit documentation](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/rate-limits-and-user-limits) for the authoritative rules and congestion limits.

## Legend behavior

* A shared PostgreSQL rolling window allows 1,000 ordinary request weight and reserves another 100 for cancellations. Cancellation prerequisite reads can use that reserve.
* Market metadata is cached for 60 seconds per API process, and concurrent identical reads are coalesced within that process. New instances can still need fresh metadata reads.
* Address allowance is shared per account and refreshed from Hyperliquid every 10 seconds as needed. Each submitted action conservatively reserves five address units because expired actions can consume five times the normal allowance.
* The current per-key API throttle is 120 requests per minute.
* Exhaustion returns `429` with `Retry-After` in seconds. A confirmed upstream HTTP `429` activates a shared cooldown. Signed writes are not automatically retried or placed in an unbounded queue.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Cache-Control: no-store
```

Wait for `Retry-After`, then retry the same logical action with the same idempotency key. Use bounded backoff and jitter when multiple clients resume together.

Other services sharing an outbound IP and other tools trading the same account can consume exchange capacity. Headroom cannot guarantee that Hyperliquid never returns `429`; both admission and explicit rejection handling are required.

## Request cost examples

A Legend API request may make several Hyperliquid requests. With warm metadata and account-allowance caches, placing one order costs one exchange weight. A cold native-perpetual order can cost 41 weight: 20 for metadata, 20 for account allowance, and one for the order. HIP-3 resolution can require another 20-weight DEX metadata read.

With the current native and XYZ DEX coverage, reading balances costs six weight, reading positions costs four, and listing current open orders costs 40. Filtering positions or open orders to one DEX reduces those costs to two or 20 respectively. Each additional supported DEX adds two weight to balances/positions and 20 to open orders. Stored fills are read from Legend’s index. Polling, cold starts, and the number of active accounts affect throughput; 1,000 weight is not a promise of 1,000 order submissions per minute.

A new API key does not create a new Hyperliquid address allowance. The UI and other tools using the same account share that allowance. The same applies to REST IP capacity for services sharing egress. This API does not open a WebSocket connection per API key.