openapi: 3.1.0
info:
  title: Charles Schwab Market Data API
  description: >-
    REST API for retrieving real-time and historical market data from
    Charles Schwab including quotes, option chains, price history, market
    hours, instrument metadata, and movers for major US indices.
  version: '1.0'
  contact:
    name: Schwab Developer Support
    url: https://developer.schwab.com/contact-us
externalDocs:
  description: Schwab Market Data API Documentation
  url: https://developer.schwab.com/products/trader-api--individual
servers:
  - url: https://api.schwabapi.com/marketdata/v1
    description: Schwab Market Data Production
tags:
  - name: Quotes
    description: Real-time and delayed quote data
  - name: Options
    description: Option chain and expiration data
  - name: Price History
    description: Historical price candles
  - name: Movers
    description: Top movers within indexes
  - name: Market Hours
    description: Market hours by product
  - name: Instruments
    description: Instrument metadata search
security:
  - oauth2: []
paths:
  /quotes:
    get:
      operationId: getQuotes
      summary: Get quotes for one or more symbols
      tags:
        - Quotes
      parameters:
        - name: symbols
          in: query
          required: true
          description: Comma-separated list of ticker symbols.
          schema:
            type: string
        - name: fields
          in: query
          schema:
            type: string
        - name: indicative
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Quote data keyed by symbol
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Quote'
  /{symbol_id}/quotes:
    get:
      operationId: getQuote
      summary: Get quote for a specific symbol
      tags:
        - Quotes
      parameters:
        - name: symbol_id
          in: path
          required: true
          schema:
            type: string
        - name: fields
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Quote
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
  /chains:
    get:
      operationId: getOptionChains
      summary: Get option chain for a symbol
      tags:
        - Options
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: contractType
          in: query
          schema:
            type: string
            enum: [CALL, PUT, ALL]
        - name: strikeCount
          in: query
          schema:
            type: integer
        - name: includeQuotes
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Option chain
  /expirationchain:
    get:
      operationId: getOptionExpirationChain
      summary: Get option expiration chain for a symbol
      tags:
        - Options
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Expiration chain
  /pricehistory:
    get:
      operationId: getPriceHistory
      summary: Get price history candles for a symbol
      tags:
        - Price History
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: periodType
          in: query
          schema:
            type: string
            enum: [day, month, year, ytd]
        - name: period
          in: query
          schema:
            type: integer
        - name: frequencyType
          in: query
          schema:
            type: string
            enum: [minute, daily, weekly, monthly]
        - name: frequency
          in: query
          schema:
            type: integer
        - name: startDate
          in: query
          schema:
            type: integer
            description: Epoch milliseconds
        - name: endDate
          in: query
          schema:
            type: integer
            description: Epoch milliseconds
      responses:
        '200':
          description: Candle history
  /movers/{symbol_id}:
    get:
      operationId: getMovers
      summary: Get top movers for an index
      tags:
        - Movers
      parameters:
        - name: symbol_id
          in: path
          required: true
          description: Index symbol such as $DJI, $COMPX, or $SPX.
          schema:
            type: string
        - name: sort
          in: query
          schema:
            type: string
            enum: [VOLUME, TRADES, PERCENT_CHANGE_UP, PERCENT_CHANGE_DOWN]
        - name: frequency
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Movers list
  /markets:
    get:
      operationId: getMarketHours
      summary: Get market hours for one or more markets
      tags:
        - Market Hours
      parameters:
        - name: markets
          in: query
          required: true
          schema:
            type: string
        - name: date
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Market hours
  /markets/{market_id}:
    get:
      operationId: getMarketHoursForMarket
      summary: Get market hours for a single market
      tags:
        - Market Hours
      parameters:
        - name: market_id
          in: path
          required: true
          schema:
            type: string
            enum: [equity, option, bond, future, forex]
        - name: date
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Market hours
  /instruments:
    get:
      operationId: searchInstruments
      summary: Search instruments by symbol or CUSIP
      tags:
        - Instruments
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: projection
          in: query
          required: true
          schema:
            type: string
            enum: [symbol-search, symbol-regex, desc-search, desc-regex, fundamental]
      responses:
        '200':
          description: Instrument metadata
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.schwabapi.com/v1/oauth/authorize
          tokenUrl: https://api.schwabapi.com/v1/oauth/token
          scopes:
            api: Access Schwab Trader and Market Data APIs
  schemas:
    Quote:
      type: object
      properties:
        symbol:
          type: string
        bidPrice:
          type: number
        askPrice:
          type: number
        lastPrice:
          type: number
        openPrice:
          type: number
        highPrice:
          type: number
        lowPrice:
          type: number
        netChange:
          type: number
        totalVolume:
          type: integer
        quoteTime:
          type: integer
          description: Epoch milliseconds
        tradeTime:
          type: integer
          description: Epoch milliseconds