Skip to main content

​
HTTP responses

Request-Id identifies the HTTP request. Authenticated API responses are not cacheable.

​
Idempotency

Send an Idempotency-Key header containing 8–128 printable ASCII characters on every trading mutation. Choose one key per logical action. The key is scoped to the API credential. Reusing it with the same parameters returns the recorded result; changing parameters returns 409. A timeout is not proof that a trade failed. Retry the same action with the same idempotency key. Never submit a replacement under a new key simply because the original response was lost. Switching API credentials also changes the idempotency namespace. For orders, retrieve the returned order UUID to reconcile an unknown result against Hyperliquid. An unknown exchange order ID is not proof of nonexecution. An unresolved mutation of the same order blocks another mutation of that order. Unrelated orders and commands may proceed with their own idempotency keys. For leverage, margin, and TWAP actions, retrieve the operation UUID. An unknown operation remains unknown unless its execution result is known; a retrieval does not replay the action. Inspect the account’s exchange state before deciding on a separate action. There is no automatic retry of signed exchange writes. A confirmed single-attempt HTTP 429 or local pre-dispatch rejection permits retry with the same idempotency key after the indicated delay. Transport timeouts and lost responses do not get this treatment.

​
Order statuses

open, waiting_for_trigger, filled, canceled, rejected, and unknown describe the order resource. Unknown fill amounts or average prices are null, not zero. A rejected modification can also cancel the original order at Hyperliquid. Legend reconciles the original order and sets its error field; if reconciliation is unavailable, its status is unknown. Read fills for execution details; order status alone does not provide a complete fill history.