BigONE Market Data API

openapi: 3.2.0
info:
  title: Bigone Market Data API
  contact:
    email: developer@big.one
  version: '1.0'
  description: 'Operations tagged Market Data across 4 of this provider''s published API definitions: contract_rest.yml, spot_rest.yml, bigone-contract-openapi.yml, bigone-spot-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.big.one/api/contract/v2
- url: https://api.big.one/api/v3
tags:
- name: Market Data
  description: Public Market Data
paths:
  /instruments:
    get:
      tags:
      - Market Data
      summary: Get List of Contracts Detail
      description: Returns detailed information about all available contract instruments including prices, funding rates, and trading volume.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Instrument'
      operationId: getInstruments
      x-operation-id-source: derived
    servers:
    - url: https://api.big.one/api/contract/v2
  /depth@{symbol}/snapshot:
    get:
      tags:
      - Market Data
      summary: Get OrderBook Snapshot
      description: Returns the current order book snapshot for a contract, showing aggregate quantities at each price level.
      parameters:
      - name: symbol
        in: path
        required: true
        schema:
          type: string
        description: The contract symbol (e.g., BTCUSD, BTCUSDT).
        example: BTCUSD
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  bids:
                    type: object
                    description: Map of Price -> Quantity for buy orders (bids).
                    properties:
                      '{price}':
                        type: number
                        description: The aggregate quantity available at this price level.
                  asks:
                    type: object
                    description: Map of Price -> Quantity for sell orders (asks).
                    properties:
                      '{price}':
                        type: number
                        description: The aggregate quantity available at this price level.
                  to:
                    type: integer
                    format: int64
                    description: The ending sequence ID of this snapshot.
                  from:
                    type: integer
                    format: int64
                    description: The starting sequence ID of this snapshot.
                  lastPrice:
                    type: number
                    description: The price of the most recent trade.
                  bestPrices:
                    type: object
                    description: The current best bid and ask prices.
                    properties:
                      ask:
                        type: number
                        description: The lowest ask price.
                      bid:
                        type: number
                        description: The highest bid price.
                example:
                  bids:
                    '86000': 10
                    '86559': 90688
                  asks:
                    '86928': 86506
                    '86925.5': 92840
                  to: 3425679898
                  lastPrice: 86902
                  bestPrices:
                    ask: 86925.5
                    bid: 86900.5
                  from: 0
      operationId: getDepth@{symbol}Snapshot
      x-operation-id-source: derived
    servers:
    - url: https://api.big.one/api/contract/v2
  /asset_pairs:
    get:
      tags:
      - Market Data
      summary: Get All Asset Pairs
      description: 'Returns a list of all available asset pairs with their configuration.


        This endpoint provides essential market configuration for building trading applications. Asset pairs define the trading relationship between two assets: the **base asset** is what you buy or sell, and the **quote asset** is the currency used for pricing.


        **Special Field Usage:**


        * `base_scale` and `quote_scale` control decimal precision for order quantities and prices. Use these values to format order requests correctly. For example, if `base_scale` is 8, quantities like `0.12345678` are valid but `0.123456789` would be rejected.


        * `min_quote_value` and `max_quote_value` define the order value limits. Order value is calculated as `price × quantity` in quote currency. Orders below `min_quote_value` are too small to process, and orders above `max_quote_value` exceed risk limits.


        :::tip

        Cache this response and refresh periodically. Asset pair configurations change infrequently, so frequent polling is unnecessary.

        :::'
      operationId: getAssetPairs
      responses:
        '200':
          description: List of asset pairs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssetPair'
    servers:
    - url: https://api.big.one/api/v3
  /asset_pairs/{asset_pair_name}/ticker:
    get:
      tags:
      - Market Data
      summary: Get Ticker
      description: Returns ticker data for a specific asset pair.
      operationId: getTicker
      parameters:
      - in: path
        name: asset_pair_name
        required: true
        schema:
          type: string
          default: BTC-USDT
        description: Asset Pair Name (e.g., BTC-USDT)
        example: BTC-USDT
      responses:
        '200':
          description: Ticker data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticker'
    servers:
    - url: https://api.big.one/api/v3
  /asset_pairs/tickers:
    get:
      tags:
      - Market Data
      summary: Get Multiple Tickers
      description: Returns ticker data for multiple asset pairs. Returns all tickers if pair_names is not specified.
      operationId: getTickers
      parameters:
      - in: query
        name: pair_names
        required: false
        schema:
          type: string
        description: Comma-separated list of asset pair names to filter. Returns all tickers if not specified.
        example: BTC-USDT,ETH-BTC
      responses:
        '200':
          description: List of tickers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Ticker'
    servers:
    - url: https://api.big.one/api/v3
  /asset_pairs/{asset_pair_name}/depth:
    get:
      tags:
      - Market Data
      summary: Get Order Book
      description: Returns the order book (depth) for a specific asset pair.
      operationId: getDepth
      parameters:
      - in: path
        name: asset_pair_name
        required: true
        schema:
          type: string
          default: ETH-BTC
        description: Asset Pair Name
        example: ETH-BTC
      - in: query
        name: limit
        required: false
        schema:
          type: integer
          default: 50
          maximum: 200
        description: Depth limit
      responses:
        '200':
          description: Order book depth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Depth'
    servers:
    - url: https://api.big.one/api/v3
  /asset_pairs/{asset_pair_name}/trades:
    get:
      tags:
      - Market Data
      summary: Get Market Trades
      description: Returns the most recent public trades for a specific asset pair.
      operationId: getMarketTrades
      parameters:
      - in: path
        name: asset_pair_name
        required: true
        schema:
          type: string
        description: The asset pair name.
        example: BTC-USDT
      responses:
        '200':
          description: List of market trades
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketTrade'
    servers:
    - url: https://api.big.one/api/v3
  /asset_pairs/{asset_pair_name}/candles:
    get:
      tags:
      - Market Data
      summary: Get Candles
      description: Returns candlestick (OHLCV) data for a specific asset pair.
      operationId: getCandles
      parameters:
      - in: path
        name: asset_pair_name
        required: true
        schema:
          type: string
        description: The asset pair name.
        example: BTC-USDT
      - in: query
        name: period
        required: true
        schema:
          type: string
          enum:
          - day1
          - hour1
          - hour12
          - hour3
          - hour4
          - hour6
          - min1
          - min15
          - min30
          - min5
          - month1
          - week1
        description: The candle period.
        example: day1
      - in: query
        name: time
        required: false
        schema:
          type: string
          format: date-time
        description: The latest candle time (ISO 8601). Returns the most recent candles if not specified.
        example: '2024-01-15T00:00:00Z'
      - in: query
        name: limit
        required: false
        schema:
          type: integer
          default: 100
          minimum: 1
          maximum: 500
        description: The maximum number of candles to return.
      - in: query
        name: direction
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
        description: The sorting direction for candles. ASC = oldest first, DESC = newest first. Default is DESC.
        example: DESC
      responses:
        '200':
          description: List of candles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Candle'
    servers:
    - url: https://api.big.one/api/v3
