Sub-Accounts (Signed)

POST

order

curl -X POST https://mainnet-api1.bulk.trade/api/v1/order \
  -H "Content-Type: application/json" \
  -d '{"actions":[{"createSubAccount":{"name":"desk-1","marginSymbol":"USDC","marginAmount":1000.0}}],"nonce":1704067200000,"account":"FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7","signer":"FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7","signature":"5j7s..."}'

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {
          "createSubAccount": {
            "master": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
            "sub": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR",
            "name": "desk-1",
            "margin": 1000
          }
        }
      ]
    }
  }
}

Sub-account management uses the unified POST /order endpoint. Send a transaction with a single createSubAccount, renameSubAccount, or removeSubAccount action. Conceptual background lives on the Sub-Accounts page.

Sub-accounts are off-curve accounts. Their pubkeys are derived from the master and have no private key. Only the parent master can manage them.

Transaction Envelope

{
  "actions": [Action],
  "nonce": 1704067200000,
  "account": "master_pubkey_base58",
  "signer": "master_pubkey_base58",
  "signature": "base58_signature"
}

The account and signer must both be the master account that owns (or will own) the sub-account.

Create Sub-Account (`createSubAccount`)

Create a named sub-account under the signing master. Optionally seed it with margin in the same atomic action. Minimal (no initial margin):

{"createSubAccount": {"name": "desk-1"}}

With initial margin transfer:

{
  "actions": [
    {"createSubAccount": {"name": "desk-1", "marginSymbol": "USDC", "marginAmount": 1000.0}}
  ],
  "nonce": 1704067200000,
  "account": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
  "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
  "signature": "5j7s..."
}

Field	Type	Description
`name`	string	Sub-account display name. 1-32 chars, `A-Z a-z 0-9 - _`. Must be unique within the master’s account tree.
`marginSymbol`	string?	Optional margin asset (e.g. `"USDC"`). Must be present when `marginAmount` is non-zero.
`marginAmount`	number?	Optional initial margin transferred from master at creation. Default `0.0`. Must be a JSON number (unquoted), e.g. `0` or `1000.0`, not `"0"` or `"1000.0"`.

When both marginSymbol and marginAmount are provided, the protocol creates the sub-account and transfers margin from the master atomically. The master’s withdrawable balance is checked before the transfer.

The newly generated sub-account pubkey is returned in the createSubAccount status row (see Response), so clients can use it immediately without waiting for an account refresh.

Remove Sub-Account (`removeSubAccount`)

Remove a sub-account and sweep any remaining margin back to the master. The sub-account must have no open positions and no open orders.

{
  "actions": [
    {"removeSubAccount": {"toRemove": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR"}}
  ],
  "nonce": 1704067200001,
  "account": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
  "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
  "signature": "5j7s..."
}

Field	Type	Description
`toRemove`	string	Sub-account pubkey to remove (base58). Must belong to the signing master.

The same action also removes auto-created isolated accounts once they are flat (no open positions / orders).

Rename Sub-Account (`renameSubAccount`)

Update the display name of an existing sub-account owned by the signing master. The pubkey is unchanged, so cached references and isolated-account links keep working.

{
  "actions": [
    {"renameSubAccount": {"a": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR", "n": "desk-2"}}
  ],
  "nonce": 1704067200002,
  "account": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
  "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
  "signature": "5j7s..."
}

Field	Type	Description
`a`	string	Sub-account pubkey to rename (base58). Must belong to the signing master.
`n`	string	New display name. Same charset and length rules as `createSubAccount.name` (1-32 chars, `A-Z a-z 0-9 - _`). Must be unique within the master’s account tree.

The signing master can also rename its sub-accounts via an authorized agent wallet, following the same envelope rules as other account-management actions.

Constraints

Constraint	Value
Max sub-accounts per master	64
Max name length	32 characters
Allowed name characters	`A-Z`, `a-z`, `0-9`, `-`, `_`
Sub-accounts can create children	No (master-only)

Response

Same OrderResponse envelope as other actions. Sub-account actions emit dedicated status rows:

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {"createSubAccount": {
          "master": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
          "sub": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR",
          "name": "desk-1",
          "margin": 1000.0
        }}
      ]
    }
  }
}

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {"removeSubAccount": {
          "account": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR",
          "marginMoved": 1000.0
        }}
      ]
    }
  }
}

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {"renameSubAccount": {
          "master": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
          "account": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR",
          "name": "desk-2"
        }}
      ]
    }
  }
}

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {"createSubAccountFailed": {"message": "duplicate name"}}
      ]
    }
  }
}

