{
  "openapi": "3.1.0",
  "info": {
    "title": "BubbleMarkets Public Market Data API",
    "version": "1.0.0",
    "description": "Read-only market data behind BubbleMarkets, the multi-asset market bubble-map. Returns live price, percentage change, market capitalization and volume for US stocks, ETFs, cryptocurrencies, forex currencies, forex cross-rate pairs and commodities. Use it for market overviews, biggest gainers and losers in any asset class, and single-asset lookups.",
    "contact": {
      "name": "BubbleMarkets support",
      "email": "support@bubblemarkets.com",
      "url": "https://bubblemarkets.com/developer"
    },
    "license": {
      "name": "BubbleMarkets Terms of Use",
      "url": "https://bubblemarkets.com/terms"
    }
  },
  "servers": [{ "url": "https://bubblemarkets.com" }],
  "security": [{ "ApiKeyAuth": [] }],
  "paths": {
    "/api/v1/markets": {
      "get": {
        "operationId": "listMarkets",
        "summary": "List live market data for one asset class",
        "description": "Returns a page of assets for the requested asset class, each with symbol, name, price, market capitalization, volume and 24-hour percentage change. Ask for `crypto` to see cryptocurrencies ranked by market cap, `stocks` for the most-traded US stocks, `etf` for exchange-traded funds, `forex` for individual world currencies, `forex_pairs` for cross rates, or `commodities` for metals, energy, grains, softs and livestock. This is the fastest way to answer questions like 'what is the crypto market doing right now?' or 'which US stocks are up the most today?'.",
        "tags": ["Markets"],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "description": "Asset class to return.",
            "schema": {
              "type": "string",
              "enum": ["crypto", "stocks", "etf", "forex", "forex_pairs", "commodities"]
            },
            "example": "crypto"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number. Results are ordered by market capitalization descending, so page 1 holds the largest assets.",
            "schema": { "type": "integer", "minimum": 1, "default": 1 },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "A page of assets in the requested asset class.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "category": { "type": "string" },
                    "page": { "type": "integer" },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Asset" }
                    }
                  }
                },
                "example": {
                  "category": "crypto",
                  "page": 1,
                  "data": [
                    {
                      "symbol": "BTC",
                      "name": "Bitcoin",
                      "price": 64213.5,
                      "market_cap": 1265000000000,
                      "volume": 28400000000,
                      "price_change_percentage_24h": 2.14
                    }
                  ]
                }
              }
            }
          },
          "401": { "description": "Missing or invalid API key." },
          "429": { "description": "Rate limit exceeded." }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key issued on the Professional plan at https://bubblemarkets.com/developer"
      }
    },
    "schemas": {
      "Asset": {
        "type": "object",
        "description": "One tradable asset as rendered by a single bubble on BubbleMarkets.",
        "properties": {
          "symbol": { "type": "string", "description": "Ticker or currency code, e.g. AAPL, BTC, EURUSD." },
          "name": { "type": "string", "description": "Human-readable asset name." },
          "price": { "type": "number", "description": "Latest price in USD." },
          "market_cap": { "type": "number", "description": "Market capitalization in USD, or the closest equivalent for the asset class." },
          "volume": { "type": "number", "description": "Trading volume over the last 24 hours in USD." },
          "price_change_percentage_24h": { "type": "number", "description": "Percentage price change over the last 24 hours." }
        }
      }
    }
  }
}