{
  "openapi": "3.1.0",
  "info": {
    "title": "Buildix Crypto Orderflow API",
    "description": "Real-time crypto orderflow analytics API. Price, volume, funding and open interest for 170+ listed Hyperliquid perpetual futures pairs; VPIN, CVD, OBI, whale tracking and signal scores on the 100 most liquid of them. Static file: the figures mirror lib/seo/coverage.ts, update both together.",
    "version": "1.0.0",
    "contact": {
      "name": "Buildix",
      "url": "https://www.buildix.trade",
      "email": "hello@buildix.trade"
    },
    "x-logo": {
      "url": "https://www.buildix.trade/icon-512.png"
    }
  },
  "servers": [
    {
      "url": "https://www.buildix.trade/api/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/screener": {
      "get": {
        "summary": "Get all pairs with live data",
        "description": "Returns every Hyperliquid main-dex perpetual in the exchange metadata (170+ listed pairs) with price, volume, funding rate, open interest, and 24h change. Delisted markets are still in that metadata and come back with zero volume and zero open interest. Useful for building screeners and dashboards.",
        "operationId": "getScreener",
        "parameters": [
          {
            "name": "X-API-Key",
            "in": "header",
            "description": "Your Buildix API key (optional for basic access)",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of pair objects",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pairs": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Pair" }
                    },
                    "count": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/signals": {
      "get": {
        "summary": "Get orderflow signal scores",
        "description": "Returns signal scores (-100 to +100) for all pairs. Includes VPIN, CVD direction, funding rate extremes, whale flow, and composite signal.",
        "operationId": "getSignals",
        "parameters": [
          { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Signal scores per pair",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": { "$ref": "#/components/schemas/SignalScore" }
                }
              }
            }
          }
        }
      }
    },
    "/pair/{symbol}": {
      "get": {
        "summary": "Get detailed pair data",
        "description": "Returns comprehensive data for a single pair including price, volume, funding, OI, VPIN, CVD, signal score, and regime detection.",
        "operationId": "getPair",
        "parameters": [
          { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Pair symbol (e.g. BTC, ETH, SOL)" },
          { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Detailed pair data",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PairDetail" }
              }
            }
          }
        }
      }
    },
    "/deep-view/{symbol}": {
      "get": {
        "summary": "Get deep view orderflow data",
        "description": "Returns full orderflow analytics for a pair: VPIN, CVD history, OBI, OFI, whale trades, smart money delta, absorption events, regime detection. Requires paid API key.",
        "operationId": "getDeepView",
        "parameters": [
          { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Full orderflow analytics",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DeepView" }
              }
            }
          }
        }
      }
    },
    "/smart-money": {
      "get": {
        "summary": "Get smart money wallet positions",
        "description": "Returns current positions of tracked whale wallets on Hyperliquid. Includes wallet labels, account values, position sizes, leverage, and unrealized PnL.",
        "operationId": "getSmartMoney",
        "parameters": [
          { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Whale position data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "wallets": { "type": "integer" },
                    "positions": { "type": "array", "items": { "$ref": "#/components/schemas/WhalePosition" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/funding-arb": {
      "get": {
        "summary": "Get cross-exchange funding arbitrage opportunities",
        "description": "Returns Hyperliquid funding rates compared with Binance and Bybit (Hyperliquid predicted fundings), with arbitrage spread calculations.",
        "operationId": "getFundingArb",
        "parameters": [
          { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Funding rate comparison data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pairs": { "type": "array", "items": { "$ref": "#/components/schemas/FundingArb" } }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pair": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "example": "BTC" },
          "price": { "type": "number", "example": 73302 },
          "change24h": { "type": "number", "example": 0.64 },
          "volume24h": { "type": "number", "example": 8280000000 },
          "openInterest": { "type": "number", "example": 6900000000 },
          "fundingRate": { "type": "number", "example": 0.0001 }
        }
      },
      "SignalScore": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string" },
          "score": { "type": "integer", "minimum": -100, "maximum": 100, "description": "Composite signal: -100 (strong sell) to +100 (strong buy)" },
          "direction": { "type": "string", "enum": ["LONG", "SHORT", "NEUTRAL"] },
          "vpin": { "type": "number", "description": "Volume-Synchronized Probability of Informed Trading (0-1)" },
          "cvd": { "type": "number", "description": "Cumulative Volume Delta in USD" },
          "regime": { "type": "string", "enum": ["trending", "ranging", "volatile", "squeeze"] }
        }
      },
      "PairDetail": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string" },
          "price": { "type": "number" },
          "change24h": { "type": "number" },
          "volume24h": { "type": "number" },
          "openInterest": { "type": "number" },
          "fundingRate": { "type": "number" },
          "vpin": { "type": "number" },
          "vpinLevel": { "type": "string", "enum": ["safe", "elevated", "high", "extreme"] },
          "signalScore": { "type": "integer" },
          "signalDirection": { "type": "string" },
          "regime": { "type": "string" }
        }
      },
      "DeepView": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string" },
          "price": { "type": "number" },
          "cvd": { "type": "number" },
          "cvdHistory": { "type": "array", "items": { "type": "object" } },
          "obi": { "type": "number" },
          "ofi": { "type": "number" },
          "vpin": { "type": "number" },
          "kyleLambda": { "type": "number" },
          "whales": { "type": "array", "items": { "type": "object" } },
          "smartMoney": { "type": "object" },
          "regime": { "type": "string" },
          "signalScore": { "type": "integer" }
        }
      },
      "WhalePosition": {
        "type": "object",
        "properties": {
          "address": { "type": "string" },
          "label": { "type": "string", "nullable": true },
          "category": { "type": "string", "enum": ["fund", "smart_money", "directional_whale", "market_maker", "degen", "insider"] },
          "accountValue": { "type": "number" },
          "symbol": { "type": "string" },
          "side": { "type": "string", "enum": ["long", "short"] },
          "notional": { "type": "number" },
          "leverage": { "type": "number" },
          "entryPrice": { "type": "number" },
          "unrealizedPnl": { "type": "number" }
        }
      },
      "FundingArb": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string" },
          "hl": { "type": "number", "description": "Hyperliquid funding rate" },
          "binance": { "type": "number", "nullable": true },
          "bybit": { "type": "number", "nullable": true },
          "okx": { "type": "number", "nullable": true },
          "dydx": { "type": "number", "nullable": true },
          "maxSpread": { "type": "number", "description": "Max funding rate spread across exchanges" }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}