> For the complete documentation index, see [llms.txt](https://docs.pangolin.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pangolin.exchange/pangoperps/user-api/sub-account.md).

# Sub-account

Manage sub-accounts and view combined account balances and positions.

## Sub-account

These operations let the main account create and manage sub-accounts, inspect aggregated positions and balances, and settle sub-account PnL. Only the main account can call the listing, creation, update, and aggregate endpoints. The main account's API key can control its sub-accounts.

### Authentication headers

Private operations use `orderly-timestamp` (string, signed-request time in milliseconds), `orderly-account-id` (string, authenticated account ID), `orderly-key` (string, public signing key), and `orderly-signature` (string, request signature), except where an endpoint below specifies an account-header constraint.

### Add Sub-account

**POST /v1/client/add\_sub\_account**\
Mainnet: POST <https://api.orderly.org/v1/client/add\\_sub\\_account\\>
Testnet: POST <https://testnet-api.orderly.org/v1/client/add\\_sub\\_account\\>
Rate limit: 10 requests per second.

Only the main account may call this endpoint. Submit `application/json` with optional `description` (string) as a user-defined label. The main account's key can manage the sub-account.

HTTP 200 returns `success`, required `data.sub_account_id` (number) and `data.description` (string), plus server `timestamp`.

### Get Sub-account List

**GET /v1/client/sub\_account**\
Mainnet: GET <https://api.orderly.org/v1/client/sub\\_account\\>
Testnet: GET <https://testnet-api.orderly.org/v1/client/sub\\_account\\>
Rate limit: 10 requests per second.

Only the main account may call this endpoint. No query or path parameters. HTTP 200 returns required `data.main_account_id` (string) and required `data.rows` array. Each row contains `sub_account_id` (string account ID) and `description` (string label). The envelope also includes `success` and server `timestamp`.

```
{"success":true,"data":{"main_account_id":"0x7ecc7eb7dc60d7fb5c5ea9cc637da1a46e265a744efda327b9914d7a21725bbf","rows":[{"sub_account_id":"0x86987799a1433266cacd80c817b670336d6779468f69defd6f8dc384a07b6457","description":"abc"}]},"timestamp":1702989203989}
```

### Update Sub-account

**POST /v1/client/update\_sub\_account**\
Mainnet: POST <https://api.orderly.org/v1/client/update\\_sub\\_account\\>
Testnet: POST <https://testnet-api.orderly.org/v1/client/update\\_sub\\_account\\>
Rate limit: 10 requests per second.

Only the main account may call this endpoint. Submit `application/json` with `sub_account_id` (string, required) and `description` (string, optional).

HTTP 200 returns `success` (boolean) and server `timestamp` (integer, milliseconds).

### Get Aggregate Positions

**GET /v1/client/aggregate/positions**\
Mainnet: GET <https://api.orderly.org/v1/client/aggregate/positions\\>
Testnet: GET <https://testnet-api.orderly.org/v1/client/aggregate/positions\\>
Rate limit: 1 request per 60 seconds.

Only the main account may call this endpoint. No query or path parameters. HTTP 200 returns `success`, `timestamp`, and `data.rows`, an array aggregating the main account and sub-account positions. Each row may include: `account_id` (string); numeric `IMR_withdraw_orders`, `MMR_with_orders`, `average_open_price`, `cost_position`, `est_liq_price`, `fee_24_h`, `imr`, `last_sum_unitary_funding`, `mark_price`, `mmr`, `pending_long_qty`, `pending_short_qty`, `pnl_24_h`, `position_qty`, `settle_price`, `seq`, `timestamp`, `updated_time`, `unsettled_pnl`, `margin`, and `accrued_funding_fee`; `symbol` and `margin_mode` are strings; `leverage` is an integer.

```
[{"account_id":"0x11111","IMR_withdraw_orders":0.1,"MMR_with_orders":0.05,"average_open_price":27908.14386047,"cost_position":-139329.358492,"est_liq_price":117335.92899428,"fee_24_h":0,"imr":0.1,"last_sum_unitary_funding":70.38,"mark_price":27794.9,"mmr":0.05,"pending_long_qty":0,"pending_short_qty":0,"pnl_24_h":0,"position_qty":-5,"settle_price":27865.8716984,"symbol":"PERP_BTC_USDC","seq":1730181536341943600,"timestamp":1685429350571,"updated_time":1685429350571,"unsettled_pnl":354.858492,"leverage":10}]
```

### Get Aggregate Holding

**GET /v1/client/aggregate/holding**\
Mainnet: GET <https://api.orderly.org/v1/client/aggregate/holding\\>
Testnet: GET <https://testnet-api.orderly.org/v1/client/aggregate/holding\\>
Rate limit: 1 request per 60 seconds.

Only the main account may call this endpoint. No query or path parameters. HTTP 200 returns `success`, server `timestamp`, and `data.rows`, an array of balances for the main account and its sub-accounts. Each record includes `account_id` (string), `updated_time` (number, milliseconds), `token` (string), and numeric balances `holding`, `frozen`, `pending_short`, `isolated_margin`, and `isolated_order_frozen`.

```
[{"account_id":"0x1111","updated_time":1580794149000,"token":"BTC","holding":-28.000752,"frozen":0,"pending_short":-2000,"isolated_margin":0,"isolated_order_frozen":0},{"account_id":"0x2222","updated_time":1580794149000,"token":"ETH","holding":-10.123456,"frozen":0,"pending_short":-500,"isolated_margin":0,"isolated_order_frozen":0}]
```

### Settle Sub-account PnL

**POST /v1/sub\_account\_settle\_pnl**\
Mainnet: POST <https://api.orderly.org/v1/sub\\_account\\_settle\\_pnl\\>
Testnet: POST <https://testnet-api.orderly.org/v1/sub\\_account\\_settle\\_pnl\\>
Rate limit: 10 requests per second.

The main account's key can control sub-accounts. Include `orderly-timestamp`, `orderly-key`, and `orderly-signature`; the required account header is `orderly_account_id` (with an underscore), and it must contain the sub-account ID. Submit `application/json` with required `settle_nonce` (number).

HTTP 200 returns `success`, required `data.settle_pnl_id` (integer), and server `timestamp` (integer, milliseconds).
