Coinbase Portfolios API

openapi: 3.2.0
info:
  title: Coinbase Portfolios API
  termsOfService: https://www.coinbase.com/legal/user-agreement
  version: '1.0'
  description: 'Operations tagged Portfolios across 2 of this provider''s published API definitions: coinbase-advanced-trade-openapi.yml, coinbase-prime-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.coinbase.com/api/v3/brokerage
  description: Production Server
- url: https://api.prime.coinbase.com/v1
  description: Production Server
security:
- apiKeyAuth: []
tags:
- name: Portfolios
  description: Create and manage portfolios for organizing trading activity and asset allocation.
paths:
  /portfolios:
    get:
      operationId: listPortfolios
      summary: List portfolios
      description: Retrieves a list of all portfolios associated with the authenticated user. Returns portfolio details including name, UUID, and type.
      tags:
      - Portfolios
      parameters:
      - name: portfolio_type
        in: query
        description: Filter by portfolio type
        schema:
          type: string
          enum:
          - DEFAULT
          - CONSUMER
          - INTX
      responses:
        '200':
          description: Successfully retrieved list of portfolios
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolios:
                    type: array
                    items:
                      $ref: '#/components/schemas/Portfolio'
        '401':
          description: Unauthorized - Invalid or missing authentication
    post:
      operationId: createPortfolio
      summary: Create portfolio
      description: Creates a new portfolio for the authenticated user. Each portfolio provides an isolated trading environment with its own balances.
      tags:
      - Portfolios
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: Name for the new portfolio
      responses:
        '200':
          description: Portfolio successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio:
                    $ref: '#/components/schemas/Portfolio'
        '400':
          description: Bad request - Invalid portfolio parameters
        '401':
          description: Unauthorized - Invalid or missing authentication
    servers:
    - url: https://api.coinbase.com/api/v3/brokerage
      description: Production Server
  /portfolios/{portfolio_id}:
    get:
      operationId: getPortfolio
      summary: Get portfolio breakdown
      description: Retrieves a breakdown of a single portfolio by its ID. Returns detailed information about the portfolio including its balances and positions.
      tags:
      - Portfolios
      parameters:
      - $ref: '#/components/parameters/PortfolioIdParam'
      responses:
        '200':
          description: Successfully retrieved portfolio breakdown
          content:
            application/json:
              schema:
                type: object
                properties:
                  breakdown:
                    $ref: '#/components/schemas/PortfolioBreakdown'
        '401':
          description: Unauthorized - Invalid or missing authentication
        '404':
          description: Portfolio not found
    put:
      operationId: editPortfolio
      summary: Edit portfolio
      description: Updates the name of an existing portfolio. Only the portfolio name can be modified.
      tags:
      - Portfolios
      parameters:
      - $ref: '#/components/parameters/PortfolioIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: Updated name for the portfolio
      responses:
        '200':
          description: Portfolio successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio:
                    $ref: '#/components/schemas/Portfolio'
        '401':
          description: Unauthorized - Invalid or missing authentication
        '404':
          description: Portfolio not found
    delete:
      operationId: deletePortfolio
      summary: Delete portfolio
      description: Deletes a portfolio by its ID. The portfolio must have zero balances before it can be deleted.
      tags:
      - Portfolios
      parameters:
      - $ref: '#/components/parameters/PortfolioIdParam'
      responses:
        '200':
          description: Portfolio successfully deleted
        '401':
          description: Unauthorized - Invalid or missing authentication
        '404':
          description: Portfolio not found
    servers:
    - url: https://api.coinbase.com/api/v3/brokerage
      description: Production Server
  /portfolios/move_funds:
    post:
      operationId: moveFunds
      summary: Move portfolio funds
      description: Moves funds between portfolios owned by the authenticated user. Both the source and target portfolio must belong to the same user.
      tags:
      - Portfolios
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - funds
              - source_portfolio_uuid
              - target_portfolio_uuid
              properties:
                funds:
                  type: object
                  description: Funds to move
                  properties:
                    value:
                      type: string
                      description: Amount to transfer
                    currency:
                      type: string
                      description: Currency of the transfer
                source_portfolio_uuid:
                  type: string
                  description: UUID of the source portfolio
                target_portfolio_uuid:
                  type: string
                  description: UUID of the target portfolio
      responses:
        '200':
          description: Funds successfully moved
        '400':
          description: Bad request - Invalid transfer parameters
        '401':
          description: Unauthorized - Invalid or missing authentication
    servers:
    - url: https://api.coinbase.com/api/v3/brokerage
      description: Production Server
  /portfolios/{portfolio_id}/commission:
    get:
      operationId: getPortfolioCommission
      summary: Get portfolio commission
      description: Retrieves the commission and fee rate structure for a portfolio.
      tags:
      - Portfolios
      parameters:
      - $ref: '#/components/parameters/PortfolioIdParam_2'
      responses:
        '200':
          description: Successfully retrieved commission details
          content:
            application/json:
              schema:
                type: object
                properties:
                  trading_volume:
                    type: string
                    description: Total trading volume
                  fee_tier:
                    type: object
                    properties:
                      maker_fee_rate:
                        type: string
                        description: Maker fee rate
                      taker_fee_rate:
                        type: string
                        description: Taker fee rate
    servers:
    - url: https://api.prime.coinbase.com/v1
      description: Production Server
