# Hyperliquid Info Endpoints

{% hint style="info" %}
These endpoints support much higher rate limits.
{% endhint %}

The Info Endpoints allow you to query the state of the Hyperliquid exchange, specific user accounts, and validator information. Unlike exchange endpoints, these are read-only and do not require signed transactions, making them perfect for dashboards and monitoring tools.

Base URL

```
https://ht-api.coinmarketman.com/api
```

### Retrieve a user's open orders <a href="#retrieve-a-users-open-orders" id="retrieve-a-users-open-orders"></a>

`POST`  `/external/info`

*Returns a comprehensive list of all currently active orders for a specified account, allowing for real-time monitoring of pending liquidity on the books. It serves as a vital tool for verifying order IDs, limit prices, and remaining sizes to ensure precise execution of trading strategies.*

Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | "application/json" |

Request Body

| Name           | Type   | Description                                                                                                                                  |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| type           | String | "openOrders"                                                                                                                                 |
| user           | String | Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000.                                                 |
| dex (optional) | String | Perp dex name. Defaults to the empty string which represents the first perp dex. Spot open orders are only included with the first perp dex. |

Response

{% code expandable="true" %}

```
[
    {
        "coin": "BTC",
        "limitPx": "29792.0",
        "oid": 91490942,
        "side": "A",
        "sz": "0.0",
        "timestamp": 1681247412573
    }
]
```

{% endcode %}

***

### Retrieve a user's open orders with additional frontend info <a href="#retrieve-a-users-open-orders-with-additional-frontend-info" id="retrieve-a-users-open-orders-with-additional-frontend-info"></a>

`POST`  `/external/info`

*Provides active orders with expanded metadata like order types and trigger conditions to simplify frontend integration. This dataset offers clear visibility into complex states like Take Profit or Stop Loss triggers not available in standard queries.*

Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | "application/json" |

Request Body

| Name           | Type   | Description                                                                                                                                  |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| type           | String | "frontendOpenOrders"                                                                                                                         |
| user           | String | Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000.                                                 |
| dex (optional) | String | Perp dex name. Defaults to the empty string which represents the first perp dex. Spot open orders are only included with the first perp dex. |

Response

{% code expandable="true" %}

```
[
    {
        "coin": "BTC",
        "isPositionTpsl": false,
        "isTrigger": false,
        "limitPx": "29792.0",
        "oid": 91490942,
        "orderType": "Limit",
        "origSz": "5.0",
        "reduceOnly": false,
        "side": "A",
        "sz": "5.0",
        "timestamp": 1681247412573,
        "triggerCondition": "N/A",
        "triggerPx": "0.0",
    }
]
```

{% endcode %}

***

### Retrieve a user's vault deposits <a href="#retrieve-a-users-vault-deposits" id="retrieve-a-users-vault-deposits"></a>

`POST`  `/external/info`

*Lists all vaults where a user has active deposits alongside the current equity held in each. Facilitates easy tracking of capital allocation and total value locked within specific trading strategies.*

Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | "application/json" |

Request Body

| Name | Type   | Description                                                                                  |
| ---- | ------ | -------------------------------------------------------------------------------------------- |
| type | String | "userVaultEquities"                                                                          |
| user | String | Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000. |

Response

```
[
  {
    "vaultAddress": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303",
    "equity": "742500.082809",
  }
]
```

***

### Retrieve a user's subaccounts <a href="#retrieve-a-users-subaccounts" id="retrieve-a-users-subaccounts"></a>

`POST`  `/external/info`

*Returns a detailed list of all subaccounts associated with a master address, including their individual margin summaries and spot balances. It enables efficient oversight of complex account structures by centralizing the performance and collateral status of every linked sub-entity.*

Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | "application/json" |

Request Body

| Name | Type   | Description                                                                                  |
| ---- | ------ | -------------------------------------------------------------------------------------------- |
| type | String | "subAccounts"                                                                                |
| user | String | Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000. |

Response

{% code expandable="true" %}

