openapi: 3.0.2
info:
  title: DriveWealth Accounts Positions API
  version: '1.0'
servers:
- url: https://bo-api.drivewealth.io/back-office
  description: Sandbox server (Uses test data)
- url: https://bo-api.drivewealth.net/back-office
  description: Production Server (Uses LIVE data)
tags:
- name: Positions
  x-displayName: Positions
paths:
  /accounts/{accountID}/summary/positions:
    get:
      tags:
      - Positions
      parameters:
      - in: path
        name: accountID
        schema:
          $ref: '#/components/schemas/accountID'
        required: true
      summary: List Account Positions
      description: Retrives a list of Account Positions by accountID
      responses:
        '200':
          description: Retrieving an Account's Positions by accountID was Successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionsRes'
      security:
      - bearerAuth: []
        dwAppKey: []
      - sessionToken: []
        dwAppKey: []
  /accounts/{accountID}/options/positions:
    get:
      tags:
      - Positions
      parameters:
      - in: path
        name: accountID
        schema:
          $ref: '#/components/schemas/accountID'
        required: true
      - in: query
        name: filterBy
        schema:
          type: string
        example: expirationDate
        description: The expiration date of options; to filter by.
      - in: query
        name: from
        schema:
          type: string
        example: '2023-02-16'
        description: The start date of the range of option's expiration.
      - in: query
        name: to
        schema:
          type: string
        required: false
        example: '2023-02-16'
        description: The end date of the range of option's expiration.
      - in: query
        name: limit
        schema:
          type: number
          default: 50
        required: false
        example: 10
        description: The number of results to be returned.
      - in: query
        name: offset
        schema:
          type: string
        required: false
        example: 86572e14-84ae-4f0c-9533-3c9432637f8e.1627500314555#65d1aee9-9a6c-4720-9879-71c4fcf43060.2023-12-07T21:17:45.743Z
        description: The identifier of the page.
      summary: Retrieve Account Option Positions
      description: Retrieves Account Option Positions
      responses:
        '200':
          description: Retrieving Account Option Positions was Successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptPositionRes'
      security:
      - bearerAuth: []
        dwAppKey: []
      - sessionToken: []
        dwAppKey: []
