Alpaca Watchlist API

openapi: 3.2.0
info:
  title: Alpaca Watchlist API
  contact:
    email: support@alpaca.markets
    name: Alpaca Support
    url: https://alpaca.markets/support
  termsOfService: https://s3.amazonaws.com/files.alpaca.markets/disclosures/library/TermsAndConditions.pdf
  version: '1.0'
  description: 'Operations tagged Watchlist across 2 of this provider''s published API definitions: alpaca-us-broker-api-openapi.json, alpaca-watchlist-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: Sandbox endpoint
  url: https://broker-api.sandbox.alpaca.markets
- description: Production endpoint
  url: https://broker-api.alpaca.markets
security:
- BasicAuth: []
tags:
- name: Watchlist
paths:
  /v1/trading/accounts/{account_id}/watchlists:
    parameters:
    - description: Unique identifier of an account.
      in: path
      name: account_id
      required: true
      schema:
        format: uuid
        type: string
    get:
      description: Fetch a list of all watchlists currently in an account.
      operationId: getAllWatchlistsForAccount
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/WatchlistWithoutAsset'
                type: array
          description: OK
      summary: Retrieve all Watchlists for an Account
      tags:
      - Watchlist
    post:
      description: Returns the watchlist object
      operationId: createWatchlistForAccount
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWatchlistRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: Newly created watchlist
      summary: Create a New Watchlist for an Account
      tags:
      - Watchlist
    servers:
    - description: Sandbox endpoint
      url: https://broker-api.sandbox.alpaca.markets
    - description: Production endpoint
      url: https://broker-api.alpaca.markets
  /v1/trading/accounts/{account_id}/watchlists/{watchlist_id}:
    parameters:
    - description: Unique identifier of an account
      in: path
      name: account_id
      required: true
      schema:
        format: uuid
        type: string
    - description: Unique identifier of a watchlist
      in: path
      name: watchlist_id
      required: true
      schema:
        format: uuid
        type: string
    delete:
      description: Irrevocably delete a watchlist.
      operationId: deleteWatchlistFromAccountById
      responses:
        '200':
          description: Watchlist deleted.
      summary: Remove a Watchlist
      tags:
      - Watchlist
    get:
      description: Retrieve Watchlist by ID
      operationId: getWatchlistForAccountById
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: OK
      summary: Manage watchlists
      tags:
      - Watchlist
    post:
      description: Adds an asset to an existing watchlist.
      operationId: post-v1-trading-accounts-account_id-watchlists-watchlist_id
      requestBody:
        content:
          application/json:
            schema:
              properties:
                symbol:
                  description: The symbol name to add to the watchlist
                  type: string
              type: object
        description: ''
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: OK
        '404':
          description: The requested watchlist is not found, or one of the symbols is not found in the assets
        '422':
          description: Some parameters are not valid
      summary: Add an Asset to a Watchlist
      tags:
      - Watchlist
    put:
      description: Replace entirely the set of securities contained in the watchlist while optionally renaming it. Destructive operation.
      operationId: replaceWatchlistForAccountById
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWatchlistRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: Updated watchlist.
      summary: Update a Watchlist
      tags:
      - Watchlist
    servers:
    - description: Sandbox endpoint
      url: https://broker-api.sandbox.alpaca.markets
    - description: Production endpoint
      url: https://broker-api.alpaca.markets
  /v1/trading/accounts/{account_id}/watchlists/{watchlist_id}/{symbol}:
    parameters:
    - description: Account identifier.
      in: path
      name: account_id
      required: true
      schema:
        type: string
    - description: The Watchlist ID
      in: path
      name: watchlist_id
      required: true
      schema:
        type: string
    - description: 'The symbol '
      in: path
      name: symbol
      required: true
      schema:
        type: string
    delete:
      description: Delete one entry for an asset by symbol name
      operationId: delete-DELETE-v1-trading-accounts-account_id-watchlists-watchlist_id-symbol
      responses:
        '200':
          description: OK
        '404':
          description: The requested watchlist is not found
      summary: Remove a Symbol from a Watchlist
      tags:
      - Watchlist
    servers:
    - description: Sandbox endpoint
      url: https://broker-api.sandbox.alpaca.markets
    - description: Production endpoint
      url: https://broker-api.alpaca.markets
  /v1/accounts/{account_id}/watchlists/{watchlist_id}:
    parameters:
    - schema:
        type: string
        format: uuid
      name: account_id
      in: path
      required: true
      description: Unique identifier of an account
    - schema:
        type: string
        format: uuid
      name: watchlist_id
      in: path
      required: true
      description: Unique identifier of a watchlist
    servers:
    - url: https://broker-api.sandbox.alpaca.markets
      description: Sandbox endpoint
    - url: https://broker-api.alpaca.markets
      description: Production endpoint
    get:
      summary: Manage watchlists
      tags:
      - Watchlist
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist_2'
      operationId: getV1AccountsByAccountIdWatchlistsByWatchlistId
      description: Fetch a single watchlist by identifier.
      x-operation-id-source: normalized
      x-operation-id-original: getWatchlistForAccountById
    put:
      summary: Update an existing watchlist
      tags:
      - Watchlist
      operationId: putV1AccountsByAccountIdWatchlistsByWatchlistId
      responses:
        '200':
          description: Updated watchlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist_2'
      description: Replace entirely the set of securities contained in the watchlist while optionally renaming it. Destructive operation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWatchlistRequest'
      x-operation-id-source: normalized
      x-operation-id-original: replaceWatchlistForAccountById
    delete:
      summary: Remove a watchlist
      tags:
      - Watchlist
      operationId: deleteV1AccountsByAccountIdWatchlistsByWatchlistId
      responses:
        '200':
          description: Watchlist deleted.
      description: Irrevocably delete a watchlist.
      x-operation-id-source: normalized
      x-operation-id-original: deleteWatchlistFromAccountById
