openapi: 3.1.0
info:
  title: Market API
  description: >

    use the [Market API](/marketapi) Fetch real-time and historical market data,
    including:

    - Order books

    - Recent trades

    - Tickers and price feeds
  license:
    name: ''
  version: 0.0.1
servers:
  - url: https://data-api.hibachi.xyz
    description: Production server
paths:
  /market/exchange-info:
    get:
      tags:
        - Market
      operationId: Exchange Info
      responses:
        '200':
          description: Exchange Info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeInfoResponse'
  /market/inventory:
    get:
      tags:
        - Market
      operationId: Inventory
      responses:
        '200':
          description: Market Inventory value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketsResponse'
  /market/data/prices?symbol={symbol}:
    get:
      tags:
        - Market
      description: Get market prices for a specific symbol
      operationId: Prices
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
          example: ETH/USDT-P
      responses:
        '200':
          description: Market Prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketPricesResponse'
  /market/data/stats?symbol={symbol}:
    get:
      tags:
        - Market
      description: Get market stats for a specific symbol
      operationId: Stats
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Market Stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketStatsResponse'
  /market/data/trades?symbol={symbol}:
    get:
      tags:
        - Market
      description: Get recent trades for a specific symbol
      operationId: Trades
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
          example: ETH/USDT-P
      responses:
        '200':
          description: Market Trades
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecentTradesResponse'
  /market/data/klines?symbol={symbol}&interval={interval}:
    get:
      tags:
        - Market
      description: Get the candlesticks for a future contract.
      operationId: Candlesticks
      parameters:
        - name: symbol
          in: path
          required: true
          schema:
            type: string
        - name: interval
          in: path
          required: true
          schema:
            type: string
        - name: fromMs
          in: path
          required: true
          schema:
            type:
              - integer
              - 'null'
            format: int64
            minimum: 0
        - name: toMs
          in: path
          required: true
          schema:
            type:
              - integer
              - 'null'
            format: int64
            minimum: 0
      responses:
        '200':
          description: Market Inventory value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KlinesResponse'
  /market/data/open-interest?symbol={symbol}:
    get:
      tags:
        - Market
      summary: Open Interest
      description: |+
        Get the open interest for one future contract.
        It will return the total open position from each side.

      operationId: Open Interest
      parameters:
        - name: symbol
          in: path
          description: The symbol of the contract to get open interest for.
          required: true
          schema:
            type: string
          example: ETH/USDT-P
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenInterestResponse'
  /market/data/orderbook:
    get:
      tags:
        - Market
      operationId: Orderbook
      parameters:
        - name: symbol
          in: path
          required: true
          schema:
            type: string
        - name: depth
          in: path
          required: true
          schema:
            type:
              - integer
              - 'null'
            format: int32
            minimum: 0
        - name: granularity
          in: path
          required: true
          schema:
            type:
              - string
              - 'null'
      responses:
        '200':
          description: Market Orderbook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceLevelResponseData'
  /exchange/stats/volumes:
    get:
      tags:
        - Market
      operationId: Volumes
      responses:
        '200':
          description: Exchange Stats Volumes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeStatsVolumesResponse'
