Sub-account

#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).