components:
  schemas:
    Instrument:
      type: object
      properties:
        usdtPrice:
          type: number
          example: 0.99929568
          description: USDT Index Price
        symbol:
          type: string
          example: BTCUSD
          description: Contract Instrument Symbol
        btcPrice:
          type: number
          example: 87413.1
          description: BTC Index Price
        ethPrice:
          type: number
          example: 2921.36
          description: ETH Index Price
        nextFundingRate:
          type: number
          example: 0.0001
          description: Estimated next funding rate
        fundingRate:
          type: number
          example: 0.0001974
          description: Current funding rate
        latestPrice:
          type: number
          example: 87391
          description: Latest transaction price
        last24hPriceChange:
          type: number
          example: 0.0041
          description: 24h price change percentage
        indexPrice:
          type: number
          example: 87413.1
          description: Index price
        volume24h:
          type: number
          example: 3889971
          description: 24h trading volume (in contract size)
        turnover24h:
          type: number
          example: 44.5192334698948
          description: 24h turnover
        nextFundingTime:
          type: integer
          format: int64
          example: 1766685600000
          description: Next funding timestamp
        markPrice:
          type: number
          example: 87422.65075531
          description: Mark price
        last24hMaxPrice:
          type: number
          example: 87997.5
          description: Highest price in the last 24 hours
        volume24hInUsd:
          type: number
          example: 3891564.20722726
          description: 24h trading volume (in USD)
        openValue:
          type: number
          example: 29.7443056608277
          description: Open Value
        last24hMinPrice:
          type: number
          example: 86313.5
          description: Lowest price in the last 24 hours
        openInterest:
          type: number
          example: 1376246
          description: Total open interest
    Candle:
      type: object
      description: A candlestick (OHLCV) data point for an asset pair.
      properties:
        time:
          type: string
          description: The candle timestamp (RFC3339, second precision).
          example: '2025-12-29T13:00:00Z'
        open:
          type: string
          description: The opening price.
          example: '3613.94'
        high:
          type: string
          description: The highest price during the period.
          example: '3615.53'
        low:
          type: string
          description: The lowest price during the period.
          example: '3613.94'
        close:
          type: string
          description: The closing price.
          example: '3614.18'
        volume:
          type: string
          description: The trading volume during the period (base asset).
          example: '0.084582'
    Depth:
      type: object
      description: The order book (depth) for an asset pair showing bids and asks.
      properties:
        asset_pair_name:
          type: string
          description: The asset pair name.
          example: BTC-USDT
        bids:
          type: array
          description: Buy orders sorted by price (highest bid first).
          items:
            $ref: '#/components/schemas/PriceLevel'
        asks:
          type: array
          description: Sell orders sorted by price (lowest ask first).
          items:
            $ref: '#/components/schemas/PriceLevel'
    MarketTrade:
      type: object
      description: A public market trade.
      properties:
        id:
          type: integer
          format: int64
          description: The trade ID.
          example: 38199941
        price:
          type: string
          description: The execution price.
          example: '3378.67'
        amount:
          type: string
          description: The trade amount (base asset quantity).
          example: '0.019812'
        taker_side:
          type: string
          enum:
          - ASK
          - BID
          description: The taker's side. ASK = seller, BID = buyer.
          example: ASK
        inserted_at:
          type: string
          description: The timestamp when the trade was executed (RFC3339 with millisecond precision).
          example: '2025-12-29T14:50:54.623Z'
    PriceLevel:
      type: object
      description: A price level with quantity and order count.
      properties:
        price:
          type: string
          description: The price level.
          example: '5098.37'
        quantity:
          type: string
          description: The total quantity at this price level.
          example: '0.0679'
        order_count:
          type: integer
          format: uint64
          description: The number of orders at this price level.
          example: 10
    Ticker:
      type: object
      description: 24-hour trading statistics for an asset pair.
      properties:
        asset_pair_name:
          type: string
          description: The asset pair name.
          example: BTC-USDT
        bid:
          description: The current highest bid price level.
          $ref: '#/components/schemas/PriceLevel'
        ask:
          description: The current lowest ask price level.
          $ref: '#/components/schemas/PriceLevel'
        open:
          type: string
          description: The opening price.
          example: '3100.0'
        close:
          type: string
          description: The latest price (close).
          example: '3150.0'
        high:
          type: string
          description: The highest price in the last 24 hours.
          example: '3200.0'
        low:
          type: string
          description: The lowest price in the last 24 hours.
          example: '3050.0'
        volume:
          type: string
          description: The trading volume in the last 24 hours (base asset).
          example: '1500.5'
        daily_change:
          type: string
          description: The price change in the last 24 hours (absolute value).
          example: '50.0'
    AssetPair:
      type: object
      description: An asset pair (trading pair) with its configuration.
      properties:
        id:
          type: string
          description: The unique identifier of the asset pair.
          example: d2185614-50c3-4588-b146-b8afe7534da6
        name:
          type: string
          description: The asset pair name (e.g., BTC-USDT).
          example: BTC-USDT
        base_scale:
          type: integer
          description: The decimal precision for the base asset (quantity).
          example: 8
        quote_scale:
          type: integer
          description: The decimal precision for the quote asset (price).
          example: 2
        base_asset:
          description: The base asset details.
          type: object
          properties:
            id:
              type: string
              description: The asset ID.
            symbol:
              type: string
              description: The asset symbol.
              example: BTC
            name:
              type: string
              description: The asset name.
              example: Bitcoin
        quote_asset:
          description: The quote asset details.
          type: object
          properties:
            id:
              type: string
              description: The asset ID.
            symbol:
              type: string
              description: The asset symbol.
              example: USDT
            name:
              type: string
              description: The asset name.
              example: Tether
        min_quote_value:
          type: string
          description: The minimum order value in quote currency.
          example: '0.001'
        max_quote_value:
          type: string
          description: The maximum order value in quote currency.
          example: '1000000'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- contract_rest.yml
- spot_rest.yml
- bigone-contract-openapi.yml
- bigone-spot-openapi.yml