Sub Accounts

Create Sub-account

POST

https://api.bitget.com

/api/v3/user/create-sub

Rate limit: 10/sec/UID

This API is used for the main account to create a sub-account. It only supports creating unified account virtual sub-accounts and does not support creating regular sub-accounts.

Unified account management read and write permissions are required

Only the main account can call this API

Create Sub-account › Request Parameters

username

string · required

Generate a virtual email address username. It can only contain lowercase letters and cannot exceed 20 characters.

accountMode

string

Sub-account Mode classic Classic Account Sub-account unified Unified Account Sub-account

note

string

Note, cannot exceed 50 characters.

Create Sub-account › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

username

string

Virtual Email Address

subUid

string

Virtual Sub-account ID

status

string

Account Status normal Normal

note

string

Note

createdTime

string

Creation Time, Unix Millisecond Timestamp

updatedTime

string

Last Modified Time, Unix Millisecond Timestamp

Freeze/Unfreeze Sub-account

POST

https://api.bitget.com

/api/v3/user/freeze-sub

Rate limit: 10/sec/UID

Freeze/Unfreeze Sub-account.

Unified account management read and write permissions are required

Only the main account can call this API

Freeze/Unfreeze Sub-account › Request Parameters

subUid

string · required

Sub-account ID to be frozen/unfrozen

operation

string · required

Operation Type freeze Freeze unfreeze Unfreeze

Freeze/Unfreeze Sub-account › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

data

object

No response fields

Get Sub-account List

GET

https://api.bitget.com

/api/v3/user/sub-list

Rate limit: 10/sec/UID

Query Sub-account List.

Unified account management read permissions are required

Only the main account can call this API

Get Sub-account List › Request Parameters

limit

string

Items per page The default value is 100, and the maximum value is 100.

cursor

string

Cursor ID Used for pagination. Do not pass it for the first query. For subsequent queries (second page and beyond), use the cursor returned from the previous query.

Get Sub-account List › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

object[]

Sub-account List

hasNext

boolean

Is there more data on the next page

cursor

string

Cursor ID

GET/api/v3/user/sub-list

curl https://api.bitget.com/api/v3/user/sub-list

Example Responses

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1740212430491,
  "data": {
    "list": [
      {
        "subUid": "xxx",
        "username": "llt****@virtual-bitget.com",
        "status": "normal",
        "accountMode": "CLASSIC",
        "type": "virtual",
        "note": "xxxx",
        "createdTime": "1740129303268",
        "updatedTime": "1740129303268"
      },
      {
        "subUid": "xxx",
        "username": "zml****@virtual-bitget.com",
        "status": "normal",
        "accountMode": "UNIFIED",
        "type": "virtual",
        "note": "xxx",
        "createdTime": "1740211445018",
        "updatedTime": "1740211445018"
      },
      {
        "subUid": "xxx",
        "username": "tmr****@virtual-bitget.com",
        "status": "freeze",
        "accountMode": "UNIFIED",
        "type": "virtual",
        "note": "xxx",
        "createdTime": "1740131800692",
        "updatedTime": "1740212129476"
      }
    ],
    "hasNext": false,
    "cursor": "18484"
  }
}

json

application/json

Get Sub-account Unified Assets

GET

https://api.bitget.com

/api/v3/account/sub-unified-assets

Rate limit: 1/sec/UID

Get Sub-account Unified Assets.

Unified account management read permissions are required

Get Sub-account Unified Assets › Request Parameters

subUid

string

Sub-account UID Leave blank to return all sub-account asset lists

cursor

string

Cursor ID For pagination. Omit in first request. Pass previous cursor in subsequent requests.

limit

string

Sub-accounts per Page Default value is 10, maximum is 50.

Get Sub-account Unified Assets › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object[]

Sub-account asset list

subUid

string

Sub-account UID

cursor

string

Cursor ID

object[]

List of account coins

