市场数据 API

基础信息

• Base URL: http://localhost:6789/api/v1
• 响应格式: JSON（信封包裹 {ok, schema_version, query_time, results, ...}）
• 错误处理: 数据级失败降级返回空结构（HTTP 200）；系统级错误由信封中间件统一包裹为 {ok: false, error} 并透传 4xx/5xx 状态码

市场概览

GET /market/overview

市场概况聚合：板块涨跌榜 + 涨停/跌停家数。它把 industry_rank 的涨幅前 5 与 跌幅前 5 拼成一个 sectors 数组，另从 distribution 取两个家数，不包含情绪/资金流/ 热门股/热力图（那些各有独立端点，见下表）。

响应（results 字段内的结构）:

{
  "sectors": [
    {"code": "BK0438", "name": "食品饮料", "change_percent": 3.12, "rank": 1},
    {"code": "BK1036", "name": "电子化学品", "change_percent": -2.41, "rank": 31}
  ],
  "limit_up": 45,
  "limit_down": 8,
  "timestamp": "2026-09-25T15:12:03.482114"
}

不要把 overview 当成「一站式首页载荷」

早期版本曾计划让 overview 一次返回六大块，实际实现刻意拆成按类型的独立端点 （/market/sentiment、/market/distribution、/market/fund-flow、 /market/industry-rank、/realtime/hot-stocks、/realtime/sector-treemap）： 六块里各块的 TTL 与失败降级互不相同，合成一个端点后任一源失败会拖垮整页载荷。 按 overview 的文档结构去解析前端会全落空。

端点索引（market / realtime）

/market 与 /realtime 的全部在用端点；下表之外的细节与完整 schema 见 http://localhost:6789/docs（Swagger）。