Status	Terminal	Fields
`createSubAccount`	Yes	`{master, sub, name, margin}`
`createSubAccountFailed`	Yes	`{message}`
`removeSubAccount`	Yes	`{account, marginMoved}`
`removeSubAccountFailed`	Yes	`{message}`
`renameSubAccount`	Yes	`{master, account, name}`
`renameSubAccountFailed`	Yes	`{message}`

The newly generated sub-account pubkey is returned in the createSubAccount status, so clients can use it immediately without waiting for an account refresh.

Listing Sub-Accounts

A master account’s fullAccount snapshot includes a subAccounts array of {pubkey, name?} rows. See Query Account for the full response shape.

Trading From a Sub-Account

Sub-accounts can submit any signed action (orders, modify, cancel, on-fill, conditional baskets, transfers, agent wallets, user settings) the same way a master does. There is no separate endpoint and no special action variant. To act on a sub-account, just set the transaction account field to the sub-account’s pubkey while the master signs:

{
  "actions": [
    {"l": {"c": "BTC-USD", "b": true, "px": 100000.0, "sz": 0.1, "tif": "GTC", "r": false, "i": false}}
  ],
  "nonce": 1704067200000,
  "account": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR",
  "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
  "signature": "5j7s..."
}

Field	Value
`account`	Sub-account pubkey (the account being traded).
`signer`	One of: the parent master, the sub-account itself, an agent wallet registered on the parent master, or an agent wallet registered directly on the sub-account. Agents registered on a master automatically also work for that master’s sub-accounts; sub-accounts can additionally register their own agents independently.
`signature`	Ed25519 over the canonical wincode binary. The signed bytes already include `account`, so the signature binds this transaction to the sub-account. See Transaction Signing.

Notes:

Margin, positions, open orders, fills, and risk for that transaction are evaluated on the sub-account’s balance sheet, not the master’s.
All conditional and on-fill follow-ups attached to a sub-account order stay on that sub-account.
Any other signer (not the master, not the sub-account itself, and not an authorized agent on either) returns unauthorized signer.
To route a sub-account order into a per-instrument isolated account attached to that sub-account, set i = true on the order action. The isolated-account pubkey is never set as account.

Before You Start

See Transaction Signing for how to sign requests.Nonce: use a unique value (e.g. timestamp in nanoseconds): BigInt(Date.now()) * 1_000_000n.

Body

application/json

Transaction with a single sub-account action

actions

(createSubAccount · object | renameSubAccount · object | removeSubAccount · object)[]

required

Must contain exactly one createSubAccount, renameSubAccount, or removeSubAccount action

createSubAccount
renameSubAccount
removeSubAccount

Show child attributes

nonce

integer<int64>

required

account

string

required

Master account public key (base58)

signer

string

required

Signer public key (base58)

signature

string

required

Ed25519 signature (base58)

Response

200 - application/json

Sub-account action accepted

status

enum<string>

Available options:

ok,

error

response

object

Show child attributes

curl -X POST https://mainnet-api1.bulk.trade/api/v1/order \
  -H "Content-Type: application/json" \
  -d '{"actions":[{"createSubAccount":{"name":"desk-1","marginSymbol":"USDC","marginAmount":1000.0}}],"nonce":1704067200000,"account":"FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7","signer":"FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7","signature":"5j7s..."}'

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {
          "createSubAccount": {
            "master": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
            "sub": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR",
            "name": "desk-1",
            "margin": 1000
          }
        }
      ]
    }
  }
}

Getting Started

Market Data (HTTP)

Account (HTTP - Unsigned)

Trading (HTTP - Signed)

Testnet

WebSocket API

Transaction Envelope

Create Sub-Account (`createSubAccount`)

Remove Sub-Account (`removeSubAccount`)

Rename Sub-Account (`renameSubAccount`)

Constraints

Response

Listing Sub-Accounts

Trading From a Sub-Account

Before You Start

Body

Response

​Transaction Envelope

​Create Sub-Account (createSubAccount)

​Remove Sub-Account (removeSubAccount)

​Rename Sub-Account (renameSubAccount)

​Constraints

​Response

​Listing Sub-Accounts

​Trading From a Sub-Account

​Before You Start

Body

Response

Transaction Envelope

Create Sub-Account (`createSubAccount`)

Remove Sub-Account (`removeSubAccount`)

Rename Sub-Account (`renameSubAccount`)

Constraints

Response

Listing Sub-Accounts

Trading From a Sub-Account

Before You Start