openapi: 3.1.0
info:
  title: Market Data
  version: v0
  description: tastytrade Market Data API.
  contact:
    name: tastytrade API support
    email: api.support@tastytrade.com
    url: https://developer.tastytrade.com
servers:
  - url: https://api.cert.tastyworks.com
    description: Sandbox
  - url: https://api.tastyworks.com
    description: Production
paths:
  /market-data/by-type:
    get:
      tags:
        - market-data-controller
      summary: Get Quotes By Instrument Type
      operationId: getMarketDataByType
      parameters:
        - name: index
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            default: []
          style: form
          explode: false
          description: Comma-separated list of index symbols.
          example:
            - SPX
        - name: equity
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            default: []
          style: form
          explode: false
          description: Comma-separated list of equity symbols.
          example:
            - AAPL
            - TSLA
        - name: equity-option
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            default: []
          style: form
          explode: false
          description: Comma-separated list of equity option symbols in OCC symbology.
          example:
            - SPY   250428P00355000
        - name: future
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            default: []
          style: form
          explode: false
          description: Comma-separated list of future symbols.
          example:
            - /CLM5
        - name: future-option
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            default: []
          style: form
          explode: false
          description: Comma-separated list of future option symbols.
          example:
            - /MESU5EX3M5 250620C6450
        - name: cryptocurrency
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            default: []
          style: form
          explode: false
          description: Comma-separated list of cryptocurrency symbols.
          example:
            - BTC/USD
      responses:
        "200":
          description: Quotes for the requested symbols, returned as a list of quote
            objects under `data.items`. JSON keys are dasherized and numeric
            prices are returned as decimal strings.
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/MarketData"
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/MarketData"
                    required:
                      - items
                  context:
                    type: string
                    example: /market-data/by-type
                  pagination:
                    type: object
                    description: Paging metadata, present on paginated list responses.
                    properties:
                      per-page:
                        type: integer
                      page-offset:
                        type: integer
                      item-offset:
                        type: integer
                      total-items:
                        type: integer
                      total-pages:
                        type: integer
                      current-item-count:
                        type: integer
                required:
                  - data
                  - context
        "400":
          description: Bad request. A symbol or instrument-type query parameter was
            malformed or could not be parsed. Verify the type parameter keys and
            that symbols follow tastytrade symbology.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
        "401":
          description: "Unauthorized. The access token is missing, expired (tokens last 15
            minutes), or the required `User-Agent: <product>/<version>` header
            was missing or malformed."
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: unauthorized
                    message: No valid access token was provided; access tokens expire after 15
                      minutes.
        "403":
          description: Forbidden. The account or token is not permitted to access this
            resource.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: not_permitted
                    message: User not permitted access
        "429":
          description: Too many requests. Reduce request frequency before retrying. For
            continuous updates, prefer streaming market data over polling.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      description: Fetches real-time REST quotes for multiple securities at once. Pass
        each instrument type as a query parameter (`equity`, `equity-option`,
        `index`, `future`, `future-option`, `cryptocurrency`) whose value is a
        comma-delimited list of symbols in tastytrade symbology. The combined
        number of symbols across all type parameters is capped at 100 per
        request; split larger sets across multiple calls or use the DXLink
        streaming feed instead. Available to funded account holders only; no
        delayed quotes are served over REST. For continuous, low-latency updates
        prefer streaming over polling.