方法	路径	参数（默认值）	说明
GET	/market/sentiment	—	指数 + 涨跌统计 + 情绪评分 + 月涨幅
GET	/market/indices	—	主要指数实时数据（sentiment.indices 切片）
GET	/market/distribution	—	涨跌分布（涨/平/跌/涨停/跌停）
GET	/market/industry-rank	—	行业涨跌 TOP5（涨幅前 5 + 跌幅前 5）
GET	/market/fund-flow	—	总成交额、主力净流入、封板成功率
GET	/market/breadth-intraday	days=5（1~60）	盘中市场广度时序（app_market_breadth_intraday，交易时段每 5 分钟采样）；每点含家数/涨跌停 + 同趟脉搏（上证·深证成指点位与涨跌幅、沪深成交额（亿元），深市成交额走深证综指 399106）
GET	/market/limit-count-history	days=60（1~250）	涨停/跌停家数历史（回算口径与供应商权威口径并排输出）
GET	/market/emotion-cycle	days=60（1~250）	情绪周期序列（情绪分/赚钱效应/炸板率/连板高度 + 阶段判定；服务端计算，含当日临期点）
GET	/market/index-calendar	code=""（留空=上证指数）、days=365（90~750）	近一年指数涨跌日历（逐日涨跌幅 + 汇总；读本地 fox_index_daily，零 HTTP）
GET	/market/cross-market-risk	—	跨市场风险温度（九项透明规则评分：境内 3 + 外围 6；陈旧/缺失项剔除不计分，覆盖数决定置信度；服务端整体缓存 60s）
GET	/market/event-chain	—	事件传导链（快讯线索 → 宏观传导路径 → A 股风格映射 + 当日板块实证 → 失效条件）；🔴 weight 是"多少条快讯提到"，不是已确认事件、不进任何评分；观察指标读数与 /market/cross-market-risk 共用同一个 60s 缓存键（两块面板并排时数值/出处逐字相同）
GET	/market/share-brief	—	今日分享简报图（1200×630 SVG 文本，社交分享用：风险温度 + A 股收盘 + 短线情绪 + 跨市场 6 格 + 结论）；全部复用既有载荷（零新增取数口径、零图像依赖，字符串拼装），svg 为最终显示文本 → 前端一个数都不重算；🔴 缺值显示「—」而非 0、整段无数据则该块不出现并在页脚「未纳入评分」点名、无可用事实时 svg=null 且看 brief.note；风险温度读数与 /market/cross-market-risk、/market/event-chain 共用同一个 60s 缓存键（三处并排时分数逐字相同）
GET	/market/calendar	—	A 股交易日历与当前市场状态
GET	/market/regime	—	当日市场情绪阶段快照（优先读每日 15:45 落库，缺失才现算）
GET	/market/phase-history	days=90	情绪阶段历史：行序列 + 阶段段 + 当前持续 + 转移分布
GET	/market/news-marquee	code=""、name=""	新闻跑马灯（新浪滚动 + 腾讯入口聚合）
GET	/market/backtest	code、profile=moderate、initial_capital=100000、lookback_days=250	ATR 动态止损回测
GET	/market/backtest/strategies	—	可用 ATR 止损风格列表
GET	/market/backtest/strategy	code、strategy=ma_cross、fast_period/slow_period、initial_capital、lookback_days、validate	信号策略回测（含 A 股涨跌停约束 + 费率模型）
GET	/market/backtest/strategy/list	—	回测引擎支持的 9 大经典策略列表
GET	/market/factors/list	—	已注册因子清单（纯函数因子注册表）
GET	/market/factors/bench	codes、forward_days=5、lookback_days=250	因子 IC 横评
POST	/market/change-detector/compare	body: {entity_type, entity_id, payload}	通用变化检测（对比上次快照产出差异）
GET	/market/change-detector/history/{entity_type}	entity_id=""	查询该实体的变化历史
GET	/realtime/trading-time	—	当前是否 A 股交易时间（含节假日日历判定）
GET	/realtime/hot-stocks	limit=20、market=20（10/20/30）	热门股票排行（降级链 L1 fox_stock_wide）
GET	/realtime/abnormal-moves	limit=20、use_cache=true	三类异动聚合（竞价 / 盘中 / 偏离值）
GET	/realtime/sector-treemap	—	板块涨跌热力图
GET	/realtime/money-flow/{code}	—	个股日级资金流趋势（fox 引擎统一入口）
GET	/realtime/stock-changes	—	东财 push2ex 实时异动（熔断 + 受限并发 + stale 兜底）
GET	/realtime/stream	—	SSE 事件流（quotes_updated）
GET	/realtime/quote-stream	symbols（逗号分隔，必填）、last_event_id	逐标的报价推送 SSE，带全量载荷

hot_stocks 与 sector_treemap 挂在 /realtime 前缀下，不在 /market。

GET /market/sentiment

单独获取市场情绪数据（指数 + 涨跌统计 + 情绪评分 + 月涨幅）。

响应示例（信封包裹后的 results 字段）:

{
  "indices": [{"code": "000001", "name": "上证指数", "price": 3900.35, "change_percent": 0.57}],
  "breadth": {"up": 3200, "down": 1500, "flat": 300, "total": 5000},
  "sentiment_score": 62,
  "sentiment_label": "中性",
  "monthly_change_percent": -1.78,
  "sample_based": false,
  "timestamp": "2026-08-06T13:00:00"
}

字段	类型	说明
monthly_change_percent	float | null	上证指数近 22 个交易日累计涨跌幅（rolling 22-day return，即 22 个交易日前收盘 → 今日收盘，非自然月 MTD；≈月涨幅，用于月线定调阶段判断），数据源为新浪指数日线（sh000001），失败时返回 null
sample_based	bool	广度是否来自抽样估算源（腾讯样本约 50 只）

数据源优先级：交易时段 TDX TCP → 腾讯 → 东财（新浪仅作 fund_flow 备用）；非交易时段腾讯优先（腾讯 → TDX，收盘快照更稳）。全部失败时降级 DB 历史快照，再降级返回空结构。月涨幅固定使用新浪指数日线（sh000001）。

GET /realtime/abnormal-moves

三类异动聚合（竞价 / 盘中 / 偏离值），一页覆盖。

参数:

参数	类型	默认	说明
limit	int	20	每类返回条数（服务端夹取 [5, 50]）
use_cache	bool	true	false 绕过服务端分档 TTL 强制重算（供手动「刷新」按钮使用）

响应:

{
  "generated_at": "2026-09-25 10:12:03",
  "elapsed_s": 0.0,
  "cached": true,
  "auction_date": "20260924",
  "auction_status": "ready",
  "auction": [
    {
      "code": "600000", "name": "浦发银行",
      "auction_price": 10.5, "prev_close": 10.0, "change_pct": 5.0,
      "matched_vol": 1000, "unmatched_vol": 200,
      "direction": "抢筹", "limit_days": 2
    }
  ],
  "intraday": [],
  "deviation": [],
  "counts": { "auction": 1, "intraday": 0, "deviation": 0 }
}

三段的口径:

段	口径	数据源
auction	昨日涨停股在今日集合竞价（09:15–09:25）的表现；change_pct = 09:25 最终撮合价 / 昨收 − 1，direction 由未匹配买卖方向判「抢筹 / 抛压 / 均衡」，limit_days 是昨日连板数	TDX get_auction（0x056A 撮合序列）+ 东财 getYesterdayZTPool（池）+ 腾讯行情（昨收）
intraday	东财 push2ex 实时异动（火箭发射 / 封涨停 / 开板等）	东财 push2ex
deviation	龙虎榜上榜原因含「偏离」的记录（交易所异动规则口径）	龙虎榜

竞价段的「昨日涨停股」口径

竞价窗口（09:15–09:25）内今日涨停池尚未成型，只有昨日涨停股是可预期的观察对象， 这是打板/接力盯盘的标准口径。故池子取 yesterday_limit_up_pool() （东财 getYesterdayZTPool，返回「参考交易日之前一个交易日」的涨停池）， 不是今日涨停池 —— 否则 09:30 后成分会随今日池填充而静默漂移。 auction_date 即该「昨日」的日期（YYYYMMDD）。

auction_status：非交易日 / 盘前为什么是空的

TDX get_auction 返回的撮合序列只有 time 字段、没有日期，在「非交易日」或 「交易日 09:15 之前」请求时它给出的是上一交易日的序列（数值看着完全正常）。 为避免把昨日行情当成「今日竞价」展示，服务端按交易日历 + 窗口起点设闸门：

auction_status	条件	auction
ready	交易日且 ≥ 09:15	正常返回
pre_auction	交易日但 < 09:15	空，不触 TDX
non_trading_day	周末 / 法定休市	空，不触 TDX

闸门同样作用于 use_cache=false；intraday / deviation 不受影响。 前端应据此显示「今日休市」/「今日竞价尚未开始」，而不是笼统的「暂无数据」。

服务端缓存：三个子源的真实变化频率差异极大，故按频率分档（services/abnormal_moves.py）：

段	TTL
auction（竞价窗口内 09:15–09:30）	20s
auction（窗口外）	1800s（撮合 09:25 落定 + 昨收固定 + 池子固定 → 全字段冻结）
intraday	20s
deviation	1800s
任一子源的空结果	20s（短 TTL：既不污染长窗口，也不让空态每轮重打数据源）

数据来源标识

响应中可能包含 _source 字段标识数据来源（部分场景下挂在明细项上，如 hot_stocks.stocks[]._source）：

值	含义
tdx	通达信 TCP（实时盘口/指数/涨跌统计）
tencent	腾讯财经 HTTP
eastmoney	东方财富 HTTP
sina_backup	新浪备用源（fund_flow 东财受限时）
fox_stock_wide	fox 宽表（全市场盘后口径，热门股降级链 L1）
fox_quote_snapshot	fox 自选股行情快照（样本口径）
xueqiu	雪球（热门股人气榜补充源）
db_history	fox 持久层历史兜底

builders.py 会把首个明细项的 _source 提升为整体 _source（如热门股的来源）， 前端据此区分「全市场盘后口径」与「实时/样本口径」。

相关文档

• 个股数据 API
• 数据管理 API
• 端点路由速查（全量索引 + 降级链口径）
• 数据源集成