Alpaca Watchlists API

openapi: 3.2.0
info:
  contact:
    email: support@alpaca.markets
    name: Alpaca Support
    url: https://alpaca.markets/support
  description: Alpaca's Trading API is a modern platform for algorithmic trading.
  termsOfService: https://s3.amazonaws.com/files.alpaca.markets/disclosures/library/TermsAndConditions.pdf
  title: Trading Watchlists API
  version: 2.0.1
servers:
- description: Paper
  url: https://paper-api.alpaca.markets
- description: Live
  url: https://api.alpaca.markets
security:
- API_Key: []
  API_Secret: []
tags:
- name: Watchlists
paths:
  /v2/watchlists:
    get:
      description: Returns the list of watchlists registered under the account.
      operationId: getWatchlists
      responses:
        '200':
          content:
            application/json:
              examples:
                example-1:
                  value:
                  - account_id: abe25343-a7ba-4255-bdeb-f7e013e9ee5d
                    created_at: '2022-01-31T21:49:05.14628Z'
                    id: 3174d6df-7726-44b4-a5bd-7fda5ae6e009
                    name: Primary Watchlist
                    updated_at: '2022-01-31T21:49:05.14628Z'
              schema:
                items:
                  $ref: '#/components/schemas/WatchlistWithoutAsset'
                type: array
          description: Successful response
      summary: Get All Watchlists
      tags:
      - Watchlists
    post:
      description: Create a new watchlist with initial set of assets.
      operationId: postWatchlist
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWatchlistRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: Successful response
      summary: Create Watchlist
      tags:
      - Watchlists
  /v2/watchlists/{watchlist_id}:
    parameters:
    - description: watchlist id
      in: path
      name: watchlist_id
      required: true
      schema:
        format: uuid
        type: string
    delete:
      description: Delete a watchlist. This is a permanent deletion.
      operationId: deleteWatchlistById
      responses:
        '204':
          description: No Content
        '404':
          description: Watchlist not found
      summary: Delete Watchlist By Id
      tags:
      - Watchlists
    get:
      description: Returns a watchlist identified by the ID.
      operationId: getWatchlistById
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: Successful response
      summary: Get Watchlist by ID
      tags:
      - Watchlists
    post:
      description: Append an asset for the symbol to the end of watchlist asset list
      operationId: addAssetToWatchlist
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAssetToWatchlistRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: Successful response
      summary: Add Asset to Watchlist
      tags:
      - Watchlists
    put:
      description: Update the name and/or content of watchlist
      operationId: updateWatchlistById
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWatchlistRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: Successful response
      summary: Update Watchlist By Id
      tags:
      - Watchlists
  /v2/watchlists/{watchlist_id}/{symbol}:
    parameters:
    - description: Watchlist ID
      in: path
      name: watchlist_id
      required: true
      schema:
        format: uuid
        type: string
    - description: symbol name to remove from the watchlist content
      in: path
      name: symbol
      required: true
      schema:
        type: string
    delete:
      description: Delete one entry for an asset by symbol name
      operationId: removeAssetFromWatchlist
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: Returns the updated watchlist
      summary: Delete Symbol from Watchlist
      tags:
      - Watchlists
  /v2/watchlists:by_name:
    delete:
      description: Delete a watchlist. This is a permanent deletion.
      operationId: deleteWatchlistByName
      parameters:
      - description: name of the watchlist
        in: query
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
      summary: Delete Watchlist By Name
      tags:
      - Watchlists
    get:
      description: 'You can also call GET, PUT, POST and DELETE with watchlist name with another endpoint /v2/watchlists:by_name and query parameter name=, instead of /v2/watchlists/{watchlist_id} endpoints


        Returns a watchlist by name'
      operationId: getWatchlistByName
      parameters:
      - description: name of the watchlist
        in: query
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: Successful response
      summary: Get Watchlist by Name
      tags:
      - Watchlists
    post:
      description: Append an asset for the symbol to the end of watchlist asset list
      operationId: addAssetToWatchlistByName
      parameters:
      - description: name of the watchlist
        in: query
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAssetToWatchlistRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: Successful response
      summary: Add Asset to Watchlist By Name
      tags:
      - Watchlists
    put:
      description: Update the name and/or content of watchlist
      operationId: updateWatchlistByName
      parameters:
      - description: name of the watchlist
        in: query
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWatchlistRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
          description: Successful response
      summary: Update Watchlist By Name
      tags:
      - Watchlists