components:
  schemas:
    Balance:
      type: object
      description: A monetary value with currency
      properties:
        value:
          type: string
          description: Amount as a string to preserve precision
        currency:
          type: string
          description: Currency code
    PortfolioBreakdown:
      type: object
      description: Detailed breakdown of a portfolio
      properties:
        portfolio:
          $ref: '#/components/schemas/Portfolio'
        portfolio_balances:
          type: object
          description: Aggregated balance information
          properties:
            total_balance:
              $ref: '#/components/schemas/Balance'
            total_futures_balance:
              $ref: '#/components/schemas/Balance'
            total_cash_equivalent_balance:
              $ref: '#/components/schemas/Balance'
        spot_positions:
          type: array
          description: Spot positions in the portfolio
          items:
            type: object
            properties:
              asset:
                type: string
                description: Asset symbol
              account_uuid:
                type: string
                description: Account UUID
              total_balance_fiat:
                type: number
                description: Total balance in fiat
              total_balance_crypto:
                type: number
                description: Total balance in crypto
    Portfolio:
      type: object
      description: A user portfolio for organizing trading activity
      properties:
        uuid:
          type: string
          format: uuid
          description: Unique identifier for the portfolio
        name:
          type: string
          description: Name of the portfolio
        type:
          type: string
          description: Portfolio type
          enum:
          - DEFAULT
          - CONSUMER
          - INTX
        deleted:
          type: boolean
          description: Whether the portfolio has been deleted
    Portfolio_2:
      type: object
      description: An institutional trading portfolio
      properties:
        id:
          type: string
          description: Portfolio identifier
        name:
          type: string
          description: Portfolio name
        entity_id:
          type: string
          description: Entity ID associated with the portfolio
        organization_id:
          type: string
          description: Organization identifier
  parameters:
    PortfolioIdParam:
      name: portfolio_id
      in: path
      required: true
      description: Unique identifier for the portfolio
      schema:
        type: string
        format: uuid
    PortfolioIdParam_2:
      name: portfolio_id
      in: path
      required: true
      description: Portfolio identifier
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: CB-ACCESS-KEY
      description: Coinbase API key authentication using HMAC SHA-256 signatures. Requires CB-ACCESS-KEY, CB-ACCESS-SIGN, and CB-ACCESS-TIMESTAMP headers.
x-refined-from:
- coinbase-advanced-trade-openapi.yml
- coinbase-prime-openapi.yml