> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# spotClearinghouseState | Hyperliquid info

> The info endpoint with type: "spotClearinghouseState" retrieves a user's token balances for spot trading on the Hyperliquid exchange.

<Info>
  This method is available on Chainstack. Not all Hyperliquid methods are available on Chainstack, as the open-source node implementation does not support them yet — see [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown.
</Info>

The `info` endpoint with `type: "spotClearinghouseState"` retrieves a user's token balances for spot trading on the Hyperliquid exchange. This endpoint provides detailed information about available balances, held amounts in open orders, and entry notional values for all spot tokens in the user's account.

## Parameters

### Request body

* `type` (string, required) — The request type. Must be `"spotClearinghouseState"` to retrieve user's spot token balances.
* `user` (string, required) — Onchain address in 42-character hexadecimal format (e.g., `0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036`).

## Response

The response contains detailed balance information:

### Balances

An array of the user's spot token balances:

* `coin` (string) — Token symbol (e.g., "USDC", "PURR").
* `token` (integer) — Token index identifier used internally by the exchange.
* `hold` (string) — Amount currently on hold (locked in open orders or pending transactions).
* `total` (string) — Total balance including both available and held amounts.
* `entryNtl` (string) — Entry notional value, used for PnL calculations and tracking cost basis.

### Balance calculation

The available balance for trading can be calculated as:

```
Available Balance = Total - Hold
```

For example, if `total` is "14.625485" and `hold` is "0.0", then the available balance is "14.625485".

## Example request

<CodeGroup>
  ```shell Shell theme={"system"}
  curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"type": "spotClearinghouseState", "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036"}' \
    https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info
  ```

  ```python Python (hyperliquid-python-sdk) theme={"system"}
  from hyperliquid.info import Info

  # skip_ws=True keeps this to a single info HTTP call
  info = Info("YOUR_CHAINSTACK_ENDPOINT", skip_ws=True)

  # Posts {"type": "spotClearinghouseState", "user": address}
  spot_state = info.spot_user_state("0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036")
  print(spot_state)
  ```

  ```typescript TypeScript (@nktkas/hyperliquid) theme={"system"}
  import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";

  // apiUrl points the transport at your custom server
  const transport = new HttpTransport({ apiUrl: "YOUR_CHAINSTACK_ENDPOINT" });
  const info = new InfoClient({ transport });

  // Posts {"type": "spotClearinghouseState", "user": "0x..."}
  const spotState = await info.spotClearinghouseState({
    user: "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036",
  });
  console.log(spotState);
  ```
</CodeGroup>

<Note>
  **Use your own endpoint in your code.** The code examples use a placeholder Chainstack endpoint (YOUR\_CHAINSTACK\_ENDPOINT) — replace it with your own Hyperliquid node endpoint from the [Chainstack console](https://console.chainstack.com/). The curl above uses a shared public endpoint for quick checks only; do not use it in production.
</Note>

## Use case

The `info` endpoint with `type: "spotClearinghouseState"` is essential for spot trading applications that need to:

* Display user's current spot token balances
* Calculate available balance for new orders (total - hold)
* Show which tokens are locked in open orders
* Track cost basis and entry values for portfolio management
* Validate order placement against available balances
* Build trading interfaces with real-time balance updates
* Implement portfolio tracking and PnL calculations

This endpoint is typically called frequently to keep trading interfaces updated with current balance information and ensure accurate order placement validation.


## OpenAPI

````yaml openapi/hyperliquid_node_api/hypercore_info/info_spotclearinghousestate.json post /4f8d8f4040bdacd1577bff8058438274/info
openapi: 3.0.0
info:
  title: Hyperliquid Node API
  version: 1.0.0
  description: This is an API for interacting with Chainstack Hyperliquid node.
servers:
  - url: https://hyperliquid-mainnet.core.chainstack.com
security: []
paths:
  /4f8d8f4040bdacd1577bff8058438274/info:
    post:
      tags:
        - hyperliquid operations
      summary: info (spotClearinghouseState)
      operationId: infoSpotClearinghouseState
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  default: spotClearinghouseState
                  enum:
                    - spotClearinghouseState
                  description: Request type to retrieve user's spot token balances
                user:
                  type: string
                  default: '0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036'
                  description: Onchain address in 42-character hexadecimal format
              required:
                - type
                - user
      responses:
        '200':
          description: User's spot token balances
          content:
            application/json:
              schema:
                type: object
                properties:
                  balances:
                    type: array
                    description: Array of user's spot token balances
                    items:
                      type: object
                      properties:
                        coin:
                          type: string
                          description: Token symbol (e.g., 'USDC', 'PURR')
                        token:
                          type: integer
                          description: Token index identifier
                        hold:
                          type: string
                          description: Amount on hold (locked in open orders)
                        total:
                          type: string
                          description: Total balance including held amount
                        entryNtl:
                          type: string
                          description: Entry notional value
                      required:
                        - coin
                        - token
                        - hold
                        - total
                        - entryNtl
                required:
                  - balances

````