Rate limits

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 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.
• Each key and each user have a limit of 120 requests per minute. The user limit is shared across all keys and API instances. Creating or replacing a key does not reset it.
• Each user also has 240 work units per minute. An account read or open-order list costs ten units, a positions read costs four, and other reads cost two. A write costs one unit. Connector protocol requests have a separate charge in the same budget.
• A user can have four requests in progress. Cancellations have a separate slot and a reserve of 20 requests per minute when normal capacity is exhausted. These reserves do not override venue limits.
• A user can have five active keys and ten active Legend TWAPs. Uncertain TWAPs count toward this limit until they are resolved. Signed key registration attempts have a limit of ten per hour.
• Public ingress limits each source IP to approximately 5,000 requests over five minutes. Key registration has a separate ceiling of 60 requests over five minutes. This registration ceiling does not include revocation.
• Bodies larger than 16 KiB return 413 without submission.
• 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/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 26 weight, including spot metadata for token valuation, 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.