Copy page

Platform

Account Administration & Subaccounts

Gemini subaccounts let institutional groups, trading desks, and automated agents manage segregated trading environments under a single group.

Subaccounts operate as isolated containers with separate balances, order books, rate limits, and API keys. You can manage all subaccounts centrally with a single Master API key and internal transfers.

---

The Gemini Account Hierarchy

Gemini organizes accounts into a three-tier hierarchy:

Layer	Purpose	Scope & Lifecycle
Account Group	Top-level institutional container	Provisioned by Gemini during onboarding. Holds KYC/AML records, group-wide risk settings, and approved withdrawal whitelists. You cannot create or delete groups via API.
Account / Subaccount	Individual trading or custody entity	Created dynamically via POST /v1/account/create or in API Settings. Holds balances, open orders, trades, and position history. Can be of type exchange or custody.
User & API Keys	Identity & access controls	Users belong to one or more accounts. Access is granted via Roles assigned per user-account pair or per API key.

Code
┌─────────────────────────────────────────────────────────┐
│                      Account Group                      │
│     KYC Records · Approved Addresses · Group Settings    │
└───────────────┬─────────────────┬───────────────────────┘
                │                 │
     ┌──────────▼──────┐   ┌──────▼──────────┐
     │   Subaccount A  │   │   Subaccount B  │
     │   (exchange)    │   │    (custody)    │
     └──────────┬──────┘   └──────┬──────────┘
                │                 │
                └────────┬────────┘
                         │
                 Users & API Keys
              (Master or Account level)

---

Account Administration Endpoints

The API provides administrative control over subaccount creation, listing, detail inspection, renaming, and internal fund transfers:

Endpoint	Method	Role Required	Description
/v1/account/create	POST	Administrator	Creates a new subaccount under your group (type: exchange or type: custody). Returns the kebab-cased account shortname.
/v1/account/list	POST	Administrator / Auditor	Lists all subaccounts in your group, returning names, account IDs, shortnames, and creation timestamps (up to 500 per call).
/v1/account	POST	Administrator / Auditor	Retrieves detailed information for a specific subaccount (users, roles, country codes, and status).
/v1/account/rename	POST	Administrator	Renames a subaccount display name or kebab-cased shortname.
/v1/account/transfer/{currency}	POST	Fund Manager	Executes instant zero-fee transfers between two subaccounts in the same group.

---

Using Master API Keys

Gemini supports Master API Keys (prefixed with master-) and Account-Level API Keys (prefixed with account-).

• Master API Keys: Created at the Account Group level in API Settings. Master keys can invoke account-level endpoints across any subaccount in the group if assigned the appropriate roles.
• Targeting Subaccounts: To target a specific subaccount using a Master API key, pass the subaccount kebab-cased shortname in the "account" request parameter:

Code
{
  "request": "/v1/balances",
  "nonce": 1776294447000,
  "account": "primary-trading"
}

[!NOTE] If a Master key request omits the "account" parameter, the request defaults to the primary account to which the key was initially attached. Account-level keys (account-...) are strictly locked to their single assigned account and cannot pass the "account" parameter.

---

Subaccount Architectural Patterns

Subaccounts provide clean boundaries for risk containment, strategy isolation, team permissions, and bot operations:

1. Agentic & Automated Trading Bots

Assign each trading bot or LLM agent its own dedicated subaccount and an account-level API key restricted to the Trader role.

• Blast Radius: A bug or runaway strategy in one bot cannot deplete funds in other accounts.
• Rate Limits & Order Scope: Rate limits are enforced independently per subaccount. Executing Cancel All Orders cancels orders exclusively within that bot's subaccount.
• Orchestrator Control: The central orchestrator holds the Master API key with Administrator and Fund Manager roles to provision and fund subaccounts.

Code
Group ── agent-trend   (exchange) ← Account Key (Trader role)
      ├─ agent-arb     (exchange) ← Account Key (Trader role)
      └─ agent-mm      (exchange) ← Account Key (Trader role)
      Master Key held by Control Plane (Administrator + Fund Manager roles)

2. Prediction Market Bots

Organize prediction market trading bots into separate subaccounts by market category (e.g., pm-crypto, pm-sports, pm-weather).

• Group Terms Acceptance: Accept prediction markets terms once at the group level (POST /v1/prediction-markets/terms/accept); all subaccounts under the group inherit trading access.
• Isolated Settlements: Any unexpected loss or price index movement on contract settlement is bounded strictly to that bot's subaccount.

3. Prop vs. Client Funds

Keep firm capital and client assets completely segregated:

• Place client cold-storage funds in custody subaccounts.
• Run active proprietary trading strategies in exchange subaccounts.
• Use internal transfers (POST /v1/account/transfer/{currency}) to rebalance capital without incurring network gas or on-chain withdrawal fees.

---

End-to-End Subaccount Workflow

1. Provision Master Key: Create a Master API key with Administrator + Fund Manager roles in API Settings.
2. Create Subaccount: Call POST /v1/account/create with name: "My Bot" and type: "exchange". Record the returned account shortname (e.g., my-bot).
3. Fund Subaccount: Call POST /v1/account/transfer/{currency} to move funds from your main account to my-bot.
4. Operate & Trade: Issue orders using the Master key with "account": "my-bot", or issue a dedicated account key scoped to my-bot.
5. Reconcile: Call POST /v1/account/list or POST /v1/balances across subaccounts.

---

Constraints & Requirements

• Prerequisite: Subaccounts and Master API keys require an institutional account group provisioned by Gemini onboarding.
• Shortname Usage: Always use kebab-cased shortnames (e.g., trading-desk-1), not human display names, in the "account" payload parameter.
• Transfers: Internal transfers (POST /v1/account/transfer/{currency}) can only move funds between subaccounts within the same Account Group.
• Roles per Key: Master keys must be granted the required role for the action performed (Administrator for creation/listing, Fund Manager for transfers, Trader for order placement). See Roles.

---

Related Documentation

• Subaccounts Overview — In-depth architectural guide & isolation patterns
• Master API Keys — API key signing mechanics & headers
• Roles & Permissions — Role matrix across Master and Account endpoints
• Create New Account · List Accounts · Transfer Between Accounts