{
  "ok": true,
  "name": "SurgeFlow Public Data Contract",
  "site": "https://surgeflows.capital",
  "generated_at": "2026-11-18T02:39:01.783Z",
  "version": "public-data-v1",
  "purpose": "Public research snapshots for external agents, notebooks, search systems, and attribution-safe sharing.",
  "markets": [
    {
      "code": "us",
      "label": "United States",
      "benchmark": "S&P 500",
      "coverage": {
        "market_watch": "live_or_daily",
        "momentum": "live_or_latest_market_session",
        "macro": "daily_source_refresh",
        "factor_research": "daily_freshness_contract_with_weekly_cascade",
        "news": "4_market_feed_with_depth_by_source",
        "whales": "filing_frequency_by_market"
      }
    },
    {
      "code": "cn",
      "label": "China",
      "benchmark": "CSI 300",
      "coverage": {
        "market_watch": "live_or_daily",
        "momentum": "live_or_latest_market_session",
        "macro": "daily_source_refresh",
        "factor_research": "daily_freshness_contract_with_weekly_cascade",
        "news": "4_market_feed_with_depth_by_source",
        "whales": "filing_frequency_by_market"
      }
    },
    {
      "code": "jp",
      "label": "Japan",
      "benchmark": "Nikkei 225",
      "coverage": {
        "market_watch": "live_or_daily",
        "momentum": "live_or_latest_market_session",
        "macro": "daily_source_refresh",
        "factor_research": "daily_freshness_contract_with_weekly_cascade",
        "news": "4_market_feed_with_depth_by_source",
        "whales": "filing_frequency_by_market"
      }
    },
    {
      "code": "hk",
      "label": "Hong Kong",
      "benchmark": "Hang Seng Index",
      "coverage": {
        "market_watch": "live_or_daily",
        "momentum": "live_or_latest_market_session",
        "macro": "daily_source_refresh",
        "factor_research": "daily_freshness_contract_with_weekly_cascade",
        "news": "4_market_feed_with_depth_by_source",
        "whales": "filing_frequency_by_market"
      }
    }
  ],
  "snapshots": [
    {
      "id": "momentum-hotlist",
      "json": "https://surgeflows.capital/api/public/snapshots/momentum-hotlist.json",
      "csv": "https://surgeflows.capital/api/public/snapshots/momentum-hotlist.csv",
      "params": [
        "market"
      ]
    },
    {
      "id": "macro-indicators",
      "json": "https://surgeflows.capital/api/public/snapshots/macro-indicators.json",
      "csv": "https://surgeflows.capital/api/public/snapshots/macro-indicators.csv",
      "params": []
    },
    {
      "id": "news-sentiment",
      "json": "https://surgeflows.capital/api/public/snapshots/news-sentiment.json",
      "csv": "https://surgeflows.capital/api/public/snapshots/news-sentiment.csv",
      "params": [
        "days"
      ]
    },
    {
      "id": "factor-overview",
      "json": "https://surgeflows.capital/api/public/snapshots/factor-overview.json",
      "csv": "https://surgeflows.capital/api/public/snapshots/factor-overview.csv",
      "params": [
        "market"
      ]
    },
    {
      "id": "data-freshness",
      "json": "https://surgeflows.capital/api/public/snapshots/data-freshness.json",
      "csv": "https://surgeflows.capital/api/public/snapshots/data-freshness.csv",
      "params": []
    }
  ],
  "docs": {
    "openapi": "https://surgeflows.capital/api/public/openapi.json",
    "robots": "https://surgeflows.capital/robots.txt",
    "sitemap": "https://surgeflows.capital/sitemap.xml",
    "llms": "https://surgeflows.capital/llms.txt",
    "llms_full": "https://surgeflows.capital/llms-full.txt"
  },
  "answers": {
    "note": "Small dated answers (no key): one JSON document per topic with its own observation dates. Research data only; not investment advice.",
    "sources": [
      {
        "id": "hotlist",
        "json": "https://surgeflows.capital/api/public/signature/hotlist.json",
        "method": "https://surgeflows.capital/research/turnover-surge-amihud-illiquidity"
      },
      {
        "id": "news",
        "json": "https://surgeflows.capital/api/public/signature/news.json",
        "method": "https://surgeflows.capital/research/research-integrity-standards"
      },
      {
        "id": "macro",
        "json": "https://surgeflows.capital/api/public/signature/macro.json",
        "method": "https://surgeflows.capital/research/macro-leading-coincident-lagging-indicators"
      },
      {
        "id": "breadth",
        "json": "https://surgeflows.capital/api/public/signature/breadth.json",
        "method": "https://surgeflows.capital/research/research-integrity-standards"
      },
      {
        "id": "factor-reference",
        "json": "https://surgeflows.capital/api/public/signature/factor-reference.json",
        "method": "https://surgeflows.capital/methodology/factor-research"
      },
      {
        "id": "factor-overview",
        "json": "https://surgeflows.capital/api/public/signature/factor-overview.json",
        "method": "https://surgeflows.capital/methodology/factor-research"
      }
    ]
  },
  "company_preview": "https://surgeflows.capital/api/public/company-preview?market=us&ticker=NVDA",
  "caveats": [
    "Research data only; not investment advice.",
    "Market data may be delayed or stale when venues are closed.",
    "Coverage depth differs by market and source availability.",
    "CSV snapshots flatten nested fields and may JSON-encode complex cells.",
    "The no-key momentum-hotlist snapshot may be a capped sample for every caller: at most the top 3 names by selection rank, public columns only. data.total_count when present (CSV: board_total_count) is the full board size; truncated marks a capped answer. The full board is on the signed-in site or the keyed API (/api/v1/markets/<code>/hotlist)."
  ]
}