Skip to main content
Create Sub-Account
The email field, not shareKyc, decides whether the sub-account is active at creation:
  • When shareKyc is false or not provided: email is required. WhiteBIT sends an invitation to that email, and the sub-account stays inactive until the end user opens the link and sets a password. The link expires after three days and can be re-sent on whitebit.com, not through the API.
  • When shareKyc is true: leave email out. The sub-account is active as soon as the request succeeds and shares the main account’s verification.
  • A request with email starts the invitation flow even when shareKyc is true.

Used in these guides

Authorizations

X-TXC-APIKEY
string
header
required

The public WhiteBIT API key.

X-TXC-PAYLOAD
string
header
required

Base64-encoded JSON request body.

X-TXC-SIGNATURE
string
header
required

HMAC-SHA512 signature of the payload, hex-encoded. Computed as hex(HMAC-SHA512(payload, api_secret)).

Body

application/json
alias
string
required

Sub-account name, up to 127 characters. Unique among the main account's sub-accounts; the alias of a deleted sub-account can be used again.

Maximum string length: 127
Example:

"trading_bot"

permissions
object
required
email
string

End user's email. Required when shareKyc is false or omitted; leave it out when shareKyc is true. Any email starts the invitation flow, and the sub-account stays inactive until the end user sets a password

Example:

"sub@example.com"

shareKyc
boolean

Share the main account's KYC with the sub-account. With true, leave email out; the sub-account is then active at creation

Example:

false

Response

Sub-account created successfully

id
string

Sub-account identifier

Example:

"8e667b4a-0b71-4988-8af5-9474dbfaeb51"

alias
string

Sub-account alias/name

Example:

"trading_bot"

userId
string | null

User identifier associated with account. In List of Sub-Accounts, null for a sub-account created with email until the end user sets the password

Example:

"u-12345"

email
string

Sub-account email (masked)

Example:

"s***@example.com"

status
string

Sub-account status. In List of Sub-Accounts, active once the end user of a sub-account created with email has set the password; a sub-account created without an email (shareKyc: true) is active from the first list call

Example:

"active"

color
string

Sub-account color

Example:

"#FF5733"

kyc
object

KYC information

permissions
object

Sub-account permissions