CBPrimeClient: Institutional Custody & Order Management

CBPrimeClient is the REST client for the Coinbase Prime API — Coinbase’s institutional offering that combines custody, trading, and financing in a single platform. It is scoped to entities and portfolios, with separate endpoints for trading balances, vault balances, wallet management, web3 wallets, and order execution.

Coinbase Prime uses API key + secret + passphrase authentication. No sandbox is available — all API calls interact with the live Prime environment.

Installation

npm install coinbase-api

Instantiation

TypeScript
JavaScript

import { CBPrimeClient } from 'coinbase-api';

const client = new CBPrimeClient({
  apiKey: 'your_prime_api_key',
  apiSecret: 'your_prime_api_secret',
  apiPassphrase: 'your_prime_api_passphrase',
});

const { CBPrimeClient } = require('coinbase-api');

const client = new CBPrimeClient({
  apiKey: 'your_prime_api_key',
  apiSecret: 'your_prime_api_secret',
  apiPassphrase: 'your_prime_api_passphrase',
});

There is no sandbox for Coinbase Prime. All requests are made against the production environment at https://api.prime.coinbase.com.

Activities

Activities capture the history of all operations on a portfolio or entity — orders, transfers, conversions, and more.

Method	Description
`getActivities(params)`	List all activities for a portfolio
`getActivityById(params)`	Retrieve any activity by ID
`getEntityActivities(params)`	List all activities for an entity
`getPortfolioActivityById(params)`	Get an activity scoped to a specific portfolio

// List recent portfolio activities
const activities = await client.getActivities({
  portfolio_id: 'your-portfolio-id',
  page_size: 50,
});

// Get a single activity from any portfolio
const activity = await client.getActivityById({
  activity_id: 'activity-uuid',
});

// Entity-level activity log
const entityActivities = await client.getEntityActivities({
  entity_id: 'your-entity-id',
});

Allocations

Allocations distribute executed fills across sub-portfolios after a block trade. Both standard and net allocation types are supported.

Method	Description
`createPortfolioAllocations(params)`	Create an allocation for a portfolio
`createPortfolioNetAllocations(params)`	Create a net allocation
`getPortfolioAllocations(params)`	List historical allocations
`getAllocationById(params)`	Get a specific allocation
`getNetAllocationsByNettingId(params)`	Get net allocations by netting ID

// List all allocations for a portfolio
const allocations = await client.getPortfolioAllocations({
  portfolio_id: 'your-portfolio-id',
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-01-31T23:59:59Z',
});

const allocation = await client.getAllocationById({
  portfolio_id: 'your-portfolio-id',
  allocation_id: 'allocation-uuid',
});

Balances & Margin

Query buying power, withdrawal limits, margin health, and portfolio-level balances. Balances can be split by type: trading, vault, or total.

Method	Description
`getPortfolioBuyingPower(params)`	Buying power based on holdings and available credit
`getPortfolioWithdrawalPower(params)`	Max withdrawable quantity for an asset
`getPortfolioBalances(params)`	List all portfolio balances by type
`getWalletBalance(params)`	Balance for a specific wallet
`getEntityMargin(params)`	Real-time margin evaluation for an entity
`getEntityMarginSummaries(params)`	Historical margin call summaries
`getPortfolioMarginConversions(params)`	Margin conversions (deprecated — use entity margin summaries)

// Buying power for a product
const power = await client.getPortfolioBuyingPower({
  portfolio_id: 'your-portfolio-id',
  symbol: 'BTC-USD',
});

// Total balances across vault and trading
const balances = await client.getPortfolioBalances({
  portfolio_id: 'your-portfolio-id',
  balance_type: 'TOTAL_BALANCES',
});

// Real-time margin check at entity level
const margin = await client.getEntityMargin({
  entity_id: 'your-entity-id',
});

Orders

All order operations are scoped to a portfolio. Prime supports full order lifecycle management including previews, fills, and cancellations.

Method	Description
`submitOrder(params)`	Create an order for a portfolio
`getOrderPreview(params)`	Preview an order before submitting
`getOpenOrders(params)`	List open orders for a portfolio
`getPortfolioOrders(params)`	List historical orders for a portfolio
`getOrderById(params)`	Get a specific order
`cancelOrder(params)`	Cancel an open order
`getPortfolioFills(params)`	List fills for a portfolio
`getOrderFills(params)`	List fills for a specific order

const order = await client.submitOrder({
  portfolio_id: 'your-portfolio-id',
  product_id: 'BTC-USD',
  side: 'BUY',
  type: 'LIMIT',
  base_quantity: '0.1',
  limit_price: '30000',
  client_order_id: 'my-prime-order-001',
});

Wallets

Custody wallets hold assets within your Prime portfolios. You can create wallets, retrieve balances and deposit instructions, and initiate transfers or withdrawals.

Method	Description
`getPortfolioWallets(params)`	List all wallets for a portfolio
`createWallet(params)`	Create a new wallet
`getWalletById(params)`	Get a specific wallet
`getWalletBalance(params)`	Get the balance of a wallet
`getWeb3WalletBalances(params)`	Get balances for a web3 wallet
`getWalletDepositInstructions(params)`	Get deposit address/instructions
`getWalletTransactions(params)`	List transactions for a wallet
`createTransfer(params)`	Transfer funds between wallets
`createWithdrawal(params)`	Create a withdrawal from a wallet