components:
  schemas:
    AddAssetToWatchlistRequest:
      description: Request format used for appending an asset to an existing watchlist.
      properties:
        symbol:
          description: the symbol name to add to the watchlist
          example: AAPL
          type: string
      title: AddAssetToWatchlistRequest
      type: object
    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/orders. This `asset_class: ipo` value is distinct from the assets API `attributes: ["ipo"]` flag.'
      enum:
      - us_equity
      - us_option
      - crypto
      - crypto_perp
      - treasury
      - corporate
      - global_equity
      - us_index
      - us_equity_chain
      - ipo
      example: us_equity
      examples:
      - us_equity
      title: AssetClass
      type: string
    WatchlistWithoutAsset:
      description: 'The watchlist API provides CRUD operation for the account''s watchlist. An account can have multiple watchlists and each is uniquely identified by id but can also be addressed by user-defined name.

        '
      examples:
      - account_id: abe25343-a7ba-4255-bdeb-f7e013e9ee5d
        created_at: '2022-01-31T21:49:05.14628Z'
        id: 3174d6df-7726-44b4-a5bd-7fda5ae6e009
        name: Primary Watchlist
        updated_at: '2022-01-31T21:49:05.14628Z'
      properties:
        account_id:
          description: account ID
          format: uuid
          type: string
        created_at:
          format: date-time
          type: string
        id:
          description: watchlist id
          format: uuid
          type: string
        name:
          description: user-defined watchlist name (up to 64 characters)
          minLength: 1
          type: string
        updated_at:
          format: date-time
          type: string
      required:
      - id
      - account_id
      - created_at
      - updated_at
      - name
      title: Watchlist
      type: object
    CreateWatchlistRequest:
      description: Request format used for creating a new watchlist with a set of assets and name.
      properties:
        name:
          description: The watchlist name.
          example: Tech Stocks
          type: string
        symbols:
          description: List of asset symbols to include in the watchlist.
          example:
          - AAPL
          - TSLA
          items:
            type: string
          type: array
      required:
      - name
      title: PostWatchlistRequest
      type: object
    AssetAttribute:
      description: 'Unique characteristic of an 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.'
      enum:
      - ptp_no_exception
      - ptp_with_exception
      - ipo
      - has_options
      - options_late_close
      - fractional_eh_enabled
      - overnight_tradable
      - overnight_halted
      example: ptp_no_exception
      type: string
    Watchlist:
      description: 'The watchlist API provides CRUD operation for the account''s watchlist. An account can have multiple watchlists and each is uniquely identified by id but can also be addressed by user-defined name. Each watchlist is an ordered list of assets.

        '
      examples:
      - account_id: abe25343-a7ba-4255-bdeb-f7e013e9ee5d
        assets:
        - class: us_equity
          easy_to_borrow: true
          exchange: NASDAQ
          fractionable: true
          id: 8ccae427-5dd0-45b3-b5fe-7ba5e422c766
          marginable: true
          name: Tesla, Inc. Common Stock
          shortable: true
          status: active
          symbol: TSLA
          tradable: true
        created_at: '2022-01-31T21:49:05.14628Z'
        id: 3174d6df-7726-44b4-a5bd-7fda5ae6e009
        name: Primary Watchlist
        updated_at: '2022-01-31T21:49:05.14628Z'
      properties:
        account_id:
          description: account ID
          format: uuid
          type: string
        assets:
          description: the content of this watchlist, in the order as registered by the client
          items:
            $ref: '#/components/schemas/Assets'
          type: array
        created_at:
          format: date-time
          type: string
        id:
          description: watchlist id
          format: uuid
          type: string
        name:
          description: user-defined watchlist name (up to 64 characters)
          minLength: 1
          type: string
        updated_at:
          format: date-time
          type: string
      required:
      - id
      - account_id
      - created_at
      - updated_at
      - name
      title: Watchlist
      type: object
    UpdateWatchlistRequest:
      anyOf:
      - required:
        - name
      - required:
        - symbols
      description: Request format used for updating an existing watchlist with a set of assets and/or a name.
      properties:
        name:
          description: The new watchlist name.
          type: string
        symbols:
          description: List of asset symbols to include in the watchlist. The existing assets will be replaced with the new list.
          items:
            type: string
          type: array
      title: PutWatchlistRequest
      type: object
    Assets:
      description: 'The assets API serves as the master list of assets available for trade and data consumption from Alpaca. Assets are sorted by asset class, exchange and symbol. Some assets are only available for data consumption via Polygon, and are not tradable with Alpaca. These assets will be marked with the flag tradable=false.

        '
      examples:
      - borrow_status: easy_to_borrow
        class: us_equity
        easy_to_borrow: true
        exchange: NASDAQ
        fractionable: true
        id: b0b6dd9d-8b9b-48a9-ba46-b9d54906e415
        marginable: true
        name: Apple Inc. Common Stock
        shortable: true
        status: active
        symbol: AAPL
        tradable: true
      properties:
        attributes:
          example:
          - ptp_no_exception
          - ipo
          items:
            $ref: '#/components/schemas/AssetAttribute'
          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'
        cusip:
          description: 'The CUSIP identifier for the asset (US Equities only).

            To request a specific CUSIP, please reach out to Alpaca support.

            '
          example: '987654321'
          type:
          - string
          - 'null'
        exchange:
          $ref: '#/components/schemas/Exchange'
        fractionable:
          description: Asset is fractionable or not
          type: boolean
        id:
          description: Asset ID
          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
          type: boolean
        min_order_size:
          description: Minimum order size. Field available for crypto only.
          format: decimal
          type: string
        min_trade_increment:
          description: Amount a trade quantity can be incremented by. Field available for crypto only.
          format: decimal
          type: string
        name:
          description: The official name of the asset
          minLength: 1
          type: string
        price_increment:
          description: Amount the price can be incremented by. Field available for crypto only.
          format: decimal
          type: string
        shortable:
          description: Asset is shortable or not
          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
          type: boolean
      required:
      - id
      - class
      - exchange
      - symbol
      - name
      - status
      - tradable
      - marginable
      - shortable
      - fractionable
      title: Assets
      type: object
    Exchange:
      description: 'Represents the current exchanges Alpaca supports. List is currently:


        US equities:

        - AMEX

        - ARCA

        - BATS

        - NYSE

        - NASDAQ

        - NYSEARCA

        - OTC

        - TXSE


        Crypto:

        - CRYPTO

        - ERSX

        - CRXL


        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
      - CRYPTO
      - TXSE
      - ERSX
      - CRXL
      - ASCX
      - INDEX
      example: NYSE
      title: Exchange
      type: string
  securitySchemes:
    API_Key:
      description: ''
      in: header
      name: APCA-API-KEY-ID
      type: apiKey
    API_Secret:
      description: ''
      in: header
      name: APCA-API-SECRET-KEY
      type: apiKey
x-readme:
  explorer-enabled: true
  proxy-enabled: false