# Subaccounts

Subaccounts let you run independent accounts under a single group — each with its own balances, orders, rate limits, and API keys. Separate strategies and contain risk, test new ideas in a capped account without touching your main book, or give each agent its own isolated space to operate. A single Master API key can act across all of them; a single transfer moves funds between them. 

In one sentence: **issue a Master API key, create accounts under your group, target them by passing an `account` identifier (a lowercase, hyphenated slug like `strategy-trend`) in your request payload, and move funds between them with an internal transfer.** Everything below is the long version.

## The model

Your relationship with Gemini is organized into three layers:

| Layer | What it is | Created by |
|-------|------------|-----------|
| **Account group** | The top-level container, provisioned by Gemini during onboarding. Holds KYC records, approved withdrawal addresses, and group-wide settings. You cannot create or modify this layer through the API. | Gemini onboarding |
| **Account** | A member of a group. Holds balances, orders, trades, and transfers. Has a type (`exchange` or `custody`). One Master key per group can act across all accounts (subject to roles bound to that key); each account also has its own API keys. | `POST /v1/account/create` or Gemini support |
| **User** | A person with KYC information. A user can be a member of multiple accounts and multiple groups. Roles are assigned per (user, account) pair. | Gemini onboarding |

```
┌──────────────────────────────────────────────┐
│                Account Group                 │
│   KYC · approved addresses · group settings  │
└─────────┬───────────────┬───────────────┬────┘
          │               │               │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │  Account  │   │  Account  │   │  Account  │
    │ (exchange)│   │ (exchange)│   │ (custody) │
    └─────┬─────┘   └─────┬─────┘   └─────┬─────┘
          │               │               │
          └───────────────┴───────────────┘
                          │
                  Users (one or more,
                   roles per account)
```

The group is provisioned through Gemini onboarding. Once it exists, an Administrator on a Master API key can spin up new accounts inside it through the API.

## Account types

`POST /v1/account/create` accepts two types:

| Type | What it's for |
|------|---------------|
| `exchange` | Spot trading, prediction markets, and fund management. Default when `type` is omitted. |
| `custody` | Cold-storage custody of crypto assets. Subject to custody fee schedule. See [Fund Management](/trading/rest-api/fund-management) for custody-specific operations. **Custody must be enabled on your group by Gemini before you can create custody accounts — contact the Gemini team.** |