Create Sub-account API Key

POST

https://api.bitget.com

/api/v3/user/create-sub-api

Rate limit: 10/sec/UID

This API is used to create an API Key for a sub-account under a unified account. It is applicable when the main account is in a mix or unified account mode. If the current main account is in the classic account mode, this API cannot be called.

Currently, only the creation of virtual sub-accounts is supported.

Unified account management read and write permissions are required

Only the main account can call this API

Create Sub-account API Key › Request Parameters

subUid

string · required

Sub-account ID

note

string · required

Note Name The note needs to start with a letter and supports [0-9], [a-z], [A-Z], as well as [-,_]

type

string · required

Permission Type read_write Read/Write read_only Read-only

passphrase

string · required

passphrase A combination of 8 to 32 characters of letters and numbers

permissions

string[] · required

Permission values Unified Account Permissions: uta_mgt Unified Account Management uta_trade Unified Account Trading

ips

string[] · required

Withdrawal Whitelist IP Multiple IP addresses are supported A maximum of 30 IPs can be bound to a single key Only supports IPv4

Create Sub-account API Key › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

note

string

Note

apiKey

string

Sub-account API Key

secret

string

Sub-account API Secret

type

string

Sub-account API Key Permission Type read_write Read/Write read_only Read-only

permissions

string[]

Sub-account API Key Permission Values Unified Account Permissions: uta_mgt Unified Account Management uta_trade Unified Account Trading

ips

string[]

Withdrawal Whitelist IP

POST/api/v3/user/create-sub-api

curl https://api.bitget.com/api/v3/user/create-sub-api \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "subUid": "subUid",
  "note": "note",
  "type": "type",
  "passphrase": "passphrase",
  "permissions": [
    "string"
  ],
  "ips": [
    "string"
  ]
}'

Example Request Body

{
  "subUid": "subUid",
  "note": "note",
  "type": "type",
  "passphrase": "passphrase",
  "permissions": [
    "string"
  ],
  "ips": [
    "string"
  ]
}

json

Example Responses

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1740213448866,
  "data": {
    "note": "test",
    "apiKey": "***********************************",
    "secret": "*****************************************",
    "type": "read_only",
    "permissions": [
      "uta_trade"
    ],
    "ips": [
      "127.0.0.1"
    ]
  }
}

json

application/json

Modify Sub-account API Key

POST

https://api.bitget.com

/api/v3/user/update-sub-api

Rate limit: 10/sec/UID

This API is used to modify the unified account sub-account API Key permissions and withdrawal whitelist IP addresses. It only supports modifying the API Key of a unified account sub-account and does not support creating an API Key for a classic account sub-account.

Unified account management read and write permissions are required

Only the main account can call this API

Modify Sub-account API Key › Request Parameters

apiKey

string · required

Sub-account API Key

passphrase

string · required

passphrase A combination of 8 to 32 characters of letters and numbers

type

string

Permission Type read_write Read/Write read_only Read-only This parameter is required when permissions has a value.

permissions

string[]

Permission values Unified Account Permissions: uta_mgt Unified Account Management uta_trade Unified Account Trading This parameter is required when type has a value.

ips

string[]

Whitelist IP If not provided, the IP address will not be modified. If an empty value is provided, the IP whitelist will be deleted. Multiple IP addresses are supported A maximum of 30 IPs can be bound to a single key Only supports IPv4

Modify Sub-account API Key › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

apiKey

string

Sub-account API Key

note

string

Note name

type

string

Sub-account API Key Permission Type read_write Read/Write read_only Read-only

permissions

string[]

Sub-account API Key Permission Values Unified Account Permissions: uta_mgt Unified Account Management uta_trade Unified Account Trading

ips

string[]

Whitelist IP

Delete Sub-account API Key

POST

https://api.bitget.com

/api/v3/user/delete-sub-api

Rate limit: 10/sec/UID