components:
  schemas:
    AssetClass:
      description: 'This represents the category to which the asset belongs to. It serves to identify the nature of the financial instrument, with options including "us_equity" for U.S. equities, "us_option" for U.S. options, "crypto" for cryptocurrencies, and "ipo" for IPO indications of interest. This `asset_class: ipo` value is distinct from the assets API `attributes: ["ipo"]` flag.'
      enum:
      - us_equity
      - us_option
      - us_index
      - crypto
      - crypto_perp
      - ipo
      type: string
    Exchange:
      description: 'Represents the exchange where an asset is traded.


        For Stocks:

        - AMEX

        - ARCA

        - BATS

        - NYSE

        - NASDAQ

        - NYSEARCA

        - OTC

        - TXSE


        For Crypto:

        - CRYPTO

        - ERSX

        - CRXL


        For crypto perpetuals:

        - ASCX


        Index symbols:

        - INDEX


        INDEX is the artificial exchange for index symbols such as SPX.'
      enum:
      - AMEX
      - ARCA
      - BATS
      - NYSE
      - NASDAQ
      - NYSEARCA
      - OTC
      - TXSE
      - CRYPTO
      - ERSX
      - CRXL
      - ASCX
      - INDEX
      example: NASDAQ
      title: Exchange
      type: string
    WatchlistWithoutAsset:
      description: Represents a set of securities observed by a user.
      properties:
        account_id:
          description: 'Unique identifier of the account that owns this watchlist.

            '
          format: uuid
          type: string
        created_at:
          description: When watchlist was created
          format: date-time
          type: string
        id:
          description: 'Unique identifier of the watchlist itself.

            '
          format: uuid
          type: string
        name:
          description: User friendly Name of watchlist
          pattern: ^[a-zA-Z0-9]+$
          type: string
        updated_at:
          description: When watchlist was last updated
          format: date-time
          type: string
      required:
      - id
      - account_id
      - created_at
      - updated_at
      - name
      title: Watchlist
      type: object
    CreateWatchlistRequest:
      description: This model represents the fields you can specify when Creating or Updating/Replacing a Watchlist
      properties:
        name:
          description: The watchlist name
          type: string
        symbols:
          description: The new list of symbol names to watch
          items:
            example: '["AAPL", "TSLA"]'
            type: string
          type: array
      required:
      - name
      - symbols
      title: CreateWatchlistRequest
      type: object
    Watchlist:
      description: Represents a set of securities observed by a user.
      properties:
        account_id:
          description: 'Unique identifier of the account that owns this watchlist.

            '
          format: uuid
          type: string
        assets:
          description: The contents of the watchlist, in the order as registered
          items:
            $ref: '#/components/schemas/Asset'
          type: array
        created_at:
          description: When watchlist was created
          format: date-time
          type: string
        id:
          description: 'Unique identifier of the watchlist itself.

            '
          format: uuid
          type: string
        name:
          description: User friendly Name of watchlist
          pattern: ^[a-zA-Z0-9]+$
          type: string
        updated_at:
          description: When watchlist was last updated
          format: date-time
          type: string
      required:
      - id
      - account_id
      - created_at
      - updated_at
      - name
      title: Watchlist
      type: object
    Asset:
      description: Assets are sorted by asset class, exchange and symbol. Some assets are not tradable with Alpaca. These assets will be marked with the flag tradable=false
      properties:
        attributes:
          description: 'Unique characteristics of the asset. Supported values:

            - `ptp_no_exception`: Asset is a Publicly Traded Partnership (PTP) without a qualified notice; non-U.S. customers may incur 10% withholding on gross proceeds as per IRS guidance, and are blocked from being purchased by default.

            - `ptp_with_exception`: Users can open positions in these PTPs without general restrictions.

            - `ipo`: Accepting limit orders only before the stock begins trading on the secondary market.

            - `has_options`: The underlying equity has listed options available on the platform. Note: if the equity had inactive/expired contracts in the past, this will still show up.

            - `options_late_close`: Indicates the underlying asset''s options contracts close at 4:15pm ET instead of the standard 4:00pm ET.

            - `fractional_eh_enabled`: Indicates the asset accepts fractional orders during extended hours sessions (pre-market, post-market, and overnight if enabled).

            - `overnight_tradable`: Asset is eligible for overnight (24x5) trading in supported venues on the platform.

            - `overnight_halted`: Asset is eligible for overnight trading but is currently halted/blocked for overnight sessions due to risk, corporate action, compliance, or venue constraints.'
          example:
          - ptp_no_exception
          - ipo
          items:
            enum:
            - ptp_no_exception
            - ptp_with_exception
            - ipo
            - has_options
            - options_late_close
            - fractional_eh_enabled
            - overnight_tradable
            - overnight_halted
            type: string
          type: array
        borrow_status:
          description: Borrow status for US equity assets. This field is omitted for non-US-equity assets.
          enum:
          - easy_to_borrow
          - hard_to_borrow
          example: easy_to_borrow
          type: string
        class:
          $ref: '#/components/schemas/AssetClass'
        exchange:
          $ref: '#/components/schemas/Exchange'
        fractionable:
          description: Asset is fractionable or not
          example: true
          type: boolean
        id:
          description: Asset ID
          example: 904837e3-3b76-47ec-b432-046db621571b
          format: uuid
          type: string
        maintenance_margin_requirement:
          deprecated: true
          description: '**deprecated**: Please use margin_requirement_long or margin_requirement_short instead. Note that these fields are of type string.

            Shows the margin requirement percentage for the asset (equities only).

            '
          type: number
        margin_requirement_long:
          description: The margin requirement percentage for the asset's long positions (equities only), encoded as a decimal string.
          example: '100'
          format: decimal
          type: string
        margin_requirement_short:
          description: The margin requirement percentage for the asset's short positions (equities only), encoded as a decimal string.
          example: '30'
          format: decimal
          type: string
        marginable:
          description: Asset is marginable or not
          example: true
          type: boolean
        min_order_size:
          description: Minimum order size.  Field available for crypto only.
          type: string
        min_trade_increment:
          description: Amount a trade quantity can be incremented by. Field available for crypto only.
          type: string
        name:
          description: The official name of the asset
          example: Apple Inc. Common Stock
          type: string
        price_increment:
          description: Amount the price can be incremented by. Field available for crypto only.
          type: string
        shortable:
          description: Asset is shortable or not
          example: true
          type: boolean
        status:
          description: active or inactive
          enum:
          - active
          - inactive
          example: active
          type: string
        symbol:
          description: The symbol of the asset
          example: AAPL
          type: string
        tradable:
          description: Asset is tradable on Alpaca or not
          example: true
          type: boolean
      required:
      - id
      - class
      - exchange
      - symbol
      - name
      - status
      - tradable
      - marginable
      - shortable
      - fractionable
      - margin_requirement_long
      - margin_requirement_short
      title: Asset
      type: object
    Watchlist_2:
      title: Watchlist
      type: object
      description: Represents a set of securities observed by a user.
      properties:
        id:
          type: string
          format: uuid
          description: 'Unique identifier of the watchlist itself.

            '
        account_id:
          type: string
          format: uuid
          description: 'Unique identifier of the account that owns this watchlist.

            '
        created_at:
          type: string
          format: date-time
          description: When watchlist was created
        updated_at:
          type: string
          format: date-time
          description: When watchlist was last updated
        name:
          type: string
          pattern: ^[a-zA-Z0-9]+$
          description: User friendly Name of watchlist
        assets:
          type: array
          description: The contents of the watchlist, in the order as registered
          items:
            $ref: '#/components/schemas/Asset_2'
      required:
      - id
      - name
    AssetClass_2:
      type: string
      enum:
      - us_equity
      - crypto
    Exchange_2:
      type: string
      title: Exchange
      example: NASDAQ
      description: 'Represents the exchange where an asset is traded.


        For Stocks:

        - AMEX

        - ARCA

        - BATS

        - NYSE

        - NASDAQ

        - NYSEARCA

        - OTC


        For Crypto:

        - ERSX

        - FTXU'
      enum:
      - AMEX
      - ARCA
      - BATS
      - NYSE
      - NASDAQ
      - NYSEARCA
      - OTC
      - ERSX
      - FTXU
    Asset_2:
      title: Asset
      type: object
      description: Assets are sorted by asset class, exchange and symbol. Some assets are not tradable with Alpaca. These assets will be marked with the flag tradable=false
      properties:
        id:
          type: string
          example: 904837e3-3b76-47ec-b432-046db621571b
          format: uuid
          description: Asset ID
        class:
          $ref: '#/components/schemas/AssetClass_2'
        exchange:
          $ref: '#/components/schemas/Exchange_2'
        symbol:
          type: string
          example: AAPL
          description: The symbol of the asset
        name:
          type: string
          example: Apple Inc. Common Stock
          description: The official name of the asset
        status:
          type: string
          enum:
          - active
          - inactive
          description: active or inactive
          example: active
        tradable:
          type: boolean
          example: true
          description: Asset is tradable on Alpaca or not
        marginable:
          type: boolean
          example: true
          description: Asset is marginable or not
        shortable:
          type: boolean
          example: true
          description: Asset is shortable or not
        easy_to_borrow:
          type: boolean
          example: true
          description: Asset is easy-to-borrow or not (filtering for easy_to_borrow = True is the best way to check whether the name is currently available to short at Alpaca).
        fractionable:
          type: boolean
          example: true
          description: Asset is fractionable or not
        last_close_pct_change:
          type: string
          format: decimal
          description: 'Percent change for the trading day as of last market closure. NOTE: This field is currently in this spec however it may not be present in the production environment at time of publishing. It will be coming in a future update at which point this spec should be updated.'
        last_price:
          type: string
          format: decimal
          description: 'Most recent available price for this asset on the market. NOTE: This field is currently in this spec however it may not be present in the production environment at time of publishing. It will be coming in a future update at which point this spec should be updated.'
        last_close:
          type: string
          description: 'Last price of the asset upon market closure on the most recent trading day. NOTE: This field is currently in this spec however it may not be present in the production environment at time of publishing. It will be coming in a future update at which point this spec should be updated.'
          format: decimal
      required:
      - id
      - class
      - symbol
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
x-refined-from:
- alpaca-us-broker-api-openapi.json
- alpaca-watchlist-api-openapi.yml
x-readme:
  explorer-enabled: true
  proxy-enabled: false