API docs by Redocly

Hyperliquid Unified API (0.1.0)

Download OpenAPI specification:

License: MIT

Consolidated OpenAPI 3.1 schema for Hyperliquid REST and WebSocket APIs.

  • POST /info: Multiplexed info endpoint using type discriminator
  • POST /exchange: Trading operations using action.type discriminator
  • GET /ws: WebSocket entrypoint for real-time subscriptions

Multiplexed info endpoint

A single endpoint that serves many read-only queries distinguished by a type field in the JSON body. This operation uses a discriminator on the type property to pick the appropriate request schema. Responses vary by request type.

Valid type values and purposes:

  • allMids: Return mid prices for all actively traded coins. If a book is empty, last trade price is used.
  • openOrders: Retrieve a user's open orders.
  • frontendOpenOrders: Retrieve a user's open orders with additional frontend fields.
  • userFills: Retrieve a user's most recent trade fills (up to 2,000).
  • userFillsByTime: Retrieve a user's trade fills within a time range (up to 2,000 per response).
  • userRateLimit: Return the user's current rate-limit usage and capacity.
  • orderStatus: Query order status by numeric order ID or client order ID (cloid).
  • l2Book: Retrieve an L2 order book snapshot for a given coin (up to 20 levels per side).
  • candleSnapshot: Retrieve OHLCV candles for a coin and interval (most recent 5,000).
  • portfolio: Retrieve summarized portfolio time-series across intervals.
  • spotMeta: Retrieve spot token metadata and spot universe definitions.
  • spotMetaAndAssetCtxs: Retrieve spot metadata and per-asset pricing contexts.
  • spotClearinghouseState: Retrieve a user's spot balances and totals.
  • meta: Retrieve perpetuals metadata including universe and margin tables.
  • metaAndAssetCtxs: Retrieve perps universe and per-asset contexts (funding, OI, prices).
  • clearinghouseState: Retrieve a user's perps clearinghouse account state and summaries.
  • gossipRootIps: Retrieve recently available seed peer IP addresses to bootstrap gossip.
Request Body schema: application/json
required
type
required
string

Responses

Request samples

Content type
application/json
Example
{
  • "type": "allMids"
}

Response samples

Content type
application/json
Example
{
  • "property1": "string",
  • "property2": "string"
}

Trading operations based on action

All trading operations use POST /exchange with different action.type variants.

Common request structure:

  • action: Operation-specific object
  • nonce: Timestamp in milliseconds
  • signature: Cryptographic signature
  • vaultAddress: Optional, for vault trading
  • expiresAfter: Optional expiration timestamp
Request Body schema: application/json
required
required
any (Trading Action)

Choose one of the following actions via the type discriminator:

  • order: Place a new order (limit/trigger)
  • cancel: Cancel by order id
  • cancelByCloid: Cancel by client order id
  • scheduleCancel: Schedule a cancel-all operation at a future time.
  • modify: Modify an existing order
  • batchModify: Modify multiple orders
  • updateLeverage: Update cross or isolated leverage on a coin.
  • updateIsolatedMargin: Add or remove margin from isolated position
  • usdSend: Send usd to another address. This transfer does not touch the EVM bridge. The signature format is human readable for wallet interfaces.
  • spotSend: Send spot assets to another address. This transfer does not touch the EVM bridge. The signature format is human readable for wallet interfaces.
  • withdraw3: This method is used to initiate the withdrawal flow. After making this request, the L1 validators will sign and send the withdrawal request to the bridge contract. There is a $1 fee for withdrawing at the time of this writing and withdrawals take approximately 5 minutes to finalize.
  • usdClassTransfer: This method is used to transfer USDC from the user's spot wallet to perp wallet and vice versa.
  • sendAsset: (testnet only) This generalized method is used to transfer tokens between different perp DEXs, spot balance, users, and/or sub-accounts. Use "" to specify the default USDC perp DEX and "spot" to specify spot. Only the collateral token can be transferred to or from a perp DEX.
  • cDeposit: This method is used to transfer native token from the user's spot account into staking for delegating to validators.
  • cWithdraw: This method is used to transfer native token from staking into the user's spot account. Note that transfers from staking to spot account go through a 7 day unstaking queue.
  • tokenDelegate: Delegate or undelegate native tokens to or from a validator. Note that delegations to a particular validator have a lockup duration of 1 day.
  • vaultTransfer: Add or remove funds from a vault.
  • approveAgent: Approves an API Wallet (also sometimes referred to as an Agent Wallet).
  • approveBuilderFee: Approve a maximum fee rate for a builder.
  • twapOrder: Place a TWAP order
  • twapCancel: Cancel a TWAP order
  • reserveRequestWeight: Instead of trading to increase the address based rate limits, this action allows reserving additional actions for 0.0005 USDC per request. The cost is paid from the Perps balance.
  • noop: Invalidate Pending Nonce
nonce
required
integer

Current timestamp in milliseconds

signature
required
object

Cryptographic signature

vaultAddress
string

Vault address for vault trading

expiresAfter
integer

Request expiration timestamp

Responses

Request samples

Content type
application/json
{
  • "action": {
    },
  • "nonce": 0,
  • "signature": { },
  • "vaultAddress": "string",
  • "expiresAfter": 0
}

Response samples

Content type
application/json
{
  • "status": "err",
  • "response": "string"
}

WebSocket Connection

Establish WebSocket connection for real-time data streaming.

Subscribe by sending JSON messages like: { "method": "subscribe", "subscription": { "type": "...", ... } }

Then the server responds with subscriptionResponse and streams updates on the corresponding channel.

Responses