> ## Documentation Index
> Fetch the complete documentation index at: https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Portfolios: Organize and Track Your Coinbase Assets

> Portfolios let you segment your Coinbase assets and orders into separate groups for strategy isolation, risk management, and performance tracking.

Portfolios give you a way to organize your Coinbase assets and activity into distinct, isolated groups. Rather than managing all your capital in a single flat view, you can create separate portfolios for different trading strategies — for example, one for a long-term accumulation strategy and another for short-term momentum trades. Each portfolio tracks its own balances, open orders, and positions independently, making it easier to measure performance and manage risk at the strategy level.

## What Are Portfolios?

A portfolio is a named container that holds a subset of your Coinbase assets and associates them with specific orders and positions. When you place an order, it is linked to a particular portfolio. Fills, balances, and positions are all scoped to that portfolio, allowing you to:

* **Isolate risk** — a drawdown in one portfolio does not directly affect another
* **Attribute performance** — track returns for each strategy independently
* **Segment capital** — allocate specific amounts of buying power to different approaches

> [!NOTE]
>
> Every Coinbase Advanced Trade account comes with a **default portfolio** that is created automatically. If you do not specify a portfolio when placing an order, the order is associated with your default portfolio.

## Default vs. Custom Portfolios

| Portfolio Type | Description |
| - | - |
| **Default** | Created automatically for every account. Cannot be deleted. All activity goes here unless you explicitly route it to another portfolio. |
| **Custom** | Portfolios you create manually via the API or UI. You can create multiple custom portfolios, name them however you like, and delete them when no longer needed. |

> [!TIP]
>
> Use custom portfolios to implement multi-strategy or multi-account setups cleanly. If you are running a grid bot alongside a trend-following strategy, separate portfolios let you evaluate each strategy's P\&L without mixing their activity.

## Portfolio Fields

**uuid** `string` *required*

The unique identifier for the portfolio. Use this value to associate orders with the portfolio and to retrieve portfolio-specific breakdowns.

**name** `string` *required*

The human-readable name of the portfolio (e.g., `"Momentum Strategy"` or `"BTC Accumulation"`).

**type** `string` *required*

The portfolio type. Possible values:

* `DEFAULT` — The automatically created default portfolio for your account.
* `CONSUMER` — A custom portfolio created by the user for organizing consumer-level trading activity.
* `INTX` — A portfolio associated with Coinbase International Exchange (INTX) for perpetual futures trading.

**deleted** `boolean`

Whether the portfolio has been deleted. Deleted portfolios are no longer active but may still appear in historical data queries. Defaults to `false` for active portfolios.

## Example Portfolio Object

```json theme={null}
{
  "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "name": "Momentum Strategy",
  "type": "CONSUMER",
  "deleted": false
}
```

## Portfolio Breakdown

Beyond the basic portfolio object, the API provides a **portfolio breakdown** — a detailed snapshot of everything held within a portfolio. This includes spot positions, futures positions, and aggregate balance figures. The breakdown is the primary tool for computing your net exposure and P\&L within a strategy.

Key sections of a portfolio breakdown include:

* **`spot_positions`** — An array of individual asset holdings, showing the quantity held, the current value, and unrealized gains or losses for each asset.
* **`perp_positions`** — Perpetual futures positions associated with the portfolio, if applicable.
* **`futures_positions`** — Dated futures positions, if applicable.
* **`portfolio_balances`** — Aggregate balance figures including total value in USD, cash equivalents, and margin usage.

### Example Portfolio Breakdown (Spot Positions)

The following shows a partial portfolio breakdown response, highlighting the `spot_positions` array for a portfolio that holds BTC:

```json theme={null}
{
  "breakdown": {
    "portfolio": {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Momentum Strategy",
      "type": "CONSUMER",
      "deleted": false
    },
    "portfolio_balances": {
      "total_balance": {
        "value": "32716.05",
        "currency": "USD"
      },
      "total_futures_balance": {
        "value": "0",
        "currency": "USD"
      },
      "total_cash_equivalent_balance": {
        "value": "500.00",
        "currency": "USD"
      },
      "total_crypto_balance": {
        "value": "32216.05",
        "currency": "USD"
      }
    },
    "spot_positions": [
      {
        "asset": "BTC",
        "account_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "total_balance_fiat": 32216.05,
        "total_balance_crypto": 0.4925,
        "available_to_trade_fiat": 28000.00,
        "allocation": 0.985,
        "one_day_change": 1.87,
        "cost_basis": {
          "value": "28500.00",
          "currency": "USD"
        },
        "asset_img_url": "https://dynamic-assets.coinbase.com/bitcoin.png",
        "is_primary": true
      }
    ]
  }
}
```

In this breakdown, the portfolio holds approximately **0.4925 BTC** valued at **$32,216.05 USD**, with a cost basis of **$28,500.00**. The `one_day_change` field shows a 1.87% gain over the past 24 hours.

> [!NOTE]
>
> The `allocation` field in a spot position represents the fraction of the portfolio's total crypto balance that this asset accounts for (as a decimal). In the example above, BTC makes up 98.5% of the portfolio's crypto holdings.

## Working with Portfolios in Practice

When you create an order, you can specify the target portfolio using the portfolio's `uuid`. Orders not explicitly assigned to a portfolio fall into the default portfolio. To move assets between portfolios, use the portfolio transfer endpoints.

> [!WARNING]
>
> Deleting a custom portfolio does not automatically cancel open orders or liquidate positions associated with it. Before deleting a portfolio, make sure all open orders are cancelled and any holdings have been transferred or accounted for.

## Relevant API Endpoints

| Endpoint | Description |
| - | - |
| `GET /api/v3/brokerage/portfolios` | List all portfolios for your account |
| `POST /api/v3/brokerage/portfolios` | Create a new custom portfolio |
| `GET /api/v3/brokerage/portfolios/{portfolio_uuid}` | Get a portfolio and its full breakdown |
| `PUT /api/v3/brokerage/portfolios/{portfolio_uuid}` | Edit a portfolio's name |
| `DELETE /api/v3/brokerage/portfolios/{portfolio_uuid}` | Delete a custom portfolio |
| `POST /api/v3/brokerage/portfolios/move_to_portfolio` | Transfer funds between portfolios |

```bash theme={null}
# List all portfolios
curl -X GET "https://api.coinbase.com/api/v3/brokerage/portfolios" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get a portfolio breakdown
curl -X GET "https://api.coinbase.com/api/v3/brokerage/portfolios/b2c3d4e5-f6a7-8901-bcde-f12345678901" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

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

* [List Portfolios](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/api/portfolios/list-portfolios.md)
* [Get Portfolio Breakdown](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/api/portfolios/get-portfolio-breakdown.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.