Skip to main content
A subaccount is a separate wallet with its own balance, positions, orders, and trading key. Account model explains how subaccounts and keys fit together. All four routes count against the account throttle.

​
Open a subaccount

One call to POST /v3/account/subaccounts opens the subaccount, its wallet, and its one trading key. Sign the call with your management key. First, generate the trading keypair:
macOS ships LibreSSL, which can’t generate an Ed25519 key. Run these commands with OpenSSL 3 (brew install openssl). Then send the public key in the body:
  • label holds up to characters. It’s for display only and doesn’t have to be unique.
  • publicKey is the SPKI PEM of a fresh keypair, newlines included.
  • algorithm must match the key material.
  • expiresAt must be strictly in the future.
The keyId identifies the trading key. It’s also the subaccount’s address. Store it beside desk-1.pem.
If you lose desk-1.pem, nothing can sign as this subaccount again. Your management key can still defund the subaccount and change its label.
Opening a subaccount has two requirements:
  • You’ve passed KYC, our identity check, and aren’t self-excluded. We check this here, when you fund, and on every order you place.
  • You have a free slot. The sixth open fails.

​
List subaccounts

GET /v3/account/subaccounts returns one row per live subaccount. Sign it with a management or management::read key. The route has no paging and no filter.
200

​
Read a balance

GET /v3/account/subaccounts/{keyId}/balance returns one subaccount’s balance. The keyId is the subaccount’s trading key, not the key you sign with. Put it in the path before you sign. A trading or trading::read key that reads another subaccount gets a 404 SUBACCOUNT_NOT_FOUND, as if the subaccount did not exist. A subaccount holds up to live trading::read keys. A trader holds up to live management::read keys. Creating a read key past either cap returns a 400 ACCOUNT_RULE_REFUSED.

​
Change a label

PATCH /v3/account/subaccounts/{keyId} changes a subaccount’s label. The label is the only part of a subaccount you can change. Sign the call with your management key. The call moves no money and opens no position, so self-exclusion doesn’t block it. The call is idempotent: sending the same label twice makes one change.
200