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