// List trading wallets
const wallets = await client.getPortfolioWallets({
  portfolio_id: 'your-portfolio-id',
  type: 'TRADING',
});

// Get deposit address for a specific wallet
const instructions = await client.getWalletDepositInstructions({
  portfolio_id: 'your-portfolio-id',
  wallet_id: 'btc-wallet-uuid',
  deposit_type: 'CRYPTO',
});

// Withdraw from a vault wallet
await client.createWithdrawal({
  portfolio_id: 'your-portfolio-id',
  wallet_id: 'vault-wallet-uuid',
  amount: '0.5',
  destination_type: 'CRYPTO_ADDRESS',
  crypto_address: 'your-external-btc-address',
  currency_symbol: 'BTC',
  idempotency_key: 'withdraw-001',
});

Portfolios

Portfolios are the top-level account unit in Prime. Each entity can have multiple portfolios, each with independent balances, orders, and wallets.

Method	Description
`getPortfolios()`	List all portfolios the key has read access to
`getPortfolioById(params)`	Get a portfolio by ID
`getPortfolioCreditInformation(params)`	Get post-trade credit information
`getPortfolioCommission(params)`	Get commission rates
`getPortfolioProducts(params)`	List tradeable products for a portfolio
`getPortfolioTransactions(params)`	List transactions affecting balances
`getTransactionById(params)`	Get a specific transaction
`createConversion(params)`	Convert between assets in a wallet

const portfolios = await client.getPortfolios();

const credit = await client.getPortfolioCreditInformation({
  portfolio_id: 'your-portfolio-id',
});

Financing

Prime offers financing features including interest accruals, locates for short selling, and margin summaries at the entity level.

Method	Description
`getEntityAccruals(params)`	List interest accruals for an entity
`getEntityLocateAvailabilities(params)`	Get available short locates
`getEntityMargin(params)`	Real-time margin evaluation for an entity
`getEntityMarginSummaries(params)`	Historical margin call summaries for an entity
`getEntityTFTieredFees(params)`	Get trade finance tiered pricing fees for an entity
`getPortfolioAccruals(params)`	List interest accruals for a portfolio
`getPortfolioBuyingPower(params)`	Buying power based on holdings and available credit
`getPortfolioLocates(params)`	List existing locates
`getPortfolioMarginConversions(params)`	List margin conversions (deprecated — use entity margin summaries)
`getPortfolioWithdrawalPower(params)`	Max withdrawable quantity for an asset
`getInvoices(params)`	List invoices for an entity

const accruals = await client.getEntityAccruals({
  entity_id: 'your-entity-id',
  start_date: '2024-01-01',
  end_date: '2024-01-31',
});

const locates = await client.getEntityLocateAvailabilities({
  entity_id: 'your-entity-id',
});

Address Book

Manage trusted withdrawal addresses at the portfolio level.

// List trusted addresses
const book = await client.getAddressBook({
  portfolio_id: 'your-portfolio-id',
});

// Add a new trusted address
await client.createAddressBookEntry({
  portfolio_id: 'your-portfolio-id',
  address: '0xYourAddress',
  currency_symbol: 'ETH',
  name: 'Hot Wallet',
});

Assets

// List all assets available for a given entity
const assets = await client.getAssets({
  entity_id: 'your-entity-id',
});

Payment Methods

Retrieve payment methods registered for an entity.

Method	Description
`getEntityPaymentMethods(params)`	List all payment methods for an entity
`getEntityPaymentMethod(params)`	Get a specific payment method by ID

const methods = await client.getEntityPaymentMethods({
  entity_id: 'your-entity-id',
});

const method = await client.getEntityPaymentMethod({
  entity_id: 'your-entity-id',
  payment_method_id: 'pm-uuid',
});

Positions

Query aggregate and individual position data at the entity level.

Method	Description
`getEntityAggregatePositions(params)`	List paginated aggregate positions for an entity
`getEntityPositions(params)`	List paginated positions for an entity

const positions = await client.getEntityPositions({
  entity_id: 'your-entity-id',
  limit: 100,
});

Users

Inspect which users are associated with your entity or portfolio.

Method	Description
`getUsers(params)`	List users for an entity
`getPortfolioUsers(params)`	List users for a portfolio

Get Started

REST Clients

WebSockets

Guides

CBPrimeClient: Institutional Custody & Order Management

Installation

Instantiation

Activities

Allocations

Balances & Margin

Orders

Wallets

Portfolios

Financing

Address Book

Assets

Payment Methods

Positions

Users

Next Steps

International Client

Exchange Client

Build docs developers (and LLMs) love

Get Started

REST Clients

WebSockets

Guides

Documentation Index

​Installation

​Instantiation

​Activities

​Allocations

​Balances & Margin

​Orders

​Wallets

​Portfolios

​Financing

​Address Book

​Assets

​Payment Methods

​Positions

​Users

​Next Steps

International Client

Exchange Client

Build docs developers (and LLMs) love

Installation

Instantiation

Activities

Allocations

Balances & Margin

Orders

Wallets

Portfolios

Financing

Address Book

Assets

Payment Methods

Positions

Users

Next Steps