This API is used for the main account to delete a sub-account's API Key. It is not applicable for the main account or sub-account to delete their own API Key.

Please note that once the deletion is completed, the sub-account API Key will be immediately invalid. Before performing the deletion, ensure that this operation will not cause any loss.

This API only supports deleting API Keys of sub-accounts under a unified account, and does not support deleting API Keys of sub-accounts under a classic account.

Unified account management read and write permissions are required

Only the main account can call this API

Delete Sub-account API Key › Request Parameters

apikey

string · required

The sub-account API Key

Delete Sub-account API Key › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

data

object

No response fields

Get Sub-account API Keys

GET

https://api.bitget.com

/api/v3/user/sub-api-list

Rate limit: 10/sec/UID

Supports querying the full API Key list under a single sub-account.

Unified account management read permissions are required

Only the main account can call this API

Get Sub-account API Keys › Request Parameters

subUid

string · required

Sub-account UID

limit

string

Items per page The default value is 100, and the maximum value is 100.

cursor

string

Cursor ID Used for pagination. Do not pass it for the first query. For subsequent queries (second page and beyond), use the cursor returned from the previous query.

Get Sub-account API Keys › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

object[]

Sub-account API Key List

hasNext

boolean

Is there more data on the next page

cursor

string

Cursor ID

Create Agent Sub-account

POST

https://api.bitget.com

/api/v3/user/sub-account/agent-create

Rate limit: 1/sec/UID

Create a dedicated sub-account for an AI Agent instance. Agent sub-accounts are not editable after creation (name, permissions, and other configurations cannot be modified). Each main account shares the total sub-account quota with regular sub-accounts.

Permission: Unified account management (read and write)

Only the main account can call this API

Create Agent Sub-account › Request Parameters

username

string · required

Username used to generate the virtual email address. Only lowercase letters are allowed; maximum 20 characters

passphrase

string · required

API key passphrase. Must be 8-32 characters, consisting of letters and numbers

note

string

Sub-account note

Create Agent Sub-account › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

username

string

Agent sub-account username

subUid

string

Agent sub-account ID

apiKey

string

Agent sub-account API key

secret

string

Agent sub-account secret

note

string

Note

createdTime

string

Creation time, Unix millisecond timestamp

Trading Risk & Position Config Deposit/Withdrawal & Transfer

Account

Sub Accounts

Create Sub-account

POST

https://api.bitget.com

/api/v3/user/create-sub

Rate limit: 10/sec/UID

This API is used for the main account to create a sub-account. It only supports creating unified account virtual sub-accounts and does not support creating regular sub-accounts.

Unified account management read and write permissions are required

Only the main account can call this API

Create Sub-account › Request Parameters

username

string · required

Generate a virtual email address username. It can only contain lowercase letters and cannot exceed 20 characters.

accountMode

string

Sub-account Mode classic Classic Account Sub-account unified Unified Account Sub-account

note

string

Note, cannot exceed 50 characters.

Create Sub-account › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

username

string

Virtual Email Address

subUid

string

Virtual Sub-account ID

status

string

Account Status normal Normal

note

string

Note

createdTime

string

Creation Time, Unix Millisecond Timestamp

updatedTime

string

Last Modified Time, Unix Millisecond Timestamp

Freeze/Unfreeze Sub-account

POST

https://api.bitget.com

/api/v3/user/freeze-sub

Rate limit: 10/sec/UID

Freeze/Unfreeze Sub-account.

Unified account management read and write permissions are required

Only the main account can call this API

Freeze/Unfreeze Sub-account › Request Parameters

subUid

string · required

Sub-account ID to be frozen/unfrozen

operation

string · required

Operation Type freeze Freeze unfreeze Unfreeze

Freeze/Unfreeze Sub-account › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

data

object

No response fields

Get Sub-account List

GET

https://api.bitget.com

/api/v3/user/sub-list

Rate limit: 10/sec/UID

