Skip to main content

​
Entities and Portfolios

Coinbase Prime uses a hierarchical account structure with three levels: organizations, entities, and portfolios. This structure supports both simple trading setups and complex institutional arrangements.
  • Organization: The top-level container for all your Prime accounts, typically representing your company or institution.
  • Entity: A business unit within your organization, often used for different legal structures, geographical locations, or business divisions
  • Portfolio: Individual trading accounts and vault wallets within an entity, used to segregate different strategies, teams, or purposes. User permissions are defined at this level.
Every Prime account begins with one portfolio under a single entity. You can add multiple portfolios within the same entity to separate trading strategies, user groups, or operational needs. Additional entities can be created for different domiciles or separate legal structures, with all entities from the same onboarding process rolling up into one organization.

​
API Key Hierarchy

API keys operate at three different scopes, each providing different levels of access: Portfolio-level keys: Access only the specific portfolio they’re created for. Required for Orders WebSocket and FIX connections. Created in the Prime UI. Entity-level keys: Can perform REST API requests and subscribe to order book data via WebSocket on any portfolio within their entity. Created in the Prime UI. Organization-level keys: Can perform REST API requests and subscribe to order book data via WebSocket across all portfolios across all entities within the organization. Can only be generated by emailing primeops@coinbase.com. API keys also support IP allowlisting for enhanced security, allowing you to restrict access to specific IP addresses or CIDR ranges.

​
API Key Scopes

Through API scopes, Prime supports advanced operations for permissions setting, specifically by category or endpoint. For each API endpoint category (e.g. wallets, products, activities, etc), Prime supports setting API key scopes at a variety of complexities:
  1. Endpoint specific: Granular control where specific endpoints are allowed (e.g., get wallet balance is allowed but get portfolio balances isn’t)
  2. Category-level READ/WRITE: All endpoints of a specific operation type within a category (e.g., all READ orders endpoints but no WRITE orders endpoints)
  3. ALL READ / ALL WRITE: Broad access that includes all categories for the specified operation type
This system is designed to work for both existing and future endpoints, so there is no need for further scoping in scenarios 2 and 3 as new endpoints are added. Since most REST API calls require an Entity ID or Portfolio ID, your first API call should be List Portfolios to retrieve these identifiers and understand your account structure.
  • Java
  • .NET
  • Go
  • Python
  • CLI
  • TS/JS
PortfoliosService portfoliosService = PrimeServiceFactory.createPortfoliosService(client);

ListPortfoliosResponse response = portfoliosService.listPortfolios();
To learn more about this SDK, please visit the Prime Java SDK.
Most endpoints are scoped to the portfolio level, so they require a Portfolio ID. These include placing an order or creating a withdrawal. Examples of endpoints that are scoped to the entity level include listing payment methods, listing assets, and listing users.

​
Supported Assets

An asset can be any cryptocurrency (e.g., BTC) or fiat currency (e.g., USD) supported by Coinbase Prime. This is different from a product, which is a tradable pair of assets (e.g., BTC-USD). To retrieve a list of supported assets along with important metadata (precision, supported networks, etc.), call List Assets. This endpoint covers all assets at the entity level, so an Entity ID is required.
  • Java
  • .NET
  • Go
  • Python
  • TS/JS
  • CLI
AssetsService assetsService = PrimeServiceFactory.createAssetsService(client);

ListAssetsRequest request = new ListAssetsRequest.Builder()
    .entityId("ENTITY_ID_HERE")
    .build();

ListAssetsResponse response = assetsService.listAssets(request);
To learn more about this SDK, please visit the Prime Java SDK.
Please note: All requests discussed above require proper authentication. For more information, visit REST API Authentication.
⌘I