components:
  schemas:
    Instrument:
      type: object
      properties:
        symbol:
          type: string
          description: The instrument's symbol in tastytrade symbology.
          example: AAPL
        instrumentType:
          type: string
          enum:
            - Bond
            - Cryptocurrency
            - Equity
            - Equity Offering
            - Equity Option
            - Fixed Income Security
            - Future
            - Future Option
            - Index
            - Liquidity Pool
            - Mutual Fund
            - Unknown
          description: The type of the instrument.
          example: Equity
        instrumentKey:
          $ref: "#/components/schemas/InstrumentKey"
          description: Compact key (symbol plus instrument type) uniquely identifying this
            instrument.
        underlyingInstrument:
          $ref: "#/components/schemas/Instrument"
          description: For derivatives such as options, the underlying instrument the
            contract derives from.
        rootSymbol:
          type: string
          description: Root symbol shared by related contracts (for example, the product
            root of a future or option).
          example: /CL
        exchange:
          type: string
          enum:
            - EQUITY
            - SMALLS
            - CME
            - CFE
            - CBOED
            - BOND
            - CRYPTOCURRENCY
            - EQUITY_OFFERING
            - UNKNOWN
          description: The exchange or venue category the instrument trades on.
          example: EQUITY
      description: Describes a tradable instrument and, for derivatives, its
        underlying. Used to identify the security a quote applies to.
    InstrumentKey:
      type: object
      properties:
        symbol:
          type: string
          description: The instrument's symbol in tastytrade symbology.
          example: AAPL
        instrumentType:
          type: string
          enum:
            - Bond
            - Cryptocurrency
            - Equity
            - Equity Offering
            - Equity Option
            - Fixed Income Security
            - Future
            - Future Option
            - Index
            - Liquidity Pool
            - Mutual Fund
            - Unknown
          description: The type of the instrument.
          example: Equity
      description: A compact identifier for an instrument, pairing its symbol with its
        instrument type.
    MarketData:
      type: object
      properties:
        symbol:
          type: string
          description: The security symbol in tastytrade symbology (e.g. `AAPL` for an
            equity, `BTC/USD` for a crypto pair, `/CLM5` for a future).
          example: AAPL
        instrumentType:
          type: string
          enum:
            - Bond
            - Cryptocurrency
            - Equity
            - Equity Offering
            - Equity Option
            - Fixed Income Security
            - Future
            - Future Option
            - Index
            - Liquidity Pool
            - Mutual Fund
            - Unknown
          description: The instrument type of the quoted security.
          example: Equity
        updatedAt:
          type: string
          format: date-time
          description: ISO-8601 timestamp of when this quote was last updated.
          example: 2025-04-29T21:33:25.535Z
        bid:
          type: string
          format: decimal
          description: Current best bid price. Decimal value serialized as a JSON string
            (e.g. "150.25").
          example: "210.55"
        bidSize:
          type: string
          format: decimal
          description: Size available at the best bid. Decimal value serialized as a JSON
            string (e.g. "150.25").
          example: "2.0"
        ask:
          type: string
          format: decimal
          description: Current best ask price. Decimal value serialized as a JSON string
            (e.g. "150.25").
          example: "210.6"
        askSize:
          type: string
          format: decimal
          description: Size available at the best ask. Decimal value serialized as a JSON
            string (e.g. "150.25").
          example: "1.0"
        mid:
          type: string
          format: decimal
          description: Midpoint between the best bid and best ask. Decimal value
            serialized as a JSON string (e.g. "150.25").
          example: "210.575"
        mark:
          type: string
          format: decimal
          description: Mark price used for valuation. Decimal value serialized as a JSON
            string (e.g. "150.25").
          example: "210.55"
        last:
          type: string
          format: decimal
          description: Last traded price. Decimal value serialized as a JSON string (e.g.
            "150.25").
          example: "210.511"
        lastExt:
          type: string
          format: decimal
          description: Last traded price including extended-hours trading. Decimal value
            serialized as a JSON string (e.g. "150.25").
          example: "211.05"
        lastMkt:
          type: string
          format: decimal
          description: Last price reported by the regular/primary market. Decimal value
            serialized as a JSON string (e.g. "150.25").
          example: "211.21"
        beta:
          type: string
          format: decimal
          description: Beta of the security relative to the market. Typically present for
            equities. Decimal value serialized as a JSON string (e.g. "150.25").
          example: "1.260672228"
        dividendAmount:
          type: string
          format: decimal
          description: Per-share dividend amount. Typically present for dividend-paying
            equities. Decimal value serialized as a JSON string (e.g. "150.25").
          example: "0.25"
        dividendFrequency:
          type: string
          format: decimal
          description: Number of dividend payments per year. Decimal value serialized as a
            JSON string (e.g. "150.25").
          example: "4.0"
        open:
          type: string
          format: decimal
          description: Opening price for the current session. Decimal value serialized as
            a JSON string (e.g. "150.25").
          example: "208.693"
        dayHighPrice:
          type: string
          format: decimal
          description: Highest traded price during the current session. Decimal value
            serialized as a JSON string (e.g. "150.25").
          example: "212.24"
        dayLowPrice:
          type: string
          format: decimal
          description: Lowest traded price during the current session. Decimal value
            serialized as a JSON string (e.g. "150.25").
          example: "208.37"
        close:
          type: string
          format: decimal
          description: Closing price for the most recent completed session. Decimal value
            serialized as a JSON string (e.g. "150.25").
          example: "211.21"
        closePriceType:
          type: string
          enum:
            - Unknown
            - Regular
            - Indicative
            - Preliminary
            - Final
          description: Qualifier indicating how the close price was derived. Values are
            serialized in title case on the wire (e.g. `Final`, `Regular`).
          example: Final
        prevClose:
          type: string
          format: decimal
          description: Closing price of the prior session. Decimal value serialized as a
            JSON string (e.g. "150.25").
          example: "210.14"
        prevClosePriceType:
          type: string
          enum:
            - Unknown
            - Regular
            - Indicative
            - Preliminary
            - Final
          description: Qualifier indicating how the previous close price was derived.
            Values are serialized in title case on the wire (e.g. `Final`,
            `Regular`).
          example: Final
        summaryDate:
          type: string
          format: date
          description: Session date the summary (close, day high/low) pricing applies to.
          example: 2025-04-29
        prevCloseDate:
          type: string
          format: date
          description: Session date the previous close applies to.
          example: 2025-04-28
        lowLimitPrice:
          type: string
          format: decimal
          description: Lower trading-band limit price for the session, when applicable.
            Decimal value serialized as a JSON string (e.g. "150.25").
          example: "189.77"
        highLimitPrice:
          type: string
          format: decimal
          description: Upper trading-band limit price for the session, when applicable.
            Decimal value serialized as a JSON string (e.g. "150.25").
          example: "231.94"
        tradingHaltedReason:
          type: string
          description: Reason a trading halt is in effect, when the security is halted.
          example: News Pending
        haltStartTime:
          type: integer
          format: int64
          description: Epoch timestamp when a trading halt began, or `-1` when not halted.
          example: -1
        haltEndTime:
          type: integer
          format: int64
          description: Epoch timestamp when a trading halt is expected to end, or `-1`
            when not halted.
          example: -1
        yearLowPrice:
          type: string
          format: decimal
          description: 52-week low price. Decimal value serialized as a JSON string (e.g.
            "150.25").
          example: "169.11"
        yearHighPrice:
          type: string
          format: decimal
          description: 52-week high price. Decimal value serialized as a JSON string (e.g.
            "150.25").
          example: "260.1"
        volume:
          type: string
          format: decimal
          description: Traded volume for the current session. Decimal value serialized as
            a JSON string (e.g. "150.25").
          example: "35348839.0"
        tradingHalted:
          type: boolean
          description: Whether trading in the security is currently halted. Serialized as
            `is-trading-halted` in JSON responses.
          example: false
        lastTradeTime:
          type: integer
          format: int64
          description: Epoch timestamp of the last trade.
          example: 1745962405535
        dayOpen:
          type: string
          format: decimal
          deprecated: true
          description: Decimal value serialized as a JSON string (e.g. "150.25").
        dayHigh:
          type: string
          format: decimal
          deprecated: true
          description: Decimal value serialized as a JSON string (e.g. "150.25").
        dayLow:
          type: string
          format: decimal
          deprecated: true
          description: Decimal value serialized as a JSON string (e.g. "150.25").
        dayClose:
          type: string
          format: decimal
          deprecated: true
          description: Decimal value serialized as a JSON string (e.g. "150.25").
        prevDayClose:
          type: string
          format: decimal
          deprecated: true
          description: Decimal value serialized as a JSON string (e.g. "150.25").
        instrument:
          $ref: "#/components/schemas/Instrument"
          description: The instrument definition for the quoted security, when available.
      description: A real-time quote snapshot for a single security. Returned within
        `data.items` by `GET /market-data/by-type`. JSON keys are dasherized and
        price/size values are serialized as decimal strings. Field availability
        varies by instrument type; for example equities may carry `beta` and
        dividend fields, while some fields are omitted for instruments where
        they do not apply.
x-tastytrade-service:
  serviceName: market-data-cluster-java
  group: market-data
  title: Market Data
tags:
  - name: market-data-controller
