> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amberdata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Historical

> Provides detailed historical trade data for a specific options instrument, including the trade's timestamp, side (buy or sell), price, volume, and other relevant metrics like the index price, mark price, and implied volatility (IV) at the time of the trade.

<Warning>
  The maximum time range (difference between `startDate` and `endDate`) is **1 hour**.
</Warning>

<Note>
  If the `startDate` and `endDate` query parameters are not provided, the API will return the data from the previous 1 hour.
</Note>


## OpenAPI

````yaml get /options/trades/{instrument}
openapi: 3.1.0
info:
  title: market-api
  version: '2'
servers:
  - url: https://api.amberdata.com/markets
security:
  - ApiKeyAuth: []
paths:
  /options/trades/{instrument}:
    get:
      summary: Historical
      description: >-
        Provides detailed historical trade data for a specific options
        instrument, including the trade's timestamp, side (buy or sell), price,
        volume, and other relevant metrics like the index price, mark price, and
        implied volatility (IV) at the time of the trade.
      operationId: options-trades-historical
      parameters:
        - name: instrument
          in: path
          description: The instrument for which to retrieve the requested data.
          schema:
            type: string
            default: BTC-27DEC24-100000-C
          required: true
        - name: exchange
          in: query
          description: >-
            **[Required]** The exchange(s) for which to retrieve the requested
            data (comma separated). **[Default]** All available exchanges.
          required: true
          schema:
            type: string
            default: deribit
        - name: startDate
          in: query
          description: >-
            **[Optional]** Payload only includes data after this date
            (inclusive). **[Defaults]** Beginning of the current hour (max time
            range is 1 hour). **[Formats]** `seconds | milliseconds | iso8601`
            **[Examples]** `1578531600 | 1578531600000 | 2020-09-01T01:00:00`
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: >-
            **[Optional]** Payload only includes data before this date
            (exclusive). **[Defaults]** One hour after the beginning of the
            current hour (max time range is 1 hour). **[Formats]** `seconds |
            milliseconds | iso8601` **[Examples]** `1578531600 | 1578531600000 |
            2020-09-01T01:00:00`
          schema:
            type: string
            format: date-time
        - name: timeFormat
          in: query
          description: >-
            **[Optional]** Time format of the timestamps in the return payload.
            **[Defaults]** `milliseconds | ms* | iso | iso8601 | hr |
            human_readable`
          schema:
            type: string
        - name: sortDirection
          in: query
          description: >-
            **[Optional]** Specifies the direction in which the data is sorted
            (by timestamp).   **[Defaults]** asc (ascending order).   **[Usage
            Conditions]** This parameter can only be used if the `startDate` and
            `endDate` timeframe is within the most recent 24 hours, or if the
            `startDate` and `endDate` parameters are not used at all.  
            **[Examples]** ascending | descending | asc | desc
          schema:
            type: string
        - name: Accept-Encoding
          in: header
          required: true
          description: ''
          schema:
            type: string
            default: gzip, deflate, br
        - name: api-version
          in: header
          schema:
            type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Success:
                  value:
                    status: 200
                    title: OK
                    description: Successful request
                    payload:
                      metadata:
                        next: null
                        api-version: '2023-09-30'
                      data:
                        - instrument: BTC-16AUG24-50000-P
                          exchange: bybit
                          exchangeTimestamp: 1722412049804
                          exchangeTimestampNanoseconds: 0
                          isBuySide: true
                          price: 25
                          volume: 0.1
                          tradeId: 8212ab1b-88f9-5c3b-a55d-2bf79a805e11
                          quoteVolume: null
                          sequence: null
                          tickDirection: null
                          indexPrice: 66292.12
                          markPrice: 39.59685034
                          underlyingIndex: null
                          underlyingPrice: 66607.93
                          iv: 0.6291
              schema:
                oneOf:
                  - title: Success
                    type: object
                    properties:
                      status:
                        type: integer
                        example: 200
                        default: 0
                      title:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: Successful request
                      payload:
                        type: object
                        properties:
                          metadata:
                            type: object
                            properties:
                              next: {}
                              api-version:
                                type: string
                                example: '2023-09-30'
                          data:
                            type: array
                            items:
                              type: object
                              properties:
                                instrument:
                                  type: string
                                  example: BTC-16AUG24-50000-P
                                exchange:
                                  type: string
                                  example: bybit
                                exchangeTimestamp:
                                  type: integer
                                  example: 1722412049804
                                  default: 0
                                exchangeTimestampNanoseconds:
                                  type: integer
                                  example: 0
                                  default: 0
                                isBuySide:
                                  type: boolean
                                  example: true
                                  default: true
                                price:
                                  type: integer
                                  example: 25
                                  default: 0
                                volume:
                                  type: number
                                  example: 0.1
                                  default: 0
                                tradeId:
                                  type: string
                                  example: 8212ab1b-88f9-5c3b-a55d-2bf79a805e11
                                quoteVolume:
                                  type: number
                                sequence: {}
                                tickDirection: {}
                                indexPrice:
                                  type: number
                                  example: 66292.12
                                  default: 0
                                markPrice:
                                  type: number
                                  example: 39.59685034
                                  default: 0
                                underlyingIndex: {}
                                underlyingPrice:
                                  type: number
                                  example: 66607.93
                                  default: 0
                                iv:
                                  type: number
                                  example: 0.6291
                                  default: 0
      deprecated: false
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````