Subaccounts

Every Arcus account is addressed by a pair: the wallet address and an accountIndex. A single wallet can hold up to 10 subaccounts, one per index from 0 to 9. Index 0 is the primary account; indexes 1–9 are additional subaccounts you can use to separate strategies, books, or risk. An accountIndex outside the 0–9 range is rejected with HTTP 400 — the one exception is API-key scope, where 255 means all subaccounts (see below). In signed payloads the field is abbreviated ai.

Implicit creation

There is no create-subaccount endpoint. A subaccount comes into existence the first time it is used — when you deposit into it, transfer funds into it, or place an order on it. Scoping an API key to it does not create it. Until then it has no state: GET /v1/account returns 404 with "this account has no activity yet", and the same address and index return 200 after the first event lands.

Each index is an isolated silo

Every accountIndex is a self-contained account. It keeps its own collateral balance and its own rate-limit pools. Positions, orders, and free collateral under one index are independent of every other index on the same wallet. Trading volume and fee tier are the exception: they are tracked per wallet address and shared by all of its subaccounts. See Fees. Because rate limits are tracked per subaccount, spreading activity across indexes gives each index its own budget. See Rate limits for how the pools are counted.

API keys and accountIndex

An API key’s scope is set when the key is created: an accountIndex of 0–9 binds it to that single subaccount, and 255 scopes it to all of the wallet’s subaccounts (the default for web/mobile trading keys). A single-subaccount key’s order writes — place, cancel, modify, and batch operations — are authorized against its bound index, and a mismatch is rejected with HTTP 403. Account-scoped reads take an optional accountIndex query parameter and default to 0 when it is omitted. The one exception is GET /v1/apiKeys: called without accountIndex, it lists keys across all of the wallet’s subaccounts. Single-subaccount entries carry the accountIndex they belong to; all-subaccounts keys omit it and set allSubaccounts: true. See Authentication for how keys are registered and how requests are signed.

Subaccounts are not margin isolation

Subaccounts are an account-partitioning mechanism, not a margining one. Margin mode (cross or isolated) is chosen per market / per position, so a single subaccount can hold both cross-margined and isolated-margined positions at the same time. Do not use separate subaccounts as a substitute for isolated margin. For how margin modes work, see Cross & isolated margin.

Moving funds between subaccounts

To move collateral from one subaccount to another of the same wallet, submit an internal transfer with POST /v1/transfer. Deposits and withdrawals are separate, per-subaccount operations — depositing into a specific index is covered in Fund a testnet account (via the accountIndex argument). A few properties define the flow:

• Same wallet only. In v0 an internal transfer moves collateral between two accountIndex values that both belong to the same master wallet address. There is no cross-wallet recipient; the source and destination indexes must differ.
• Wallet-signed or API-key-signed. A transfer is signed with your wallet by default, or with an API key; the signing mechanics for both live on the endpoint page and in Authentication.
• Asynchronous settlement. A 202 Accepted means the transfer was validated and queued with status: PENDING and a transferId. The terminal outcome is delivered separately — read it back on GET /v1/accountTransferUpdates or the accountTransferUpdates WebSocket channel, correlating on transferId. Insufficient free collateral surfaces there as REJECTED_INSUFFICIENT_COLLATERAL (on the WebSocket event: status: REJECTED, rejectReason: INSUFFICIENT_COLLATERAL).

Next steps