Advanced Trade API Accounts: Balances and Holdings

Accounts represent your asset balances on Coinbase. Each account holds a single currency and tracks available and held balances for trading.

Accounts are the foundation of your Coinbase Advanced Trade setup. Every asset you hold — whether Bitcoin, Ether, US Dollars, or any other supported currency — lives in its own dedicated account. When you place trades, deposit funds, or receive payouts, your account balances update to reflect those changes in real time. Understanding how accounts work helps you accurately track your capital and build reliable trading logic.

What Is an Account?

Each account on Coinbase holds a single currency. You might have one account for BTC, another for ETH, and a third for USD. You can hold any number of accounts across different currencies, and each is independently identified, queried, and managed through the API.

Accounts are referenced by their uuid — a unique identifier that remains stable over time. You should store and use this uuid in your application rather than relying on account names, which can change.

Key Account Fields

uuid · string · required

The unique identifier for the account. Use this value to reference the account in API requests.

name · string

A human-readable label for the account (e.g., "BTC Wallet"). Names may change and should not be used as a stable identifier.

currency · string · required

The currency this account holds (e.g., "BTC", "ETH", "USD"). Each account holds exactly one currency.

available_balance · object · required

The portion of your balance that is free to use for new orders or withdrawals.

Show available_balance fields

value · string

The numeric balance as a string (e.g., "0.5").

currency · string

The currency of the balance value (e.g., "BTC").

hold · object · required

The portion of your balance currently reserved and unavailable for new orders.

Show hold fields

value · string

The numeric held amount as a string (e.g., "0.1").

currency · string

The currency of the held amount.

default · boolean

Indicates whether this is the default account for its currency. Coinbase automatically designates one account per currency as the default.

active · boolean

Whether the account is currently active and usable for trading.

type · string

The account type. Common values include ACCOUNT_TYPE_CRYPTO and ACCOUNT_TYPE_FIAT.

ready · boolean

Indicates whether the account is fully set up and ready for transactions.

Available Balance vs. Hold

Your total balance is split into two parts:

• available_balance — Funds you can use right now. This is the amount available to place new orders, transfer, or withdraw.
• hold — Funds that are temporarily locked because they are committed to open orders. For example, if you place a limit buy order for 0.1 BTC worth of USD, that USD amount moves into hold until the order fills, cancels, or expires.

Once an open order resolves — whether it fills, is cancelled, or expires — the held funds are released back into your available_balance.

Your effective “total balance” for a currency is available_balance.value + hold.value. The API does not surface a combined total field directly, so calculate it yourself when you need a full picture of your holdings.

Working with Multiple Accounts

You can hold multiple accounts across different currencies at the same time. For example, a typical trading setup might include:

• A USD fiat account for purchasing
• A BTC crypto account for holdings
• An ETH crypto account for a separate strategy

Each of these accounts is returned as a separate object by the API. When building a portfolio dashboard or routing an order, always look up the correct account uuid for the currency you intend to use.

Cache account UUIDs at startup rather than fetching them on every request. Account UUIDs are stable and rarely change, so a single list call at application startup is usually sufficient.

Example Account Object

Below is a representative account object for a BTC wallet with a split between available and held funds:

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "BTC Wallet",
  "currency": "BTC",
  "available_balance": {
    "value": "0.5",
    "currency": "BTC"
  },
  "default": true,
  "active": true,
  "created_at": "2023-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z",
  "type": "ACCOUNT_TYPE_CRYPTO",
  "ready": true,
  "hold": {
    "value": "0.1",
    "currency": "BTC"
  }
}

In this example, the account holds a total of 0.6 BTC — 0.5 BTC is available to use, while 0.1 BTC is currently locked in one or more open orders.

Relevant API Endpoints

Use the following endpoints to retrieve account data:

Endpoint	Description
GET /api/v3/brokerage/accounts	List all accounts associated with your profile
GET /api/v3/brokerage/accounts/{account_uuid}	Retrieve a single account by its UUID

Both endpoints require a valid JWT Bearer token in the Authorization header.

# List all accounts
curl -X GET "https://api.coinbase.com/api/v3/brokerage/accounts" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get a specific account
curl -X GET "https://api.coinbase.com/api/v3/brokerage/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

The list endpoint supports pagination via limit and cursor query parameters. If you have many accounts, iterate through pages using the cursor value returned in each response.

For full request and response schemas, see the API reference:

• List Accounts
• Get Account