> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcus.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Subaccounts

> How Arcus subaccounts work — the (wallet address, accountIndex) model, up to 10 isolated silos per wallet, API-key scoping, and same-wallet internal transfers

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 scope an API key to it, deposit into it, or transfer funds into 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**, its **own rate-limit pools**, and its **own volume credit** for fee tiering. Positions, orders, and free collateral under one index are independent of every other index on the same wallet.

Because rate limits are tracked per subaccount, spreading activity across indexes gives each index its own budget. See [Rate limits](/api-reference/rate-limits) for how the pools are counted.

<Note>
  Subaccounts and internal transfers are currently available **through the API only** — they are not yet exposed in the Arcus frontend / web console.
</Note>

## 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](/api-reference/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](/concepts/perpetuals/margin-modes).

## Moving funds between subaccounts

To move collateral from one subaccount to another **of the same wallet**, submit an internal transfer with [`POST /v1/transfer`](/api-reference/exchange/submit-internal-transfer). Deposits and withdrawals are separate, per-subaccount operations — depositing into a specific index is covered in [Fund a testnet account](/guides/fund-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.
* **Self-signed, not API-key auth.** The request is authenticated by a self-signed EIP-712 typed-data signature (the `Arcus Transfer` domain), so it does not use the `X-API-Key` / `X-Signature` headers. The signing mechanics live in [Authentication](/api-reference/authentication) and on the [endpoint page](/api-reference/exchange/submit-internal-transfer).
* **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`.

<Note>
  Internal transfers never settle on-chain — funds stay in custody and move between indexes inside the exchange.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Register an API key, scope it to a subaccount, and sign requests.
  </Card>

  <Card title="Submit internal transfer" icon="right-left" href="/api-reference/exchange/submit-internal-transfer">
    Move collateral between subaccounts of the same wallet.
  </Card>
</CardGroup>