Clear Street Holdings API

openapi: 3.2.0
info:
  title: Common API Models Holdings API
  description: Common API models for all of Studio's APIs
  version: 2.0.0
servers:
- url: https://api.clearstreet.io/studio/v2
  description: Production environment
- url: https://sandbox-api.clearstreet.io/studio/v2
  description: Sandbox environment
tags:
- name: Holdings
  x-displayName: Holdings
paths:
  /accounts/{account_id}/holdings:
    get:
      operationId: listHoldings
      summary: List holdings
      description: List holdings for a given account, filtered on the given query parameters. This endpoint will return either historical or real-time holdings directly from our custodial systems. Positions returned here are can be different than positions returned from the Execution API. While the Execution API returns positions based on trading activity within Studio, our custodial system returns all positions regardless of where trades occur.
      tags:
      - Holdings
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/AccountId'
          description: The account ID or account number to list holdings for.
      - in: query
        name: date
        schema:
          $ref: '#/components/schemas/Date'
          description: The historical date to get holdings for. If omitted, current real-time holdings will be returned.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_id:
                    $ref: '#/components/schemas/AccountId'
                  account_number:
                    $ref: '#/components/schemas/AccountNumber'
                  date:
                    $ref: '#/components/schemas/Date'
                  sod_equity:
                    type: number
                    format: double
                    description: Start of day equity.
                  eod_equity:
                    type: number
                    format: double
                    description: For historical holdings, the end of day equity. Omitted for real-time holdings.
                  timestamp:
                    $ref: '#/components/schemas/Timestamp'
                    description: For real-time holdings, the timestamp reflecting the last update made to the holdings data. Omitted for historical holdings.
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Holding'
                required:
                - account_id
                - account_number
                - date
                - sod_equity
                - data
        default:
          $ref: '#/components/responses/error'
      security:
      - BearerAuth: []
components:
  schemas:
    AccountNumber:
      type: string
      minLength: 1
      maxLength: 256
      example: ACC0001
      description: Account number for the account.
    Timestamp:
      type: integer
      format: int64
      minimum: 1710613560668
      maximum: 2900000000000
      description: Milliseconds since epoch.
    Quantity:
      type: string
      minLength: 1
      maxLength: 16
      example: '100'
      description: String representation of quantity.
    Symbol:
      type: string
      minLength: 1
      maxLength: 32
      example: AAPL
    Date:
      type: integer
      format: int32
      minimum: 20150101
      maximum: 29999999
      example: 20240101
      description: Integer in YYYYMMDD representing a date.
    AssetClass:
      type: string
      enum:
      - other
      - currency
      - equity
      - option
      - debt
      - fund
      description: The asset class of the symbol.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: A URI reference that identifies the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: number
          minimum: 100
          maximum: 599
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          format: uri
          description: An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
      additionalProperties: false
      description: A Problem Details object (RFC 9457)
    Holding:
      type: object
      properties:
        symbol:
          $ref: '#/components/schemas/Symbol'
        symbol_description:
          type: string
          description: Description of the symbol.
        asset_class:
          $ref: '#/components/schemas/AssetClass'
        quantity:
          $ref: '#/components/schemas/Quantity'
          description: The quantity held for the given symbol. This is an EOD quantity if querying historically, else the current real-time quantity for the current date.
        sod_quantity:
          $ref: '#/components/schemas/Quantity'
          description: The quantity held for the given symbol at the start of the day.
      required:
      - symbol
      - asset_class
      - quantity
      - sod_quantity
    AccountId:
      type: string
      minLength: 1
      maxLength: 256
      example: '100000'
      description: Account ID for the account.
  responses:
    error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  url: https://docs.clearstreet.io/
x-tagGroups:
- name: Custodial API
  tags:
  - Performance
  - Holdings
- name: Execution API
  tags:
  - Orders
  - Trades
  - Positions
- name: Lending API
  tags:
  - Locates
  - Rates
  - Inventories
- name: Reference API
  tags:
  - Entities
  - Accounts
  - Instruments
- name: Risk & Margin API
  tags:
  - PNL
  - Margin
  - Margin Simulations