Query Sub-account List.

Unified account management read permissions are required

Only the main account can call this API

Get Sub-account List › Request Parameters

limit

string

Items per page The default value is 100, and the maximum value is 100.

cursor

string

Cursor ID Used for pagination. Do not pass it for the first query. For subsequent queries (second page and beyond), use the cursor returned from the previous query.

Get Sub-account List › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

object[]

Sub-account List

hasNext

boolean

Is there more data on the next page

cursor

string

Cursor ID

GET/api/v3/user/sub-list

curl https://api.bitget.com/api/v3/user/sub-list

Example Responses

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1740212430491,
  "data": {
    "list": [
      {
        "subUid": "xxx",
        "username": "llt****@virtual-bitget.com",
        "status": "normal",
        "accountMode": "CLASSIC",
        "type": "virtual",
        "note": "xxxx",
        "createdTime": "1740129303268",
        "updatedTime": "1740129303268"
      },
      {
        "subUid": "xxx",
        "username": "zml****@virtual-bitget.com",
        "status": "normal",
        "accountMode": "UNIFIED",
        "type": "virtual",
        "note": "xxx",
        "createdTime": "1740211445018",
        "updatedTime": "1740211445018"
      },
      {
        "subUid": "xxx",
        "username": "tmr****@virtual-bitget.com",
        "status": "freeze",
        "accountMode": "UNIFIED",
        "type": "virtual",
        "note": "xxx",
        "createdTime": "1740131800692",
        "updatedTime": "1740212129476"
      }
    ],
    "hasNext": false,
    "cursor": "18484"
  }
}

json

application/json

Get Sub-account Unified Assets

GET

https://api.bitget.com

/api/v3/account/sub-unified-assets

Rate limit: 1/sec/UID

Get Sub-account Unified Assets.

Unified account management read permissions are required

Get Sub-account Unified Assets › Request Parameters

subUid

string

Sub-account UID Leave blank to return all sub-account asset lists

cursor

string

Cursor ID For pagination. Omit in first request. Pass previous cursor in subsequent requests.

limit

string

Sub-accounts per Page Default value is 10, maximum is 50.

Get Sub-account Unified Assets › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object[]

Sub-account asset list

subUid

string

Sub-account UID

cursor

string

Cursor ID

object[]

List of account coins

Create Sub-account API Key

POST

https://api.bitget.com

/api/v3/user/create-sub-api

Rate limit: 10/sec/UID

Currently, only the creation of virtual sub-accounts is supported.

Unified account management read and write permissions are required

Only the main account can call this API

Create Sub-account API Key › Request Parameters

subUid

string · required

Sub-account ID

note

string · required

Note Name The note needs to start with a letter and supports [0-9], [a-z], [A-Z], as well as [-,_]

type

string · required

Permission Type read_write Read/Write read_only Read-only

passphrase

string · required

passphrase A combination of 8 to 32 characters of letters and numbers

permissions

string[] · required

Permission values Unified Account Permissions: uta_mgt Unified Account Management uta_trade Unified Account Trading

ips

string[] · required

Withdrawal Whitelist IP Multiple IP addresses are supported A maximum of 30 IPs can be bound to a single key Only supports IPv4

Create Sub-account API Key › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

note

string

Note

apiKey

string

Sub-account API Key

secret

string

Sub-account API Secret

type

string

Sub-account API Key Permission Type read_write Read/Write read_only Read-only

permissions

string[]

Sub-account API Key Permission Values Unified Account Permissions: uta_mgt Unified Account Management uta_trade Unified Account Trading

ips

string[]

Withdrawal Whitelist IP

POST/api/v3/user/create-sub-api

curl https://api.bitget.com/api/v3/user/create-sub-api \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "subUid": "subUid",
  "note": "note",
  "type": "type",
  "passphrase": "passphrase",
  "permissions": [
    "string"
  ],
  "ips": [
    "string"
  ]
}'

