# Subaccounts

> HyperCore private-preview documentation.

> For the complete documentation index, see [llms.txt](/docs/llms.txt).

<Callout intent="info">
  This API is in private preview. Target October 2026; timing is subject to change.
</Callout>


# Subaccounts

Returns a master's named sub-accounts with their perpetual and spot account state.


<Note>

  **Available now.** This read is served at the interim endpoint today.

</Note>

## Request

`POST /{apiKey}/info`

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| `type`    | string | Yes      | Selects `subAccounts`.         |
| `user`    | string | Yes      | Master or sub-account address. |

```json
{
  "type": "subAccounts",
  "user": "0x0000000000000000000000000000000000000000"
}
```

## Response fields

| Field                                  | Type          | Description                                                                       |
| -------------------------------------- | ------------- | --------------------------------------------------------------------------------- |
| `[]`                                   | array \| null | Sub-account entries; the native API can return `null` when no state is available. |
| `[].name`                              | string        | Display name assigned to the sub-account.                                         |
| `[].subAccountUser`                    | string        | Address of the sub-account.                                                       |
| `[].master`                            | string        | Address that controls this sub-account.                                           |
| `[].clearinghouseState`                | object        | Perpetual account state for the sub-account.                                      |
| `[].clearinghouseState.marginSummary`  | object        | Cross-margin collateral, notional, and margin metrics.                            |
| `[].clearinghouseState.withdrawable`   | string        | USDC withdrawable while retaining the current perpetual positions.                |
| `[].clearinghouseState.assetPositions` | array         | Open perpetual positions with their position state.                               |
| `[].clearinghouseState.time`           | integer       | Millisecond timestamp of the included perpetual-account state.                    |
| `[].spotState.balances[]`              | array         | Spot balances held by the sub-account.                                            |
| `[].spotState.balances[].coin`         | string        | Spot-token symbol, for example `USDC`.                                            |
| `[].spotState.balances[].total`        | string        | Combined balance for that spot token, as a decimal string.                        |
| `[].spotState.balances[].hold`         | string        | Amount reserved by orders.                                                        |

## Response example

```json
[
  {
    "name": "Test",
    "subAccountUser": "0x035605fc2f24d65300227189025e90a0d947f16c",
    "master": "0x8c967e73e6b15087c42a10d344cff4c96d877f1d",
    "clearinghouseState": {
      "withdrawable": "29.78001",
      "assetPositions": [],
      "time": 1733968369395
    },
    "spotState": {
      "balances": [{ "coin": "USDC", "total": "0.22", "hold": "0.0" }]
    }
  }
]
```