For accounts with specialized capabilities (derivatives, margin), create the account through [API settings](https://exchange.gemini.com/settings/api) or contact the Gemini team.

The response returns a kebab-cased `account` shortname (e.g., `my-secondary-account`) that you pass as the `account` parameter on subsequent Master-key requests.

## How API keys work with the hierarchy

API keys come in two flavors:

- **Master keys** are prefixed `master-`. They can act on any account in the group by passing an `account` parameter (the shortname returned by `createNewAccount`) in the request payload. See [Master API Key](/authentication/api-key#master-api-key) for the full signing mechanics.
- **Account keys** are prefixed `account-`. They are scoped to a single account and never carry an `account` parameter.

The decoded payload for a Master key targeting `my-secondary-account` looks like this — `account` is just another field alongside `request` and `nonce`:

```json
{
  "request": "/v1/balances",
  "nonce": 1234567890123,
  "account": "my-secondary-account"
}
```

Omit `account` and the request targets whichever account the key itself belongs to.

Roles are assigned per key. The four public roles — Administrator, Trader, Fund Manager, Auditor — are documented on the [Roles](/roles#roles) page along with which endpoints each role can access. Specialized roles exist for institutional setups (for example, separate transfer-only and settlement workflows); contact the Gemini team if you need one of these enabled.

## When to use subaccounts

### Organize by purpose

Keep different goals, clients, or stakeholders in separate accounts so attribution, audit, and offboarding are clean by construction — not solved retroactively.

- **Trading desk** — one account per trader with a scoped API key; ops holds the Master key for funding and reconciliation.
- **End-client platforms** — each external client gets their own account; attribution, audit, and offboarding are clean by default.
- **Prop vs client books** — client assets in a custody account, prop trading in exchange accounts; same Master key, no commingling.
- **Per-LP isolation** — one account per LP for clean P&L attribution and per-entity tax reporting.

### Separate strategies and contain risk

Active trades and long-term holdings no longer have to share the same account. Test a new approach in a capped account without touching your main book.

- **Long-term vs active** — long-term holdings in one account, active trading in another, rebalanced via internal transfer.
- **Experiment quarantine** — fund a small account with a capped transfer; if the strategy blows up, the rest of your books are untouched.

### Give each bot its own space

Each agent or bot gets a dedicated account — its own balances, its own rate limits, its own blast radius. One bot going wrong can't affect the others.

- **Agentic and automated trading** — one account per agent or bot; a runaway agent's blast radius is contained to its own account and orders.
- **Prediction market bots** — one account per bot or market category (crypto, sports, weather); a bad fill or unexpected settlement is contained to that account alone.

## Subaccount patterns

### Agentic and automated trading

Give each agent — prediction market bot, strategy bot, LLM-driven trader, market maker — its own account and its own **account-level API key** scoped to that account with only the Trader role. The orchestrator (your control plane) holds the **Master key** with Administrator + Fund Manager roles for provisioning and funding; individual agents never hold the Master key and never have visibility into other accounts.

```
Group ── pm-crypto      (exchange) ← account key, Trader role only
      ├─ pm-sports      (exchange) ← account key, Trader role only
      ├─ agent-trend    (exchange) ← account key, Trader role only
      └─ agent-mm       (exchange) ← account key, Trader role only
        Master key held by orchestrator (Administrator + Fund Manager)
```

**Isolation guarantees per account:**
- **Cancel-all scope**: cancels only that account's open orders — other agents are unaffected.
- **Rate limits**: enforced per account — one agent hitting its limit does not throttle others.
- **Blast radius**: a rogue or crashing agent can only affect its own balances and orders.

For additional containment, provision each agent's key with **Requires Heartbeat** (Cancel on Disconnect): if the agent process crashes or goes silent, all its open orders cancel automatically within 30 seconds. See [API Key — Require Heartbeat](/authentication/api-key#require-heartbeat).

Endpoints: [Create New Account](/rest-api/common/admin/create-new-account) · [Transfer Between Accounts](/trading/rest-api/fund-management/transfer-between-accounts) · [Create New Order](/trading/rest-api/orders/create-new-order).

### Prediction market bots

Prediction market accounts are exchange accounts — the same account type, the same `account` parameter on Master-key requests, the same isolation guarantees. Organize by market category, by contract type, or by strategy. Fund each account via internal transfer; if one bot takes an unexpected loss on a contract settlement, only that account's balance is affected.

```
Group ── pm-crypto   (exchange) ← account key, Trader role only
      ├─ pm-sports   (exchange) ← account key, Trader role only
      └─ pm-weather  (exchange) ← account key, Trader role only
        Master key held by orchestrator (Administrator + Fund Manager)
```

Each bot authenticates over WebSocket using its account-level key. Before any account in the group can trade, accept the prediction markets terms once at the group level (`POST /v1/prediction-markets/terms/accept`) — a single acceptance covers all accounts in the group.

Endpoints: [Create New Account](/rest-api/common/admin/create-new-account) · [Transfer Between Accounts](/trading/rest-api/fund-management/transfer-between-accounts) · [Prediction Markets](/prediction-markets/prediction-markets).

### Prop vs experimental

A production account runs the live book. A small experimental account, funded by a capped internal transfer, runs new strategies. If the experiment blows up, the loss is bounded.

```
Group ── prod
      └─ experimental (capped via transfer)
```

Endpoints: [Create New Account](/rest-api/common/admin/create-new-account) · [Transfer Between Accounts](/trading/rest-api/fund-management/transfer-between-accounts).

### Team separation

One account per trader. Each trader gets their own account-level API key with the Trader role. The Master key (held by ops) handles funding via internal transfer and uses [List Accounts In Group](/rest-api/common/admin/list-accounts-in-group) for daily reconciliation.

```
Group ── trader-alex
      ├─ trader-blake
      └─ trader-casey
```

Endpoints: [Create New Account](/rest-api/common/admin/create-new-account) · [List Accounts In Group](/rest-api/common/admin/list-accounts-in-group) · [Transfer Between Accounts](/trading/rest-api/fund-management/transfer-between-accounts).

### Client vs proprietary funds

Client cold-storage assets live in a custody account; prop trading runs in one or more exchange accounts. Custody and exchange accounts in the same group support internal transfers when assets need to move between books.

```
Group ── client-custody  (custody)
      ├─ prop-trading-1  (exchange)
      └─ prop-trading-2  (exchange)
```

Endpoints: [Create New Account](/rest-api/common/admin/create-new-account) (use `type: custody` for the custody account; requires prior enablement by the Gemini team) · [Transfer Between Accounts](/trading/rest-api/fund-management/transfer-between-accounts).

### End-client platform

You're building a product on top of Gemini for outside users — managed-account services, fund-of-funds infrastructure, per-LP attribution for a fund, or custody for a wealth platform. Each client or LP gets its own account so attribution, audit, and offboarding are clean by construction rather than solved by partitioned ledgers.

```
Group ── client-alpha  (exchange or custody)
      ├─ client-beta   (exchange or custody)
      └─ client-gamma  (exchange or custody)
```

Endpoints: [Create New Account](/rest-api/common/admin/create-new-account) · [List Accounts In Group](/rest-api/common/admin/list-accounts-in-group) · [Transfer Between Accounts](/trading/rest-api/fund-management/transfer-between-accounts).

### Treasury split

Long-term holdings sit in a custody or quiet exchange account; a smaller hot-trading account funds day-to-day execution. Periodic internal transfers rebalance the two.

```
Group ── treasury
      └─ trading-hot
```

Endpoints: [Create New Account](/rest-api/common/admin/create-new-account) · [Transfer Between Accounts](/trading/rest-api/fund-management/transfer-between-accounts).

## End-to-end workflow

> **Prerequisite:** Subaccounts require an institutional account group provisioned by Gemini during onboarding. Standard individual accounts don't have this structure — if you don't see a Master key option at [API settings](https://exchange.gemini.com/settings/api), contact the Gemini team.

1. **Provision a Master API key.** From the Gemini Exchange [API settings](https://exchange.gemini.com/settings/api), create a Master-level key with the Administrator role.
2. **Create the account.** Call [`POST /v1/account/create`](/rest-api/common/admin/create-new-account) with a unique `name` and `type` (`exchange` or `custody`). Exchange accounts are available immediately. Custody accounts require prior enablement by the Gemini team. The response returns a kebab-cased shortname; record it. **Tip:** choose a descriptive shortname like `agent-trend` or `client-alpha` — it's what you'll pass in every Master-key request targeting that account.
3. **List your group.** Call [`POST /v1/account/list`](/rest-api/common/admin/list-accounts-in-group) to confirm the new account is present and to capture all shortnames.
4. **Fund the account.** Call [`POST /v1/account/transfer/{currency}`](/trading/rest-api/fund-management/transfer-between-accounts) to move balances between accounts in the same group.
5. **Place orders against the account.** Use your Master key with the `account` parameter set to the shortname, or provision an account-level key for that account.
6. **Rename when needed.** Call [`POST /v1/account/rename`](/rest-api/common/admin/rename-account) to change the display name or shortname (the shortname is what you'll use in subsequent requests).
7. **Reconcile.** Use [`POST /v1/balances`](/trading/rest-api/fund-management/get-available-balances), [`POST /v2/transfers`](/trading/rest-api/fund-management/list-past-transfers), and [`POST /v1/transactions`](/trading/rest-api/fund-management/get-transaction-history) per account or across the group.

## Constraints and gotchas

- **Max accounts per group.** The group-level account cap is configurable by Gemini; contact the Gemini team if you need it raised.
- **Account listing limit.** [List Accounts In Group](/rest-api/common/admin/list-accounts-in-group) returns up to 500 accounts per call.
- **Same-group transfers only.** [Transfer Between Accounts](/trading/rest-api/fund-management/transfer-between-accounts) moves funds between two accounts in the same group. There is no API path to transfer between groups.
- **Use shortnames, not display names.** The `account` parameter on Master-key requests, and the value returned by [Create New Account](/rest-api/common/admin/create-new-account), is the kebab-cased shortname.
- **Roles are per key.** A Master key needs the Administrator role to create accounts; the Fund Manager role to execute internal transfers; the Trader role to place orders. See [Roles](/roles#roles) for the full matrix.
- **Custody requires prior enablement.** Custody must be enabled on your group by Gemini before `POST /v1/account/create` will accept `type: custody`. Contact the Gemini team to get it enabled. Once enabled, custody accounts have a different fee schedule and do not support open trading. See [Fund Management](/trading/rest-api/fund-management) for custody-specific behavior.
- **Derivatives and margin accounts.** Accounts with derivatives or margin capabilities are not created via this endpoint — provision them through [API settings](https://exchange.gemini.com/settings/api) or via the Gemini team.
- **OAuth.** Listing accounts via OAuth requires the `account:read` scope. See [OAuth Scopes](/authentication/oauth#oauth-scopes).

## Related

- [Master API Key](/authentication/api-key#master-api-key) — how the `account` payload parameter works
- [Roles](/roles#roles) — what each role can do on Master and account-scoped endpoints
- [Create New Account](/rest-api/common/admin/create-new-account) · [Rename Account](/rest-api/common/admin/rename-account) · [List Accounts In Group](/rest-api/common/admin/list-accounts-in-group) · [Get Account Detail](/rest-api/common/admin/get-account-detail)
- [Transfer Between Accounts](/trading/rest-api/fund-management/transfer-between-accounts)
- [Prediction Markets](/prediction-markets/prediction-markets) — prediction market bots use exchange accounts; terms acceptance is once per group
- [OAuth Scopes](/authentication/oauth#oauth-scopes)