Spot

Dedicated endpoints for spot market metadata and user token states.

Accesses complete metadata and real-time market contexts for the spot exchange, including token indices and internal asset identifiers. Provides detailed visibility into user-specific token balances and the status of ongoing asset deployment auctions on the Hyperliquid L1.

Retrieve spot metadata

POST /external/info

Returns a comprehensive list of all tradable spot tokens and trading pairs currently available on the exchange. It provides essential asset metadata, including decimal precision, internal token indices, and unique onchain identifiers required for accurate order placement and balance tracking.

Headers

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

Request Body

Name	Type	Description
type	String	"spotMeta"

Response

{
    "tokens": [
        {
            "name": "USDC",
            "szDecimals": 8,
            "weiDecimals" 8,
            "index": 0,
            "tokenId": "0x6d1e7cde53ba9467b783cb7c530ce054",
            "isCanonical": true,
            "evmContract":null,
            "fullName":null
        },
        {
            "name": "PURR",
            "szDecimals": 0,
            "weiDecimals": 5,
            "index": 1,
            "tokenId": "0xc1fb593aeffbeb02f85e0308e9956a90",
            "isCanonical": true,
            "evmContract":null,
            "fullName":null
        },
        {
            "name": "HFUN",
            "szDecimals": 2,
            "weiDecimals": 8,
            "index": 2,
            "tokenId": "0xbaf265ef389da684513d98d68edf4eae",
            "isCanonical": false,
            "evmContract":null,
            "fullName":null
        },
    ],
    "universe": [
        {
            "name": "PURR/USDC",
            "tokens": [1, 0],
            "index": 0,
            "isCanonical": true
        },
        {
            "tokens": [2, 0],
            "name": "@1",
            "index": 1,
            "isCanonical": false
        },
    ]
}

---

Retrieve a user's token balances

POST /external/info

Returns a comprehensive list of a user's spot token holdings, detailing total balances alongside amounts currently reserved for open orders. Provides technical metadata such as internal token indices and entry notional values to enable accurate cost-basis tracking and portfolio management.

Headers

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

Request Body

Name	Type	Description
type	String	"spotClearinghouseState"
user	String	Onchain address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000.

Response

{
    "balances": [
        {
            "coin": "USDC",
            "token": 0,
            "hold": "0.0",
            "total": "14.625485",
            "entryNtl": "0.0"
        },
        {
            "coin": "PURR",
            "token": 1,
            "hold": "0",
            "total": "2000",
            "entryNtl": "1234.56",
        }
    ]
}

---

Retrieve information about the Spot Deploy Auction

POST /external/info

Returns the current state of the Dutch auction used for permissionless spot token deployment on the Hyperliquid L1. This data provides real-time visibility into the auction's timing, current gas cost in HYPE or USDC, and the per-token genesis configurations for upcoming spot listings.

Headers

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

Request Body

Name	Type	Description
type	String	"spotDeployState"
user	String	Onchain address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000.

Response

{
  "states": [
    {
      "token": 150,
      "spec" : {
        "name": "HYPE",
        "szDecimals": 2,
        "weiDecimals": 8,
      },
      "fullName": "Hyperliquid",
      "spots": [107],
      "maxSupply": 1000000000,
      "hyperliquidityGenesisBalance": "120000",
      "totalGenesisBalanceWei": "100000000000000000",
      "userGenesisBalances": [
        ("0xdddddddddddddddddddddddddddddddddddddddd", "428,062,211")...
      ],
      "existingTokenGenesisBalances": [
        (1, "0")...
      ]
    }
  ],
  "gasAuction": {
    "startTimeSeconds": 1733929200,
    "durationSeconds": 111600,
    "startGas": "181305.90046",
    "currentGas": null,
    "endGas": "181291.247358"
  }
}