components:
  schemas:
    debtPositionsObj:
      type: object
      properties:
        symbol:
          $ref: '#/components/schemas/instrumentSymbol'
        instrumentID:
          $ref: '#/components/schemas/instrumentID'
        ISIN:
          $ref: '#/components/schemas/instrumentISIN'
        instrumentType:
          $ref: '#/components/schemas/instrumentType'
        openQty:
          type: number
          example: 31.65120151
          description: Quantity of shares owned by the account.
        costBasis:
          type: number
          example: 975.98
          description: Cost basis of the position.
        marketValue:
          type: number
          example: 4540.36
          description: Current market value of the position.
        side:
          type: string
          example: B
          description: 'In this case, Side distinguishes the type of position. This will always return ''long''(B). '
          enum:
          - B
        priorClose:
          type: number
          example: 144.29
          description: The prior closing price of the security.
        availableForTradingQty:
          type: number
          example: 31.65120151
          description: The quantity of the security available for sale.
        avgPrice:
          type: number
          example: 30.84
          description: The average price of the position.
    OptPosition:
      type: object
      properties:
        expirationDate:
          type: string
          example: '2018-09-18'
          description: The date the Option contract will expire.
          format: date
        position:
          $ref: '#/components/schemas/Position'
        instrument:
          $ref: '#/components/schemas/Instrument'
    equityValue:
      type: number
      format: double
      example: 34275565.44
      description: The current total market value of the account's open equity positions.
    sideAbbreviated:
      type: string
      example: B
      description: The side of the order.
      enum:
      - B
      - S
      - BUY_OPEN
      - BUY_CLOSE
      - SELL_OPEN
      - SELL_CLOSE
    positionsValue:
      type: number
      format: double
      example: 34287911.11
      description: The current total market value of the account's open positions.
    accountID:
      type: string
      example: cc07f91b-7ee1-4868-b8fc-823c70a1b932.1407775317759
      description: The user's unique account identifier.
    Instrument:
      type: object
      properties:
        rootSymbol:
          type: string
          example: AAPL
          description: The ticker symbol of the underlying Instrument from which this Option is derived.
        rootId:
          $ref: '#/components/schemas/rootId'
        symbol:
          $ref: '#/components/schemas/instrumentSymbol'
        optionType:
          $ref: '#/components/schemas/optionType'
        marketPrice:
          type: number
          example: 16.5
          description: The market price of the option.
        strikePrice:
          type: number
          example: 16.5
          description: The strike price of the option.
    equityPositionsObj:
      type: object
      properties:
        symbol:
          $ref: '#/components/schemas/instrumentSymbol'
        instrumentID:
          $ref: '#/components/schemas/instrumentID'
        ISIN:
          $ref: '#/components/schemas/instrumentISIN'
        instrumentType:
          $ref: '#/components/schemas/instrumentType'
        openQty:
          type: number
          example: 31.65120151
          description: Quantity of shares owned by the account.
        costBasis:
          type: number
          example: 975.98
          description: Cost basis of the position.
        marketValue:
          type: number
          example: 4540.36
          description: Current market value of the position.
        side:
          type: string
          example: B
          description: 'In this case, Side distinguishes the type of position. This will always return ''long''(B). '
          enum:
          - B
        priorClose:
          type: number
          example: 144.29
          description: The prior closing price of the security.
        availableForTradingQty:
          type: number
          example: 31.65120151
          description: The quantity of the security available for sale.
        avgPrice:
          type: number
          example: 30.84
          description: The average price of the position.
        mktPrice:
          type: number
          example: 143.45
          description: The current market price of the position.
        unrealizedPL:
          type: number
          example: 3564.38
          description: Unrealized profit and loss for position.
        unrealizedDayPLPercent:
          type: number
          example: -0.58
          description: Unrealized day profit and loss for position in percent.
        unrealizedDayPL:
          type: number
          example: -26.59
          description: Unrealized day profit and loss for position.
    mutualFundsPositionsObj:
      type: object
      properties:
        symbol:
          $ref: '#/components/schemas/instrumentSymbol'
        instrumentID:
          $ref: '#/components/schemas/instrumentID'
        ISIN:
          $ref: '#/components/schemas/instrumentISIN'
        instrumentType:
          $ref: '#/components/schemas/instrumentType'
        openQty:
          type: number
          example: 31.65120151
          description: Quantity of shares owned by the account.
        costBasis:
          type: number
          example: 975.98
          description: Cost basis of the position.
        marketValue:
          type: number
          example: 4540.36
          description: Current market value of the position.
        side:
          type: string
          example: B
          description: 'In this case, Side distinguishes the type of position. This will always return ''long''(B). '
          enum:
          - B
        priorClose:
          type: number
          example: 144.29
          description: The prior closing price of the security.
        availableForTradingQty:
          type: number
          example: 31.65120151
          description: The quantity of the security available for sale.
        avgPrice:
          type: number
          example: 30.84
          description: The average price of the position.
    instrumentType:
      type: string
      example: EQUITY
      description: The classification of the instrument.
      enum:
      - EQUITY
      - ALTERNATIVE_ASSET
      - MUTUAL_FUND
      - DEBT
      - OPTION
      - CRYPTO
    optionType:
      type: string
      example: PUT
      description: The type of Option.
      enum:
      - CALL
      - PUT
    PositionsRes:
      type: object
      properties:
        accountID:
          $ref: '#/components/schemas/accountID'
        accountNo:
          $ref: '#/components/schemas/accountNo'
        tradingType:
          $ref: '#/components/schemas/tradingType'
        updated:
          type: string
          example: '2017-06-16T15:35:30.617Z'
          description: Time of last update.
        equityValue:
          $ref: '#/components/schemas/equityValue'
        optionsValue:
          $ref: '#/components/schemas/optionsValue'
        debtValue:
          $ref: '#/components/schemas/debtValue'
        positionsValue:
          $ref: '#/components/schemas/positionsValue'
        equityPositions:
          type: array
          description: An array of the positions in the account.
          items:
            $ref: '#/components/schemas/equityPositionsObj'
        optionsPositions:
          type: array
          description: An array of the options positions in the account.
          items:
            $ref: '#/components/schemas/optionsPositionsObj'
        mutualFundsPositions:
          type: array
          description: An array of the mutual funds positions in the account.
          items:
            $ref: '#/components/schemas/mutualFundsPositionsObj'
        debtPositions:
          type: array
          description: An array of the debt positions in the account.
          items:
            $ref: '#/components/schemas/debtPositionsObj'
    optionsPositionsObj:
      type: object
      properties:
        symbol:
          $ref: '#/components/schemas/instrumentSymbol'
        instrumentID:
          $ref: '#/components/schemas/instrumentID'
        ISIN:
          $ref: '#/components/schemas/instrumentISIN'
        instrumentType:
          $ref: '#/components/schemas/instrumentType'
        openQty:
          type: number
          example: 31.65120151
          description: Quantity of shares owned by the account.
        costBasis:
          type: number
          example: 975.98
          description: Cost basis of the position.
        marketValue:
          type: number
          example: 4540.36
          description: Current market value of the position.
        side:
          type: string
          example: B
          description: 'In this case, Side distinguishes the type of position. This will always return ''long''(B). '
          enum:
          - B
        priorClose:
          type: number
          example: 144.29
          description: The prior closing price of the security.
        availableForTradingQty:
          type: number
          example: 31.65120151
          description: The quantity of the security available for sale.
        avgPrice:
          type: number
          example: 30.84
          description: The average price of the position.
        mktPrice:
          type: number
          example: 440.75
          description: The current market price of the position.
        unrealizedPL:
          type: number
          example: 14.24
          description: The unrealized profit and loss for the position.
        unrealizedDayPLPercent:
          type: number
          example: 1.65
          description: The unrealized day profit and loss for position in percent.
        unrealizedDayPL:
          type: number
          example: 0.54
          description: The unrealized day profit and loss for the position.
    debtValue:
      type: number
      format: double
      example: 12345.67
      description: The current total market value of the account's open debt positions.
    instrumentSymbol:
      type: string
      nullable: true
      example: MS
      description: The ticker symbol of the Instrument. Debt Instruments and Global Mutual Funds do not have symbols and are referred to buy their `instrumentID` or `ISIN`.
    tradingType:
      type: string
      example: CASH
      description: The type of trading the account will participate in.
      enum:
      - CASH
      - MARGIN
    accountNo:
      type: string
      example: DWBG000052
      description: The user's unique account number, that is human readable.
    instrumentISIN:
      description: An `International Securities Identification Number` (ISIN) uniquely identifies a security. Its structure is defined in ISO 6166. ISINs are commonly used when an Instrument does not have a `symbol`, such as Debt Instruments and Global Mutual Funds.
      type: string
      minLength: 12
      maxLength: 14
      example: US023135BX34
    Position:
      type: object
      properties:
        accountID:
          $ref: '#/components/schemas/accountID'
        accountNo:
          $ref: '#/components/schemas/accountNo'
        costBasis:
          type: number
          example: 975.98
          description: The cost basis of the position.
        effectivePx:
          type: number
          example: 975.98
          description: The effective price of the position.
        execID:
          type: string
          example: '170638430890297892000'
          description: The execution ID of the position.
        initPx:
          type: number
          example: 975.98
          description: The initial price of the position.
        initQty:
          type: number
          example: 0.01
          description: The initial quantity of the position.
        instrumentID:
          $ref: '#/components/schemas/instrumentID'
        side:
          $ref: '#/components/schemas/sideAbbreviated'
        openQty:
          type: number
          example: 10
          description: The quantity of shares owned by the account.
        comment:
          type: string
          example: TOP
          description: A comment describing the position
    instrumentID:
      type: string
      format: uuid
      example: 3fb1e8a9-f7d5-4d90-95e2-43e7326b5636
      description: 'A unique ID created by DriveWealth to identify a specific instrument. '
    optionsValue:
      type: number
      format: double
      example: 12345.67
      description: The current total market value of the account's open option positions.
    rootId:
      type: string
      example: 3fb1e8a9-f7d5-4d90-95e2-43e7326b5636
      description: A unique ID created by DriveWealth to identify a specific Instrument that this Option is derived from.
    OptPositionRes:
      type: object
      properties:
        data:
          type: array
          description: An array of the options positions in the account.
          items:
            oneOf:
            - $ref: '#/components/schemas/OptPosition'
        nextPageOffset:
          type: string
          example: 86572e14-84ae-4f0c-9533-3c9432637f8e.1627500314555#65d1aee9-9a6c-4720-9879-71c4fcf43060.2023-12-07T21:17:45.743Z
          description: The next page offset.
        prevPageOffset:
          type: string
          example: 86572e14-84ae-4f0c-9533-3c9432637f8e.1627500314555#65d1aee9-9a6c-4720-9879-71c4fcf43060.2023-12-07T21:17:45.743Z
          description: The previous page offset.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    dwAppKey:
      type: apiKey
      in: header
      name: dw-client-app-key
    sessionToken:
      type: apiKey
      in: header
      name: dw-auth-token