```
[
  {
    "name": "Test",
    "subAccountUser": "0x035605fc2f24d65300227189025e90a0d947f16c",
    "master": "0x8c967e73e6b15087c42a10d344cff4c96d877f1d",
    "clearinghouseState": {
      "marginSummary": {
        "accountValue": "29.78001",
        "totalNtlPos": "0.0",
        "totalRawUsd": "29.78001",
        "totalMarginUsed": "0.0"
      },
      "crossMarginSummary": {
        "accountValue": "29.78001",
        "totalNtlPos": "0.0",
        "totalRawUsd": "29.78001",
        "totalMarginUsed": "0.0"
      },
      "crossMaintenanceMarginUsed": "0.0",
      "withdrawable": "29.78001",
      "assetPositions": [],
      "time": 1733968369395
    },
    "spotState": {
      "balances": [
        {
          "coin": "USDC",
          "token": 0,
          "total": "0.22",
          "hold": "0.0",
          "entryNtl": "0.0"
        }
      ]
    }
  }
]
```

{% endcode %}

***

### Query a user's fees

`POST`  `/external/info`

*Retrieves comprehensive details about a user's trading cost structure, including base fee schedules, VIP tiers, and active staking or referral discounts. It also provides a historical breakdown of daily trading volumes and calculates final effective fee rates for both spot and perpetual markets.*

Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | "application/json" |

Request Body

| Name | Type   | Description                                                                                  |
| ---- | ------ | -------------------------------------------------------------------------------------------- |
| type | String | "userFees"                                                                                   |
| user | String | Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000. |

Response

{% code expandable="true" %}

```
{
  "dailyUserVlm": [
    {
      "date": "2025-05-23",
      "userCross": "0.0",
      "userAdd": "0.0",
      "exchange": "2852367.0770729999"
    },
    ...
  ],
  "feeSchedule": {
    "cross": "0.00045",
    "add": "0.00015",
    "spotCross": "0.0007",
    "spotAdd": "0.0004",
    "tiers": {
      "vip": [
        {
          "ntlCutoff": "5000000.0",
          "cross": "0.0004",
          "add": "0.00012",
          "spotCross": "0.0006",
          "spotAdd": "0.0003"
        },
        ...
      ],
      "mm": [
        {
          "makerFractionCutoff": "0.005",
          "add": "-0.00001"
        },
        ...
      ]
    },
    "referralDiscount": "0.04",
    "stakingDiscountTiers": [
      {
        "bpsOfMaxSupply": "0.0",
        "discount": "0.0"
      },
      {
        "bpsOfMaxSupply": "0.0001",
        "discount": "0.05"
      },
      ...
    ]
  },
  "userCrossRate": "0.000315",
  "userAddRate": "0.000105",
  "userSpotCrossRate": "0.00049",
  "userSpotAddRate": "0.00028",
  "activeReferralDiscount": "0.0",
  "trial": null,
  "feeTrialReward": "0.0",
  "nextTrialAvailableTimestamp": null,
  "stakingLink": {
    "type": "tradingUser",
    "stakingUser": "0x54c049d9c7d3c92c2462bf3d28e083f3d6805061"
  },
  "activeStakingDiscount": {
    "bpsOfMaxSupply": "4.7577998927",
    "discount": "0.3"
  }
}
```

{% endcode %}

***

### Query user rate limits <a href="#query-user-rate-limits" id="query-user-rate-limits"></a>

`POST`  `/external/info`

*Provides real-time visibility into an account's API usage, including the total number of requests used against the current capacity. This data allows for precise management of request flow to ensure continuous connectivity and avoid exceeding allocated surplus limits.*

Request Body

| Name | Type   | Description                                                                                  |
| ---- | ------ | -------------------------------------------------------------------------------------------- |
| type | String | "userRateLimit"                                                                              |
| user | String | Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000. |

Response

{% code expandable="true" %}

```
{
  "cumVlm": "2854574.593578",
  "nRequestsUsed": 2890, // max(0, cumulative_used minus reserved)
  "nRequestsCap": 2864574, 
  "nRequestsSurplus": 0, // max(0, reserved minus cumulative_used)
}
```

{% endcode %}

***

### Query a user's staking delegations <a href="#query-a-users-staking-delegations" id="query-a-users-staking-delegations"></a>

`POST`  `/external/info`

*Returns a list of all active staking delegations for a specific user, detailing the validator addresses and the corresponding amount of assets allocated to each. It additionally provides the lockup expiration timestamp, ensuring clear visibility into when staked funds will become available again.*

Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | "application/json" |