Example Request Body

{
  "subUid": "subUid",
  "note": "note",
  "type": "type",
  "passphrase": "passphrase",
  "permissions": [
    "string"
  ],
  "ips": [
    "string"
  ]
}

json

Example Responses

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1740213448866,
  "data": {
    "note": "test",
    "apiKey": "***********************************",
    "secret": "*****************************************",
    "type": "read_only",
    "permissions": [
      "uta_trade"
    ],
    "ips": [
      "127.0.0.1"
    ]
  }
}

json

application/json

Modify Sub-account API Key

POST

https://api.bitget.com

/api/v3/user/update-sub-api

Rate limit: 10/sec/UID

Unified account management read and write permissions are required

Only the main account can call this API

Modify Sub-account API Key › Request Parameters

apiKey

string · required

Sub-account API Key

passphrase

string · required

passphrase A combination of 8 to 32 characters of letters and numbers

type

string

Permission Type read_write Read/Write read_only Read-only This parameter is required when permissions has a value.

permissions

string[]

Permission values Unified Account Permissions: uta_mgt Unified Account Management uta_trade Unified Account Trading This parameter is required when type has a value.

ips

string[]

Modify Sub-account API Key › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

apiKey

string

Sub-account API Key

note

string

Note name

type

string

Sub-account API Key Permission Type read_write Read/Write read_only Read-only

permissions

string[]

Sub-account API Key Permission Values Unified Account Permissions: uta_mgt Unified Account Management uta_trade Unified Account Trading

ips

string[]

Whitelist IP

Delete Sub-account API Key

POST

https://api.bitget.com

/api/v3/user/delete-sub-api

Rate limit: 10/sec/UID

This API is used for the main account to delete a sub-account's API Key. It is not applicable for the main account or sub-account to delete their own API Key.

Please note that once the deletion is completed, the sub-account API Key will be immediately invalid. Before performing the deletion, ensure that this operation will not cause any loss.

This API only supports deleting API Keys of sub-accounts under a unified account, and does not support deleting API Keys of sub-accounts under a classic account.

Unified account management read and write permissions are required

Only the main account can call this API

Delete Sub-account API Key › Request Parameters

apikey

string · required

The sub-account API Key

Delete Sub-account API Key › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

data

object

No response fields

Get Sub-account API Keys

GET

https://api.bitget.com

/api/v3/user/sub-api-list

Rate limit: 10/sec/UID

Supports querying the full API Key list under a single sub-account.

Unified account management read permissions are required

Only the main account can call this API

Get Sub-account API Keys › Request Parameters

subUid

string · required

Sub-account UID

limit

string

Items per page The default value is 100, and the maximum value is 100.

cursor

string

Cursor ID Used for pagination. Do not pass it for the first query. For subsequent queries (second page and beyond), use the cursor returned from the previous query.

Get Sub-account API Keys › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

object[]

Sub-account API Key List

hasNext

boolean

Is there more data on the next page

cursor

string

Cursor ID

Create Agent Sub-account

POST

https://api.bitget.com

/api/v3/user/sub-account/agent-create

Rate limit: 1/sec/UID

Permission: Unified account management (read and write)

Only the main account can call this API

Create Agent Sub-account › Request Parameters

username

string · required

Username used to generate the virtual email address. Only lowercase letters are allowed; maximum 20 characters

passphrase

string · required

API key passphrase. Must be 8-32 characters, consisting of letters and numbers

note

string

Sub-account note

Create Agent Sub-account › Response Parameters

200

Successful response

code

string

msg

string

requestTime

integer

object

username

string

Agent sub-account username

subUid

string

Agent sub-account ID

apiKey

string

Agent sub-account API key

secret

string

Agent sub-account secret

note

string

Note

createdTime

string

Creation time, Unix millisecond timestamp

Trading Risk & Position Config Deposit/Withdrawal & Transfer