Copy page

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

Code
┌──────────────────────────────────────────────┐
│                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 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 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 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:

Code
{
  "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 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.

Code
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.

Endpoints: Create New Account · Transfer Between Accounts · 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.

Code
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 · Transfer Between Accounts · 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.

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

Endpoints: Create New Account · 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 for daily reconciliation.

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

Endpoints: Create New Account · List Accounts In Group · 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.

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

Endpoints: Create New Account (use type: custody for the custody account; requires prior enablement by the Gemini team) · 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.

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

Endpoints: Create New Account · List Accounts In Group · 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.

Code
Group ── treasury
      └─ trading-hot

Endpoints: Create New Account · 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, contact the Gemini team.

1. Provision a Master API key. From the Gemini Exchange API settings, create a Master-level key with the Administrator role.
2. Create the account. Call POST /v1/account/create 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 to confirm the new account is present and to capture all shortnames.
4. Fund the account. Call POST /v1/account/transfer/{currency} 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 to change the display name or shortname (the shortname is what you'll use in subsequent requests).
7. Reconcile. Use POST /v1/balances, POST /v2/transfers, and POST /v1/transactions 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 returns up to 500 accounts per call.
• Same-group transfers only. 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, 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 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 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 or via the Gemini team.
• OAuth. Listing accounts via OAuth requires the account:read scope. See OAuth Scopes.

Related

• Master API Key — how the account payload parameter works
• Roles — what each role can do on Master and account-scoped endpoints
• Create New Account · Rename Account · List Accounts In Group · Get Account Detail
• Transfer Between Accounts
• Prediction Markets — prediction market bots use exchange accounts; terms acceptance is once per group
• OAuth Scopes