Request Body

| Name | Type   | Description                                                                                  |
| ---- | ------ | -------------------------------------------------------------------------------------------- |
| type | String | "delegations"                                                                                |
| user | String | Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000. |

Response

{% code expandable="true" %}

```
[
    {
        "validator":"0x5ac99df645f3414876c816caa18b2d234024b487",
        "amount":"12060.16529862",
        "lockedUntilTimestamp":1735466781353
    },
    ...
]
```

{% endcode %}

***

### Query a user's staking summary <a href="#query-a-users-staking-summary" id="query-a-users-staking-summary"></a>

`POST`  `/external/info`

*Returns a comprehensive overview of a user's staking status, including the total amount currently delegated and any funds that are undelegated. It also tracks pending withdrawals by providing the total amount and the count of withdrawal requests currently in progress.*

Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | "application/json" |

Request Body

| Name | Type   | Description                                                          |
| ---- | ------ | -------------------------------------------------------------------- |
| type | String | "delegatorSummary"                                                   |
| user | String | hexadecimal format; e.g. 0x0000000000000000000000000000000000000000. |

Response

{% code expandable="true" %}

```
{
    "delegated": "12060.16529862",
    "undelegated": "0.0",
    "totalPendingWithdrawal": "0.0",
    "nPendingWithdrawals": 0
}
```

{% endcode %}

***

### Check builder fee approval <a href="#check-builder-fee-approval" id="check-builder-fee-approval"></a>

`POST`  `/external/info`

*Verifies the maximum fee a user has approved for a specific builder, returned in tenths of a basis point. This allows developers to confirm that their platform's fee structure is authorized by the user before executing transactions.*

Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | "application/json" |

Request Body

| Name    | Type   | Description                                                                                  |
| ------- | ------ | -------------------------------------------------------------------------------------------- |
| type    | String | "openOrders"                                                                                 |
| user    | String | Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000. |
| builder | String | Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000. |

Response

{% code expandable="true" %}

```
1 // maximum fee approved in tenths of a basis point i.e. 1 means 0.001%
```

{% endcode %}

***

### Query a user's role <a href="#query-a-users-role" id="query-a-users-role"></a>

`POST`  `/external/info`

*Identifies the specific account classification for an address, distinguishing between standard users, agents, vaults, and subaccounts. This data is essential for verifying account relationships and ensuring your application interacts correctly with the unique permissions assigned to each role.*

Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | "application/json" |

Request Body

| Name | Type   | Description                                                                                  |
| ---- | ------ | -------------------------------------------------------------------------------------------- |
| type | String | "userRole"                                                                                   |
| user | String | Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000. |

{% tabs %}
{% tab title="User" %}

```
{"role":"user"} # "missing", "user", "agent", "vault", or "subAccount"
```

{% endtab %}

{% tab title="Agent" %}

```
{"role":"agent", "data": {"user": "0x..."}}
```

{% endtab %}

{% tab title="Vault" %}

```
{"role":"vault"}
```

{% endtab %}

{% tab title="Subaccount" %}

```
{"role":"subAccount", "data":{"master":"0x..."}}
```

{% endtab %}

{% tab title="Missing" %}

```
{"role":"missing"}
```

{% endtab %}
{% endtabs %}

Response

{% code expandable="true" %}

```
[
  [
    "day",
    {
      "accountValueHistory": [
        [
          1741886630493,
          "0.0"
        ],
        [
          1741895270493,
          "0.0"
        ],
        ...
      ],
      "pnlHistory": [
        [
          1741886630493,
          "0.0"
        ],
        [
          1741895270493,
          "0.0"
        ],
        ...
      ],
      "vlm": "0.0"
    }
  ],
  ["week", { ... }],
  ["month", { ... }],
  ["allTime", { ... }],
  ["perpDay", { ... }],
  ["perpWeek", { ... }],
  ["perpMonth", { ... }],
  ["perpAllTime", { ... }]
]
```

{% endcode %}

***

On the next two pages you find the Info Endpoints that are supported by us specifically for perpetuals and spot data.

For more information you can also see the hyperliquid documentation at <https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint>.&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coinmarketman.com/endpoints/hyperliquid-info-endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.