components:
  schemas:
    ChainVolume:
      type: object
      required:
        - chain_name
        - volume
      properties:
        chain_name:
          type: string
        volume:
          type: number
          format: double
    Contract:
      type: object
      required:
        - id
        - symbol
        - displayName
        - underlyingSymbol
        - underlyingDecimals
        - settlementSymbol
        - settlementDecimals
        - riskFactorForPositions
        - riskFactorForOrders
        - maintenanceFactorForPositions
        - orderbookGranularities
        - status
      properties:
        displayName:
          type: string
        id:
          $ref: '#/components/schemas/u32'
        maintenanceFactorForPositions:
          type: string
        marketCloseTimestamp:
          type:
            - string
            - 'null'
        marketOpenTimestamp:
          type:
            - string
            - 'null'
        orderbookGranularities:
          type: array
          items:
            type: string
        riskFactorForOrders:
          type: string
        riskFactorForPositions:
          type: string
        settlementDecimals:
          type: integer
          format: int32
          minimum: 0
        settlementSymbol:
          type: string
        status:
          $ref: '#/components/schemas/ContractStatus'
        symbol:
          type: string
        underlyingDecimals:
          type: integer
          format: int32
          minimum: 0
        underlyingSymbol:
          type: string
    ContractData:
      allOf:
        - $ref: '#/components/schemas/Contract'
        - type: object
          required:
            - stepSize
            - tickSize
            - minOrderSize
            - minNotional
          properties:
            minNotional:
              type: string
            minOrderSize:
              type: string
            stepSize:
              type: string
            tickSize:
              type: string
    ContractStatus:
      type: string
      enum:
        - LISTED
        - PRE_OPEN
        - LIVE
        - PAUSED
        - CLOSED
    CrossChainAsset:
      type: object
      required:
        - chain
        - token
        - exchangeRateToUSDT
        - exchangeRateFromUSDT
      properties:
        chain:
          type: string
        exchangeRateFromUSDT:
          type: string
        exchangeRateToUSDT:
          type: string
        instantWithdrawalLowerLimitInUSDT:
          type:
            - string
            - 'null'
        instantWithdrawalUpperLimitInUSDT:
          type:
            - string
            - 'null'
        token:
          type: string
    ExchangeFeeConfig:
      type: object
      required:
        - tradeTakerFeeRate
        - tradeMakerFeeRate
        - transferFeeRate
        - depositFees
        - withdrawalFees
      properties:
        depositFees:
          type: string
        instantWithdrawDstPublicKey:
          type:
            - string
            - 'null'
        instantWithdrawalFees:
          type:
            - array
            - 'null'
          items:
            type: array
            items: false
            prefixItems:
              - type: integer
                format: int64
                minimum: 0
              - type: number
                format: double
        tradeMakerFeeRate:
          type: string
        tradeTakerFeeRate:
          type: string
        transferFeeRate:
          type: string
        withdrawalFees:
          type: string
    ExchangeInfoResponse:
      allOf:
        - $ref: '#/components/schemas/MaintenanceInfo'
        - type: object
          required:
            - futureContracts
            - feeConfig
            - instantWithdrawalLimit
          properties:
            feeConfig:
              $ref: '#/components/schemas/ExchangeFeeConfig'
            futureContracts:
              type: array
              items:
                $ref: '#/components/schemas/ContractData'
            instantWithdrawalLimit:
              $ref: '#/components/schemas/InstantWithdrawalLimit'
    ExchangeMarketStats:
      type: object
      required:
        - id
        - symbol
      properties:
        high24h:
          type:
            - string
            - 'null'
        id:
          $ref: '#/components/schemas/u32'
        low24h:
          type:
            - string
            - 'null'
        symbol:
          type: string
        volume24h:
          type:
            - string
            - 'null'
    ExchangeStatsVolumesResponse:
      type: object
      required:
        - future_contracts
        - timestamp
        - chain_volumes
      properties:
        chain_volumes:
          type: array
          items:
            $ref: '#/components/schemas/ChainVolume'
        future_contracts:
          type: array
          items:
            $ref: '#/components/schemas/ExchangeMarketStats'
        timestamp:
          type: string
          format: date-time
    ExchangeStatus:
      oneOf:
        - type: object
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - NORMAL
        - type: object
          required:
            - currentMaintenanceWindow
            - status
          properties:
            currentMaintenanceWindow:
              $ref: '#/components/schemas/MaintenanceWindow'
            status:
              type: string
              enum:
                - SCHEDULED_MAINTENANCE
        - type: object
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - UNSCHEDULED_MAINTENANCE
    FundingRateEstimation:
      type: object
      required:
        - nextFundingTimestamp
        - estimatedFundingRate
      properties:
        estimatedFundingRate:
          type: string
        nextFundingTimestamp:
          type: integer
          format: int64
          minimum: 0
    InstantWithdrawalLimit:
      type: object
      properties:
        lowerLimit:
          type:
            - string
            - 'null'
        upperLimit:
          type:
            - string
            - 'null'
    Kline:
      type: object
      required:
        - interval
        - timestamp
        - open
        - high
        - low
        - close
        - volumeNotional
      properties:
        close:
          type: string
        high:
          type: string
        interval:
          type: string
        low:
          type: string
        open:
          type: string
        timestamp:
          type: integer
          format: int64
          minimum: 0
        volumeNotional:
          type: string
    KlinesResponse:
      type: object
      required:
        - klines
      properties:
        klines:
          type: array
          items:
            $ref: '#/components/schemas/Kline'
    MaintenanceInfo:
      allOf:
        - $ref: '#/components/schemas/ExchangeStatus'
        - type: object
          required:
            - maintenanceWindow
          properties:
            maintenanceWindow:
              type: array
              items:
                $ref: '#/components/schemas/MaintenanceWindow'
    MaintenanceWindow:
      type: object
      required:
        - begin
        - end
        - note
      properties:
        begin:
          type: string
        end:
          type: string
        note:
          type: string
    Market:
      type: object
      required:
        - contract
        - info
      properties:
        contract:
          $ref: '#/components/schemas/ContractData'
        info:
          $ref: '#/components/schemas/MarketInfo'
    MarketInfo:
      type: object
      required:
        - tags
      properties:
        category:
          type:
            - string
            - 'null'
        markPrice:
          type:
            - string
            - 'null'
        price24hAgo:
          type:
            - string
            - 'null'
        priceLatest:
          type:
            - string
            - 'null'
        tags:
          type: array
          items:
            type: string
    MarketPricesResponse:
      type: object
      required:
        - symbol
      properties:
        askPrice:
          type:
            - string
            - 'null'
        bidPrice:
          type:
            - string
            - 'null'
        fundingRateEstimation:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FundingRateEstimation'
        markPrice:
          type:
            - string
            - 'null'
        spotPrice:
          type:
            - string
            - 'null'
        symbol:
          type: string
        tradePrice:
          type:
            - string
            - 'null'
    MarketStatsResponse:
      type: object
      required:
        - symbol
      properties:
        high24h:
          type:
            - string
            - 'null'
        low24h:
          type:
            - string
            - 'null'
        symbol:
          type: string
        volume24h:
          type:
            - string
            - 'null'
    MarketsResponse:
      type: object
      required:
        - markets
        - feeConfig
        - tradingTiers
        - crossChainAssets
      properties:
        crossChainAssets:
          type: array
          items:
            $ref: '#/components/schemas/CrossChainAsset'
        feeConfig:
          $ref: '#/components/schemas/ExchangeFeeConfig'
        markets:
          type: array
          items:
            $ref: '#/components/schemas/Market'
        tradingTiers:
          type: array
          items:
            $ref: '#/components/schemas/TradingTier'
    OpenInterestResponse:
      type: object
      required:
        - totalQuantity
      properties:
        totalQuantity:
          type: string
          description: open interest for one future contract
          example: '6.326719254'
    PriceLevelExternal:
      type: object
      title: PriceLevel
      description: Represents a price level in the order book with price and quantity.
      required:
        - price
        - quantity
      properties:
        price:
          type: string
        quantity:
          type: string
    PriceLevelResponseData:
      type: object
      required:
        - ask
        - bid
      properties:
        ask:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PriceLevelsDetail'
        bid:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PriceLevelsDetail'
    PriceLevelsDetail:
      type: object
      required:
        - startPrice
        - endPrice
        - levels
      properties:
        endPrice:
          type: string
        levels:
          type: array
          items:
            $ref: '#/components/schemas/PriceLevelExternal'
        startPrice:
          type: string
    RecentTradesResponse:
      type: object
      required:
        - trades
      properties:
        trades:
          type: array
          items:
            $ref: '#/components/schemas/Trade'
    TakerSide:
      type: string
      enum:
        - Sell
        - Buy
    Trade:
      type: object
      required:
        - quantity
        - price
        - takerSide
        - timestamp
      properties:
        price:
          type: string
        quantity:
          type: string
        takerSide:
          $ref: '#/components/schemas/TakerSide'
        timestamp:
          type: integer
          format: int64
          minimum: 0
    TradingTier:
      type: object
      required:
        - level
        - title
        - lowerThreshold
        - upperThreshold
      properties:
        level:
          type: integer
          format: int32
        lowerThreshold:
          type: string
        title:
          type: string
        upperThreshold:
          type: string
    u32:
      type: integer
      format: int32
      minimum: 0
tags:
  - name: Market
    description: Market API endpoints
