{
  "openapi": "3.1.0",
  "info": {
    "title": "OptimistFi Perps Data API",
    "version": "1.0.0",
    "description": "Funding, open interest, prices and leverage caps for perpetual futures across venues, in one schema. The live API needs no key; the historical dataset of stock, commodity, FX and index perps needs an API key.",
    "contact": {
      "name": "OptimistFi",
      "url": "https://optimistfi.com/contact"
    }
  },
  "externalDocs": {
    "description": "Guides and reference",
    "url": "https://optimistfi.com/perps/data"
  },
  "servers": [
    {
      "url": "https://optimistfi.com"
    }
  ],
  "tags": [
    {
      "name": "Live",
      "description": "Free, no key, open CORS."
    },
    {
      "name": "Historical dataset",
      "description": "API key; 60 requests a minute per key."
    }
  ],
  "paths": {
    "/api/perps/snapshot": {
      "get": {
        "operationId": "snapshot",
        "summary": "Snapshot",
        "description": "Everything at once: venue health, market totals and every matched asset with its quote on each venue.\n\nRebuilt every 4 seconds (Hyperliquid and its builder venues every 10); polling faster returns the same data.",
        "tags": [
          "Live"
        ],
        "security": [],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "asOf": "2026-10-07T20:43:28.760Z",
                  "totals": {
                    "openInterestUsd": 22458109275.484905,
                    "volume24hUsd": 22713394857.69481,
                    "marketCount": 4004,
                    "assetCount": 1045,
                    "multiVenueAssetCount": 631
                  },
                  "venues": [
                    {
                      "venue": "veranta",
                      "ok": true,
                      "fetchedAt": "2026-10-07T20:43:23.215Z",
                      "latencyMs": 333,
                      "marketCount": 170,
                      "error": null,
                      "gaps": [
                        "price, 24h change and 24h volume (not in the public feed)"
                      ],
                      "openInterestUsd": 58844038.28,
                      "volume24hUsd": 0,
                      "volumeReported": false,
                      "openInterestLongUsd": 29069186.45,
                      "openInterestShortUsd": 29774851.83,
                      "openInterestShare": 0.00262
                    }
                  ],
                  "assets": [
                    {
                      "base": "BTC",
                      "slug": "btc",
                      "assetClass": "crypto",
                      "venueCount": 23,
                      "maxLeverage": 200,
                      "maxLeverageVenue": "gmx",
                      "upsideMaxLeverage": 500,
                      "price": 83366.57376,
                      "change24hPct": -2.633397,
                      "openInterestUsd": 5123838633.238214,
                      "volume24hUsd": 7191972043.540741,
                      "fundingRateHourly": 0.000012,
                      "fundingApr": 0.100982,
                      "fundingSpreadHourly": 0.00007,
                      "fundingSpreadApr": 0.617267,
                      "cheapestLong": "gmx",
                      "richestShort": "bluefin",
                      "priceDispersionBps": 15.03375,
                      "venues": [
                        {
                          "venue": "veranta",
                          "venueSymbol": "BTC/USD",
                          "venueMarketId": "1",
                          "base": "BTC",
                          "quote": "USD",
                          "assetClass": "crypto",
                          "contractMultiplier": 1,
                          "markPrice": null,
                          "indexPrice": null,
                          "change24hPct": null,
                          "volume24hUsd": null,
                          "openInterestUsd": 8747312.72,
                          "openInterestBase": 108.800116,
                          "fundingRateHourly": 0.000012,
                          "shortFundingRateHourly": -0.000012,
                          "borrowRateHourlyLong": 0,
                          "borrowRateHourlyShort": 0,
                          "openInterestLongUsd": 4159682.15,
                          "openInterestShortUsd": 4587630.57,
                          "fundingIntervalHours": 1,
                          "nextFundingTime": null,
                          "maxLeverage": 50,
                          "upsideMaxLeverage": 500,
                          "premium": null,
                          "fundingApr": 0.105125,
                          "openInterestShare": 0.001707
                        }
                      ],
                      "excluded": []
                    }
                  ],
                  "docs": "https://optimistfi.com/perps/data"
                }
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    },
    "/api/perps/assets": {
      "get": {
        "operationId": "assets",
        "summary": "List assets",
        "description": "Matched assets, one row per underlying across venues, filtered, sorted and paged.\n\nRebuilt every 4 seconds (Hyperliquid and its builder venues every 10); polling faster returns the same data.",
        "tags": [
          "Live"
        ],
        "security": [],
        "parameters": [
          {
            "name": "class",
            "in": "query",
            "required": false,
            "description": "Only assets of this class.",
            "schema": {
              "type": "string",
              "enum": [
                "crypto",
                "equity",
                "index",
                "fx",
                "commodity"
              ]
            }
          },
          {
            "name": "venue",
            "in": "query",
            "required": false,
            "description": "Only assets listed on this venue.",
            "schema": {
              "type": "string",
              "enum": [
                "veranta",
                "hyperliquid",
                "tradexyz",
                "kinetiq",
                "entropyio",
                "paragon",
                "lighter",
                "aster",
                "dydx",
                "gmx",
                "paradex",
                "extended",
                "qfex",
                "vest",
                "vestmarkets",
                "orderly",
                "nado",
                "kraken",
                "variational",
                "polymarket",
                "pacifica",
                "edgex",
                "grvt",
                "apex",
                "aevo",
                "gains",
                "ostium",
                "jupiter",
                "hibachi",
                "bluefin",
                "okx",
                "bitget",
                "gate",
                "mexc",
                "htx",
                "kucoin",
                "deribit",
                "bitfinex",
                "phemex",
                "woox",
                "binance",
                "bybit",
                "cme",
                "bingx",
                "whitebit",
                "cryptocom",
                "kalshi"
              ]
            }
          },
          {
            "name": "minVenues",
            "in": "query",
            "required": false,
            "description": "Listed on at least this many venues.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 47
            }
          },
          {
            "name": "minOi",
            "in": "query",
            "required": false,
            "description": "Minimum total open interest, USD.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Order, largest first.",
            "schema": {
              "type": "string",
              "enum": [
                "oi",
                "volume",
                "leverage",
                "funding",
                "spread",
                "change",
                "venues"
              ],
              "default": "oi"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows per page. Without it every row is returned.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip; follow `next` rather than computing it.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "asOf": "2026-10-07T20:43:28.760Z",
                  "query": {
                    "assetClass": "equity",
                    "limit": 1
                  },
                  "count": 1,
                  "total": 1,
                  "offset": 0,
                  "limit": 1,
                  "next": null,
                  "data": [
                    {
                      "base": "SKHYNIX",
                      "slug": "skhynix",
                      "assetClass": "equity",
                      "venueCount": 11,
                      "maxLeverage": 10,
                      "maxLeverageVenue": "tradexyz",
                      "upsideMaxLeverage": null,
                      "price": 1281.21141,
                      "change24hPct": -1.152786,
                      "openInterestUsd": 338582761.662527,
                      "volume24hUsd": 214406912.088272,
                      "fundingRateHourly": 0.000034,
                      "fundingApr": 0.301613,
                      "fundingSpreadHourly": 0.000037,
                      "fundingSpreadApr": 0.325955,
                      "cheapestLong": "aster",
                      "richestShort": "tradexyz",
                      "priceDispersionBps": 34.21971,
                      "venues": [
                        {
                          "venue": "veranta",
                          "venueSymbol": "SK HYNIX/USD",
                          "venueMarketId": "114",
                          "base": "SKHYNIX",
                          "quote": "USD",
                          "assetClass": "equity",
                          "contractMultiplier": 1,
                          "markPrice": null,
                          "indexPrice": null,
                          "change24hPct": null,
                          "volume24hUsd": null,
                          "openInterestUsd": 1000,
                          "openInterestBase": 6.232566,
                          "fundingRateHourly": 0.000001,
                          "shortFundingRateHourly": -0.000001,
                          "borrowRateHourlyLong": 0.000002,
                          "borrowRateHourlyShort": 0.000002,
                          "openInterestLongUsd": 500,
                          "openInterestShortUsd": 500,
                          "fundingIntervalHours": 1,
                          "nextFundingTime": null,
                          "maxLeverage": 5,
                          "upsideMaxLeverage": null,
                          "premium": null,
                          "fundingApr": 0.012394,
                          "openInterestShare": 0.000003
                        }
                      ],
                      "excluded": []
                    }
                  ],
                  "docs": "https://optimistfi.com/perps/data"
                }
              }
            }
          },
          "400": {
            "description": "invalid_parameter: A parameter is missing, out of range or not one of its allowed values. The message names it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    },
    "/api/perps/assets/{asset}": {
      "get": {
        "operationId": "asset",
        "summary": "Get an asset",
        "description": "One underlying on every venue, with each venue's funding history and statistics: average, range and the share of hours longs paid.\n\nFunding history refreshes every 10 minutes; quotes with the snapshot.",
        "tags": [
          "Live"
        ],
        "security": [],
        "parameters": [
          {
            "name": "asset",
            "in": "path",
            "required": true,
            "description": "The underlying: btc, eth, tsla, xau.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hours",
            "in": "query",
            "required": false,
            "description": "Hours of funding history.",
            "schema": {
              "type": "integer",
              "minimum": 24,
              "maximum": 480,
              "default": 168
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "asOf": "2026-10-07T20:43:36.898Z",
                  "historyHours": 24,
                  "asset": {
                    "base": "BTC",
                    "slug": "btc",
                    "assetClass": "crypto",
                    "venueCount": 23,
                    "maxLeverage": 200,
                    "maxLeverageVenue": "gmx",
                    "upsideMaxLeverage": 500,
                    "price": 83373.928875,
                    "change24hPct": -2.622364,
                    "openInterestUsd": 5124516105.862597,
                    "volume24hUsd": 7192537846.323318,
                    "fundingRateHourly": 0.000012,
                    "fundingApr": 0.100983,
                    "fundingSpreadHourly": 0.00007,
                    "fundingSpreadApr": 0.617267,
                    "cheapestLong": "gmx",
                    "richestShort": "bluefin",
                    "priceDispersionBps": 15.03375,
                    "venues": [
                      {
                        "venue": "veranta",
                        "venueSymbol": "BTC/USD",
                        "venueMarketId": "1",
                        "base": "BTC",
                        "quote": "USD",
                        "assetClass": "crypto",
                        "contractMultiplier": 1,
                        "markPrice": null,
                        "indexPrice": null,
                        "change24hPct": null,
                        "volume24hUsd": null,
                        "openInterestUsd": 8747312.72,
                        "openInterestBase": 108.800116,
                        "fundingRateHourly": 0.000012,
                        "shortFundingRateHourly": -0.000012,
                        "borrowRateHourlyLong": 0,
                        "borrowRateHourlyShort": 0,
                        "openInterestLongUsd": 4159682.15,
                        "openInterestShortUsd": 4587630.57,
                        "fundingIntervalHours": 1,
                        "nextFundingTime": null,
                        "maxLeverage": 50,
                        "upsideMaxLeverage": 500,
                        "premium": null,
                        "fundingApr": 0.105125,
                        "openInterestShare": 0.001707
                      }
                    ],
                    "excluded": []
                  },
                  "history": [
                    {
                      "venue": "veranta",
                      "venueSymbol": "BTC/USD",
                      "fundingIntervalHours": 1,
                      "points": [],
                      "error": "the data layer did not answer in time",
                      "stats": {
                        "count": 0,
                        "avgHourly": null,
                        "minHourly": null,
                        "maxHourly": null,
                        "lastHourly": null,
                        "lastTime": null,
                        "longsPaidShare": null
                      }
                    }
                  ],
                  "docs": "https://optimistfi.com/perps/data"
                }
              }
            }
          },
          "400": {
            "description": "invalid_parameter: A parameter is missing, out of range or not one of its allowed values. The message names it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "404": {
            "description": "not_found: No such asset or endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    },
    "/api/perps/funding": {
      "get": {
        "operationId": "funding",
        "summary": "List funding gaps",
        "description": "The widest carry between two venues on each asset, widest first: the cheapest venue to hold a long, the richest to hold a short, and the thinner side's open interest.\n\nRebuilt every 4 seconds (Hyperliquid and its builder venues every 10); polling faster returns the same data.",
        "tags": [
          "Live"
        ],
        "security": [],
        "parameters": [
          {
            "name": "class",
            "in": "query",
            "required": false,
            "description": "Only assets of this class.",
            "schema": {
              "type": "string",
              "enum": [
                "crypto",
                "equity",
                "index",
                "fx",
                "commodity"
              ]
            }
          },
          {
            "name": "venue",
            "in": "query",
            "required": false,
            "description": "Only gaps on assets listed on this venue.",
            "schema": {
              "type": "string",
              "enum": [
                "veranta",
                "hyperliquid",
                "tradexyz",
                "kinetiq",
                "entropyio",
                "paragon",
                "lighter",
                "aster",
                "dydx",
                "gmx",
                "paradex",
                "extended",
                "qfex",
                "vest",
                "vestmarkets",
                "orderly",
                "nado",
                "kraken",
                "variational",
                "polymarket",
                "pacifica",
                "edgex",
                "grvt",
                "apex",
                "aevo",
                "gains",
                "ostium",
                "jupiter",
                "hibachi",
                "bluefin",
                "okx",
                "bitget",
                "gate",
                "mexc",
                "htx",
                "kucoin",
                "deribit",
                "bitfinex",
                "phemex",
                "woox",
                "binance",
                "bybit",
                "cme",
                "bingx",
                "whitebit",
                "cryptocom",
                "kalshi"
              ]
            }
          },
          {
            "name": "minLegOi",
            "in": "query",
            "required": false,
            "description": "Minimum open interest on the thinner of the two venues, USD.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows per page. Without it every row is returned.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip; follow `next` rather than computing it.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "asOf": "2026-10-07T20:43:36.898Z",
                  "query": {
                    "minLegOi": 1000000,
                    "limit": 1
                  },
                  "count": 1,
                  "total": 1,
                  "offset": 0,
                  "limit": 1,
                  "next": null,
                  "data": [
                    {
                      "base": "NATGAS",
                      "slug": "natgas",
                      "assetClass": "commodity",
                      "longVenue": "gmx",
                      "shortVenue": "extended",
                      "longCostHourly": 0.000399,
                      "shortEarnHourly": 0.001882,
                      "spreadHourly": 0.001483,
                      "spreadApr": 12.992771,
                      "thinnerLegOpenInterestUsd": 1222012.098066,
                      "priceDispersionBps": 576.521934
                    }
                  ],
                  "docs": "https://optimistfi.com/perps/data"
                }
              }
            }
          },
          "400": {
            "description": "invalid_parameter: A parameter is missing, out of range or not one of its allowed values. The message names it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    },
    "/api/perps/markets": {
      "get": {
        "operationId": "markets",
        "summary": "List markets",
        "description": "Every matched venue listing as its own row, largest open interest first: the shape for joins and screens.\n\nRebuilt every 4 seconds (Hyperliquid and its builder venues every 10); polling faster returns the same data.",
        "tags": [
          "Live"
        ],
        "security": [],
        "parameters": [
          {
            "name": "venue",
            "in": "query",
            "required": false,
            "description": "Only this venue's markets.",
            "schema": {
              "type": "string",
              "enum": [
                "veranta",
                "hyperliquid",
                "tradexyz",
                "kinetiq",
                "entropyio",
                "paragon",
                "lighter",
                "aster",
                "dydx",
                "gmx",
                "paradex",
                "extended",
                "qfex",
                "vest",
                "vestmarkets",
                "orderly",
                "nado",
                "kraken",
                "variational",
                "polymarket",
                "pacifica",
                "edgex",
                "grvt",
                "apex",
                "aevo",
                "gains",
                "ostium",
                "jupiter",
                "hibachi",
                "bluefin",
                "okx",
                "bitget",
                "gate",
                "mexc",
                "htx",
                "kucoin",
                "deribit",
                "bitfinex",
                "phemex",
                "woox",
                "binance",
                "bybit",
                "cme",
                "bingx",
                "whitebit",
                "cryptocom",
                "kalshi"
              ]
            }
          },
          {
            "name": "class",
            "in": "query",
            "required": false,
            "description": "Only markets of this class.",
            "schema": {
              "type": "string",
              "enum": [
                "crypto",
                "equity",
                "index",
                "fx",
                "commodity"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows per page. Without it every row is returned.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip; follow `next` rather than computing it.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "asOf": "2026-10-07T20:43:36.898Z",
                  "count": 1,
                  "total": 1,
                  "offset": 0,
                  "limit": 1,
                  "next": null,
                  "data": [
                    {
                      "venue": "hyperliquid",
                      "venueSymbol": "BTC",
                      "venueMarketId": "0",
                      "base": "BTC",
                      "quote": "USD",
                      "assetClass": "crypto",
                      "contractMultiplier": 1,
                      "markPrice": 83372,
                      "indexPrice": 83395.3,
                      "change24hPct": -2.622143,
                      "volume24hUsd": 2840971957.169653,
                      "openInterestUsd": 3312338623.98568,
                      "openInterestBase": 39729.62894,
                      "fundingRateHourly": 0.000013,
                      "shortFundingRateHourly": null,
                      "borrowRateHourlyLong": null,
                      "borrowRateHourlyShort": null,
                      "openInterestLongUsd": null,
                      "openInterestShortUsd": null,
                      "upsideMaxLeverage": null,
                      "fundingIntervalHours": 1,
                      "nextFundingTime": "2026-10-07T21:00:00.000Z",
                      "maxLeverage": 40,
                      "premium": -0.000279,
                      "fundingApr": 0.1095,
                      "openInterestShare": 0.646371
                    }
                  ],
                  "docs": "https://optimistfi.com/perps/data"
                }
              }
            }
          },
          "400": {
            "description": "invalid_parameter: A parameter is missing, out of range or not one of its allowed values. The message names it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    },
    "/api/perps/venues": {
      "get": {
        "operationId": "venues",
        "summary": "List venues",
        "description": "The venue registry (network, settlement, funding interval, source endpoint) joined to each venue's live health, size and known gaps.\n\nRebuilt every 4 seconds (Hyperliquid and its builder venues every 10); polling faster returns the same data.",
        "tags": [
          "Live"
        ],
        "security": [],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "asOf": "2026-10-07T20:43:36.898Z",
                  "count": 29,
                  "data": [
                    {
                      "id": "veranta",
                      "name": "Veranta",
                      "network": "Base",
                      "settlement": "USDC",
                      "site": "https://www.veranta.xyz",
                      "apiDocs": "https://sdk.veranta.xyz",
                      "endpoint": "https://socket-api-pub.veranta.xyz/socket-api/v1/data",
                      "fundingIntervalHours": 1,
                      "venue": "veranta",
                      "ok": true,
                      "fetchedAt": "2026-10-07T20:43:28.136Z",
                      "latencyMs": 158,
                      "marketCount": 170,
                      "error": null,
                      "gaps": [
                        "price, 24h change and 24h volume (not in the public feed)"
                      ],
                      "openInterestUsd": 58844038.28,
                      "volume24hUsd": 0,
                      "volumeReported": false,
                      "openInterestLongUsd": 29069186.45,
                      "openInterestShortUsd": 29774851.83,
                      "openInterestShare": 0.00262
                    }
                  ],
                  "docs": "https://optimistfi.com/perps/data"
                }
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    },
    "/api/perps/whales": {
      "get": {
        "operationId": "whales",
        "summary": "Whale trades",
        "description": "The newest large taker orders of the last hour: $100K or more in crypto, $25K or more in stock, commodity, FX and index perps, on Lighter, Aster and Hyperliquid, at most two per market. Fills are grouped back into the order that made them. Sizes only: no wallet, account or transaction hash.\n\nRefreshed every 4 seconds.",
        "tags": [
          "Live"
        ],
        "security": [],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "asOf": "2026-10-07T20:43:28.132Z",
                  "windowMinutes": 60,
                  "thresholds": {
                    "crypto": 100000,
                    "other": 25000
                  },
                  "venues": [
                    "lighter"
                  ],
                  "trades": [
                    {
                      "id": "aster:BTC:1791405725600:sell:299957",
                      "venue": "aster",
                      "base": "BTC",
                      "name": "Bitcoin",
                      "slug": "btc",
                      "assetClass": "crypto",
                      "side": "sell",
                      "notionalUsd": 299957,
                      "price": 83321.458972,
                      "time": 1791405725600,
                      "maxLeverage": 200
                    }
                  ],
                  "docs": "https://optimistfi.com/perps/data"
                }
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    },
    "/api/perps/live": {
      "get": {
        "operationId": "live",
        "summary": "Market overview",
        "description": "The perps front page in one payload: the market strip, trending stock and macro perps, cost to hold at 10x, top gainers and losers, each row with its leverage cap and 24-hour sparkline.\n\nRefreshed every 4 seconds.",
        "tags": [
          "Live"
        ],
        "security": [],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "asOf": "2026-10-07T20:43:28.760Z",
                  "venuesOk": 28,
                  "stripMarkets": [
                    {
                      "id": "all",
                      "label": "All",
                      "rows": [
                        {
                          "base": "US500",
                          "slug": "us500",
                          "name": "S&P 500",
                          "label": "S&P 500",
                          "assetClass": "index",
                          "price": 7794.858339,
                          "change24hPct": -0.359364,
                          "openInterestUsd": 411354088.602461,
                          "maxLeverage": 100,
                          "maxLeverageVenue": "ostium",
                          "upsideMaxLeverage": null,
                          "closes": [
                            7826.1
                          ]
                        }
                      ]
                    }
                  ],
                  "stocks": [
                    {
                      "base": "RIVN",
                      "slug": "rivn",
                      "name": "Rivian Automotive, Inc.",
                      "label": "RIVN",
                      "assetClass": "equity",
                      "price": 14.35325,
                      "change24hPct": -1.081938,
                      "openInterestUsd": 2582871.683524,
                      "maxLeverage": 50,
                      "maxLeverageVenue": "ostium",
                      "upsideMaxLeverage": null,
                      "closes": [
                        14.524
                      ],
                      "positionsChange24hPct": 57
                    }
                  ],
                  "macro": [
                    {
                      "base": "KORU",
                      "slug": "koru",
                      "name": "South Korea 3x bull",
                      "label": "KORU",
                      "assetClass": "index",
                      "price": 20.187957,
                      "change24hPct": -4.764722,
                      "openInterestUsd": 5420829.301803,
                      "maxLeverage": 10,
                      "maxLeverageVenue": "tradexyz",
                      "upsideMaxLeverage": null,
                      "closes": [
                        21.35
                      ],
                      "positionsChange24hPct": 66.8
                    }
                  ],
                  "trendingBasis": {
                    "stocks": "positions",
                    "macro": "positions"
                  },
                  "gainers": [
                    {
                      "base": "NATGAS",
                      "slug": "natgas",
                      "name": "Nat gas",
                      "label": "NATGAS",
                      "assetClass": "commodity",
                      "price": 3.287854,
                      "change24hPct": 4.787844,
                      "openInterestUsd": 44745952.088534,
                      "maxLeverage": 45,
                      "maxLeverageVenue": "gmx",
                      "upsideMaxLeverage": null,
                      "closes": [
                        3.125
                      ]
                    }
                  ],
                  "losers": [
                    {
                      "base": "BB",
                      "slug": "bb",
                      "name": "BlackBerry",
                      "label": "BB",
                      "assetClass": "equity",
                      "price": 8.780358,
                      "change24hPct": -8.990801,
                      "openInterestUsd": 15003657.127062,
                      "maxLeverage": 50,
                      "maxLeverageVenue": "ostium",
                      "upsideMaxLeverage": null,
                      "closes": [
                        9.543
                      ]
                    }
                  ],
                  "costs": [
                    {
                      "base": "NATGAS",
                      "name": "Nat gas",
                      "slug": "natgas",
                      "longVenue": "gmx",
                      "shortVenue": "extended",
                      "longDailyPct": 9.571366,
                      "shortDailyPct": 45.168,
                      "apartYearPct": 1299.277124,
                      "maxLeverage": 45
                    }
                  ],
                  "oiPickups": [
                    {
                      "base": "BSV",
                      "slug": "bsv",
                      "name": "Bitcoin SV",
                      "openInterestUsd": 4739229.095311,
                      "addedUsd": 3388698,
                      "change24hPct": 250.9,
                      "change1hPct": -0.1
                    }
                  ],
                  "highlight": {
                    "base": "XAU",
                    "slug": "xau",
                    "name": "Gold",
                    "rowName": "Gold",
                    "venueCount": 18,
                    "maxLeverage": 200,
                    "maxLeverageVenue": "veranta",
                    "verantaOpenInterestUsd": 2379622.87,
                    "verantaLongShare": 0.499828,
                    "venues": [
                      {
                        "venue": "veranta",
                        "maxLeverage": 200,
                        "openInterestUsd": 2379622.87,
                        "longPaysYearPct": 11.196857
                      }
                    ]
                  },
                  "docs": "https://optimistfi.com/perps/data"
                }
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    },
    "/api/perps/data/markets": {
      "get": {
        "operationId": "dataMarkets",
        "summary": "List dataset markets",
        "description": "Every stock, commodity, FX and index perp the dataset serves: venue, symbol, underlying, leverage cap, funding interval and when its record starts.\n\nPrivate, cached for 5 minutes; the hourly record gains a row an hour.",
        "tags": [
          "Historical dataset"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "class",
            "in": "query",
            "required": false,
            "description": "A comma list of classes. Default: all four.",
            "schema": {
              "type": "string",
              "enum": [
                "equity",
                "commodity",
                "fx",
                "index"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "x-ratelimit-limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "x-ratelimit-remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "x-ratelimit-reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "venues": [
                    "hyperliquid",
                    "tradexyz",
                    "kinetiq",
                    "entropyio",
                    "paragon",
                    "lighter",
                    "gains",
                    "qfex",
                    "veranta"
                  ],
                  "classes": [
                    "equity",
                    "commodity",
                    "fx",
                    "index"
                  ],
                  "markets": [
                    {
                      "venue": "tradexyz",
                      "venueSymbol": "xyz:TSLA",
                      "base": "TSLA",
                      "assetClass": "equity",
                      "ticker": "TSLA",
                      "maxLeverage": 20,
                      "fundingIntervalHours": 1,
                      "firstSeen": "2026-09-28T18:53:47Z",
                      "lastSeen": "2026-10-07T20:00:14Z"
                    }
                  ],
                  "count": 1,
                  "byVenue": {
                    "tradexyz": {
                      "equity": 1
                    }
                  },
                  "bases": 1
                }
              }
            }
          },
          "400": {
            "description": "invalid_parameter: A parameter is missing, out of range or not one of its allowed values. The message names it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "401": {
            "description": "unauthorized: A dataset endpoint was called without a valid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "429": {
            "description": "rate_limited: More than 60 dataset requests in a minute on one key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "retry-after": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    },
    "/api/perps/data/history": {
      "get": {
        "operationId": "dataHistory",
        "summary": "Hourly history",
        "description": "The hourly record of an underlying on every served venue: mark and index price, premium, open interest in total and by side, 24-hour volume, funding and borrow for each side, and the leverage cap. At most 92 days a request.\n\nPrivate, cached for 5 minutes; the hourly record gains a row an hour.",
        "tags": [
          "Historical dataset"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "base",
            "in": "query",
            "required": true,
            "description": "The underlying: TSLA, XAU, EURUSD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "venue",
            "in": "query",
            "required": false,
            "description": "Only this venue's markets.",
            "schema": {
              "type": "string",
              "enum": [
                "hyperliquid",
                "tradexyz",
                "kinetiq",
                "entropyio",
                "paragon",
                "lighter",
                "gains",
                "qfex",
                "veranta"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start: epoch seconds, a date (2026-09-01) or an ISO time. Default: 7 days before `to`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End, in the same forms. Default: now.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "CSV has one header row with the same field names.",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "x-ratelimit-limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "x-ratelimit-remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "x-ratelimit-reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "base": "TSLA",
                  "from": "2026-10-07T18:00:00Z",
                  "to": "2026-10-07T20:00:00Z",
                  "count": 1,
                  "columns": [
                    "timestamp",
                    "time",
                    "venue",
                    "venueSymbol",
                    "base",
                    "markPrice",
                    "indexPrice",
                    "premium",
                    "openInterestUsd",
                    "openInterestLongUsd",
                    "openInterestShortUsd",
                    "volume24hUsd",
                    "fundingRateHourly",
                    "shortFundingRateHourly",
                    "borrowRateHourlyLong",
                    "borrowRateHourlyShort",
                    "maxLeverage"
                  ],
                  "rows": [
                    {
                      "timestamp": 1791403200,
                      "time": "2026-10-07T20:00:00Z",
                      "venue": "tradexyz",
                      "venueSymbol": "xyz:TSLA",
                      "base": "TSLA",
                      "markPrice": 377.82,
                      "indexPrice": 377.7,
                      "premium": 0.000318,
                      "openInterestUsd": 46047989.79,
                      "openInterestLongUsd": null,
                      "openInterestShortUsd": null,
                      "volume24hUsd": 23660329.57,
                      "fundingRateHourly": 0.00000625,
                      "shortFundingRateHourly": null,
                      "borrowRateHourlyLong": null,
                      "borrowRateHourlyShort": null,
                      "maxLeverage": 20
                    }
                  ]
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "invalid_parameter: A parameter is missing, out of range or not one of its allowed values. The message names it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "401": {
            "description": "unauthorized: A dataset endpoint was called without a valid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "429": {
            "description": "rate_limited: More than 60 dataset requests in a minute on one key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "retry-after": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    },
    "/api/perps/data/funding": {
      "get": {
        "operationId": "dataFunding",
        "summary": "Funding history",
        "description": "Every funding settlement of an underlying on every served venue, as a rate per hour, back to each listing where the venue publishes it. At most 366 days a request.\n\nPrivate, cached for 5 minutes; the hourly record gains a row an hour.",
        "tags": [
          "Historical dataset"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "base",
            "in": "query",
            "required": true,
            "description": "The underlying: TSLA, XAU, EURUSD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "venue",
            "in": "query",
            "required": false,
            "description": "Only this venue's markets.",
            "schema": {
              "type": "string",
              "enum": [
                "hyperliquid",
                "tradexyz",
                "kinetiq",
                "entropyio",
                "paragon",
                "lighter",
                "gains",
                "qfex",
                "veranta"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start: epoch seconds, a date (2026-09-01) or an ISO time. Default: 7 days before `to`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End, in the same forms. Default: now.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "CSV has one header row with the same field names.",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "x-ratelimit-limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "x-ratelimit-remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "x-ratelimit-reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "base": "TSLA",
                  "from": "2026-10-07T18:00:00Z",
                  "to": "2026-10-07T20:00:00Z",
                  "count": 1,
                  "columns": [
                    "timestamp",
                    "time",
                    "venue",
                    "venueSymbol",
                    "base",
                    "fundingRateHourly"
                  ],
                  "rows": [
                    {
                      "timestamp": 1791399600,
                      "time": "2026-10-07T19:00:00Z",
                      "venue": "tradexyz",
                      "venueSymbol": "xyz:TSLA",
                      "base": "TSLA",
                      "fundingRateHourly": 0.00000625
                    }
                  ]
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "invalid_parameter: A parameter is missing, out of range or not one of its allowed values. The message names it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "401": {
            "description": "unauthorized: A dataset endpoint was called without a valid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "429": {
            "description": "rate_limited: More than 60 dataset requests in a minute on one key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "retry-after": {
                "$ref": "#/components/headers/RetryAfter"
              }
            }
          },
          "503": {
            "description": "unavailable: No venue, or the dataset, answered in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer <key>. Keys are issued at /perps/data/request."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "code",
          "requestId"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in words."
          },
          "code": {
            "type": "string",
            "enum": [
              "invalid_parameter",
              "unauthorized",
              "not_found",
              "rate_limited",
              "unavailable"
            ]
          },
          "requestId": {
            "type": "string",
            "description": "Quote it when asking about a request."
          },
          "docs": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "This request's id: the caller's own x-request-id when sent, otherwise a new one.",
        "schema": {
          "type": "string"
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait before the next request.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitLimit": {
        "description": "Requests allowed per minute on this key.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitRemaining": {
        "description": "Requests left in the current minute.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitReset": {
        "description": "When the current minute's window resets, epoch seconds.",
        "schema": {
          "type": "integer"
        }
      }
    }
  }
}