# 澄澜量化 数据 API

Base URL: `https://app.chenglanai.com`

> 给 AI: 优先使用 `/api/v1/analysis/*` 与 `/api/v1/screen` 的结论, 不要用 `/chart`、`/bars` 的原始 K 线自己重算; MCP 地址 `/mcp`, 接入说明见 `/api/skill.md` 与 `/api/agents.md`。

## 认证与限额

- 在「用户中心 → API」生成 Key(会员可用), 请求时放在请求头: `Authorization: Bearer cl_live_xxx`(也可用 `X-API-Key`)。
- 每个 Key 有每日调用上限(默认 5000 次, 北京时间 0 点重置), 响应头 `X-RateLimit-Limit` / `X-RateLimit-Remaining` 显示额度; 超出返回 429。合作方 Key 可由管理员设为不限额, 此时响应头为 `X-RateLimit-Policy: unlimited`。
- 不带 Key 的请求按 IP 限速(每分钟 300 次), 仅供网页使用; 程序化调用请使用 Key。会员到期后 Key 暂停, 续费自动恢复; 管理员发给合作方的服务级 Key 不随会员到期, 可绑定来源 IP 白名单(不在名单内返回 403)。
- 数据按各市场收盘后计算发布(非实时); 用 `/api/v1/meta` 的 generated / asof 判断是否更新。所有接口只读、返回 JSON, 支持 gzip 与跨域。
- 错误格式: `{"ok": false, "error": "说明"}`; 401 Key 无效或已吊销, 403 会员到期, 404 标的不存在, 429 超出额度。
- 内容为价格周期状态的客观描述, 不构成投资建议。

```bash
curl -H "Authorization: Bearer cl_live_xxx" "https://app.chenglanai.com/api/v1/markets"
```

```python
import requests
r = requests.get("https://app.chenglanai.com/api/v1/list", params={"mkt": "US", "bt": 1, "limit": 50},
                 headers={"Authorization": "Bearer cl_live_xxx"})
print(r.json()["total"])
```

## AI 接入(MCP / Skill)

1. 在「用户中心 → API」生成 API Key(会员可用); 不带 Key 也能用, 按 IP 限速(每分钟 300 次), 适合试用。
2. 在你的 AI 客户端里添加 MCP 服务: 地址 `https://app.chenglanai.com/mcp`, 传输方式 Streamable HTTP, 请求头 `Authorization: Bearer <你的 API Key>`(各客户端配置见下)。
3. 可选: 安装 Skill(给 AI 的使用规则: 什么问题调哪个工具、引用要带数据日期、不要自己用 K 线重算、只描述状态): 下载 `https://app.chenglanai.com/api/skill.md`, 放到 `~/.claude/skills/chenglanai/SKILL.md` 或 `~/.codex/skills/chenglanai/SKILL.md`。
4. 可选: 把 AGENTS 片段(`https://app.chenglanai.com/api/agents.md`)粘贴进项目的 AGENTS.md / CLAUDE.md / Cursor Rules, 让编程助手默认使用澄澜数据。
5. 直接提问即可, 例如:「英伟达现在是什么趋势? 上方压力在哪」「今天美股发生了什么」「这周港股复盘」「找出处于上涨趋势且回踩周中线的美股」。工具调用与 HTTP API 共用同一个 Key 的额度。

**Claude Code**

```bash
claude mcp add --transport http chenglanai https://app.chenglanai.com/mcp --header "Authorization: Bearer $CHENGLAN_API_KEY"
```

**Codex(~/.codex/config.toml)**

```toml
[mcp_servers.chenglanai]
url = "https://app.chenglanai.com/mcp"
bearer_token_env_var = "CHENGLAN_API_KEY"
```

**Cursor(~/.cursor/mcp.json)**

```json
{"mcpServers": {"chenglanai": {"url": "https://app.chenglanai.com/mcp", "headers": {"Authorization": "Bearer ${env:CHENGLAN_API_KEY}"}}}}
```

**其他支持远程 MCP 的客户端(Claude Desktop / Cherry Studio / Dify 等)**

```text
类型: Streamable HTTP(远程 MCP)
URL: https://app.chenglanai.com/mcp
请求头: Authorization: Bearer <你的 API Key>
```

MCP 工具:

| 工具 | 用途 |
|---|---|
| `search_symbol` | 把名称或代码解析成澄澜标的代码(sym, 带市场后缀, 如 英伟达 -> NVDA.US, 腾讯 / 700 -> 00700.HK, 茅台 -> 600519.CN, 比特币 -> BTC.CRYPTO, 标普500 -> SPX.IDX)。其他工具都需要 sym; 不确定代码时先调用本工具。 |
| `get_symbol_analysis` | 返回澄澜量化已经算好的单个标的完整分析(固定规则、无未来函数、每日收盘后更新): 周期态、大趋势(含待确认)、阶段及各自开始日期, 白话解读, 全部关键位(周线布林带、周EMA120/250、下降趋势线、3年低位、月EMA)及距离, 近期状态变化, 美股期权结构与场景, 宏观敏感度, 下次财报日。用户问到某个标的的趋势、走势、周期、支撑压力、关键位、是否破位、期权墙时优先调用本工具并直接引用结果(注明数据日期), 不要自己拿 K 线计算均线或指标。可一次传多个代码。 |
| `get_market_overview` | 某个市场(或全部市场)的周期温度: 大趋势上涨/下跌/未定与待确认家数占比、阶段分布、周线周期态分布、涨跌家数、主要指数的状态, 以及最近一个交易日新出现的重要状态变化。用户问'今天市场怎么样''美股/港股/A股整体处于什么阶段''市场宽度'时调用。 |
| `get_macro_overview` | 宏观概况: 美债 10Y/2Y 收益率、10Y-2Y 期限利差(是否倒挂)、VIX、美元指数与主要汇率、原油黄金等的周期状态与变化, 以及宏观仪表盘中当前显著异动的序列和原因。用户问利率、美元、流动性、宏观环境时调用。 |
| `screen_symbols` | 按周期状态语义筛选全市场标的, 每条附入选理由(why)。可组合: 大趋势、阶段、周期态、贴近某个关键位、最近 N 天出现某类状态变化、美股期权场景。用户要'找出处于上涨趋势且回踩周中线的股票''最近突破旗形的''伽马挤压候选'之类时调用, 不要自己下载全市场数据去算。 |
| `get_recent_changes` | 最近几个交易日的周期状态变化(异动): 大趋势触发/确认/作废、阶段建立、底部提示、周线分型、形态突破跌破、关键位穿越等, 每条带说明文字。用户问'最近有哪些股票趋势反转/突破''某个标的最近发生了什么'时调用。 |
| `get_option_structure` | 美股期权结构(CBOE 延时数据, 覆盖成交额前 200 的美股与 ETF): 看涨墙、看跌墙、最大痛点、PCR、IV30、平值 IV/偏斜/期限、GEX(做市商 gamma 敞口)、伽马翻转位, 以及场景判断(附失效条件)。传 symbol 看单只; 不传返回全市场期权场景榜。用户问期权墙、最大痛点、gamma、期权资金在哪时调用。 |
| `get_state_history` | 某个标的的状态时间线: 大趋势、待确认、阶段各段的起止日期(按当时可知的日期, 无未来函数), 以及历史上的重要状态变化事件。用户问'上涨趋势持续多久了''上次转为下跌是什么时候''过去几年经历了哪些阶段'时调用。 |
| `get_symbol_events` | 个股事件与资金面: 下次与过往财报日, 最近新闻标题(中文), 美股 SEC 内部人交易(Form 4)与发债备案, 美股 FINRA 做空成交占比。用户问新闻、财报、内部人买卖、做空压力时调用。 |
| `get_calendar` | 宏观与财报日历: 美国、中国、欧元区、日本的重要经济数据与议息(公布值/预期/前值, 时间 UTC), 以及未来两周美股财报日。用户问'这周有什么重要数据''美联储什么时候开会''谁要发财报'时调用。 |
| `get_related` | 标的在澄澜知识图谱中的关联: 所属行业/板块/指数、同业、A/H 同名、主题与宏观因子, 以及近期新闻热度与市场主线。用户问'这只股票属于什么板块''和谁联动''最近市场主线是什么'时调用。 |
| `explain_term` | 解释澄澜的术语与规则口径(大趋势、待确认、阶段、周期态、各关键位、各类状态变化图层、期权结构术语等)。回答用户时需要解释某个概念, 或不确定某个字段含义时调用; 不传 term 返回全部术语列表。 |
| `get_daily_report` | 查询某个交易日的市场周期日报: 各市场(美股/港股/A股/加密/商品/宏观)的宽度及与上一份日报的对比、主要指数、按固定权重挑出的重点状态变化及同日关联的事件(市场层/板块/个股新闻财报等, 只写同日发生, 不推断因果)、观察位与未来几天的日历。用户问'今天/昨天市场发生了什么''日报''复盘'时调用; 不含买卖建议。 |
| `get_weekly_report` | 查询某一周(周一到周日)的市场周期周报: 各市场本周首尾宽度对比、状态变化总数、本周重点状态变化与同日关联事件、板块聚集出现天数、经济数据与宏观异动。用户问'这周市场怎么样''本周复盘''周报'时调用; 不含买卖建议。 |
| `get_price_bars` | 原始价格 K 线(日线或周线 OHLCV)。仅在用户明确需要原始价格数据(画图、导出、计算本服务没有提供的指标)时使用; 趋势、支撑压力、周期判断请用 get_symbol_analysis, 不要用 K 线自己重算。 |

> 交易层(买卖点)不在 MCP 中; 需要买卖点的合作方用白名单 Key 直接调 /api/v1/trade/*。

## 接口

### 标的完整分析(AI 首选)

`GET /api/v1/analysis/{sym}`

一次调用拿到单个标的的全部周期结论: 周期态/大趋势/阶段(含开始日期)、白话解读、全部关键位及距离(levels / nearest / key_levels{support, resistance})、stance(大趋势状态的英文标签 bullish / neutral / bearish, 只描述状态)、近期状态变化、美股期权结构与场景、宏观敏感度、下次财报日。白名单调用方另有 signal_id(该标的当前持有中的买卖点)。直接引用 summary, 不要用 /chart 的 K 线自己重算。format=markdown 返回精简 Markdown。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sym | path | string | 是 | 标的代码(带市场后缀) |
| format | query | string |  | markdown = 返回 text/markdown |

示例: `GET /api/v1/analysis/NVDA.US`

```json
{"symbol":{...},"as_of":{"price_date":"2026-10-15","engine":"1.1.0"},"summary":"英伟达(NVDA)截至 2026-10-15 收盘: ...","state":{...},"interpretation":[...],"levels":[...],"nearest":{...},"recent_changes":[...],"options":{"call_wall":350,"put_wall":330,"call_wall_oi":103627,"put_wall_oi":63431,"max_pain":{"price":335,"expiry":"..."},"pc":0.79,"skew":2.1,"skew_note":"均衡","gex_b":1.32,"gex_regime":"正 gamma(抑波)","gamma_flip":337.38,"flip_side":"现价在上方·正伽马区","strikes":[{"k":350,"c":...,"p":...}],"scenarios":[...]},"macro_sensitivity":{...},"notes":{"levels":"百分比为关键位相对现价的距离...","options":"看涨墙 / 看跌墙为现价上方 / 下方未平仓量最集中的行权价..."},"links":{"page":"/s/NVDA.US"},"usage_note":"...","disclaimer":"..."}
```

### 批量分析

`GET /api/v1/analysis`

一次取多个标的的完整分析(最多 20 个)。format=markdown 时拼接各标的的 Markdown。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| syms | query | string | 是 | 逗号分隔的标的代码 |
| format | query | string |  | markdown |

示例: `GET /api/v1/analysis?syms=NVDA.US,AAPL.US`

```json
{"rows":[{分析}, ...]}
```

### 状态时间线

`GET /api/v1/analysis/{sym}/history`

大趋势、待确认、阶段、周期态各段的起止日期(按当时可知的日期, 无未来函数), 以及回看范围内的重要状态变化事件。回答"上涨趋势持续多久了"。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sym | path | string | 是 | 标的代码 |
| years | query | integer |  | 回看几年, 默认 3, 最大 20 |
| format | query | string |  | markdown |

示例: `GET /api/v1/analysis/NVDA.US/history?years=3`

```json
{"sym":"NVDA.US","years":3,"trend":[{...}],"pending":[{...}],"stage":[{...}],"regime":[{...}],"events":[{...}]}
```

### 市场总览

`GET /api/v1/analysis/market/{mkt}`

某市场(或 all)的周期温度: 各状态家数与占比、主要指数状态、最近一个交易日的重要状态变化、美股期权场景分布, 以及一段可直接引用的 summary。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| mkt | path | string | 是 | 市场: US 美股 / HK 港股 / CN A股 / JP 日股 / KR 韩股 / CRYPTO 加密 / CMDTY 商品, all 为全部 |
| format | query | string |  | markdown |

示例: `GET /api/v1/analysis/market/US`

```json
{"mkt":"US","asof":"2026-10-15","n":600,"breadth":{...},"indices":[...],"changes":[...],"option_scenarios":{...},"summary":"..."}
```

### 宏观总览(结论)

`GET /api/v1/analysis/macro`

宏观因子的最新值与周期状态(收益率用 bp 表示日变化)、10Y-2Y 期限利差是否倒挂、宏观仪表盘当前显著异动及原因, 附 summary。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| format | query | string |  | markdown |

示例: `GET /api/v1/analysis/macro`

```json
{"factors":[...],"spread":{"last":0.37,"inverted":false,"note":"10 年期减 2 年期美债收益率; 小于 0 为收益率曲线倒挂, 历史上常出现在经济放缓之前"},"anomalies":[...],"summary":"..."}
```

### 每日市场周期日报(最新)

`GET /api/v1/daily`

按市场分板块(US / HK / CN / JP / KR / CRYPTO / CMDTY / MACRO)的每日日报(中文 / 英文): 宽度及与上一份日报的对比、主要指数、市场层同日事件(drivers: 指数大幅变动、经济数据、宏观异动、宽度变化)、板块聚集(sectors)、按固定权重挑出的重点状态变化(stories, 每条四段: 结果 / 模型依据 / 同日关联 / 观察位, 附归因层级 attribution: market / sector / stock / none 与证据 evidence)、其他变化(others)、未来几天日历(calendar_next)与新闻来源(sources)。每段文字有 text.template(模板, 必有)、text.final(通过数字核对 / 禁用词 / 结构校验的大模型润色, 否则同模板)与 text.source(llm / template); 证据 kind: earnings / news / short / options / macro / insider(SEC Form 4 公开市场买卖) / debt(SEC 发债备案)。同日关联只表示同时发生, 不代表因果。日期 = 交易日, 各板块有自己的 asof, 同一日期会随各市场收盘多次更新。不指定日期时: 带 mkt 取含这些市场的最新一天, 不带 mkt 取含股票市场(美/港/A/日/韩)的最新一天(周末只有加密的日期用 /daily/{date} 或 mkt=CRYPTO 取)。format=markdown 返回可读文本。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| mkt | query | string |  | 只返回某些板块, 逗号分隔: US / HK / CN / JP / KR / CRYPTO / CMDTY / MACRO |
| lang | query | string |  | zh(默认) / en 英文 |
| text | query | string |  | template = 强制模板文字(默认: 通过校验的大模型润色优先, 否则模板; 见 text.final / text.source) |
| format | query | string |  | markdown = 返回 text/markdown |

示例: `GET /api/v1/daily?mkt=US`

```json
{"date":"2026-10-16","v":1,"weights_v":"2026-10-18","generated":1792214054,"weekly_close":true,"thin":false,"headline":{"facts":[{"mkt":"HK","sym":"00700.HK","name":"腾讯控股","L":"stage","t":"▲底部建立","tone":"up"}],"text":{"template":"港股 腾讯控股阶段「▲底部建立」。..."}},"sections":[{"mkt":"US","market_name":"美股","asof":"2026-10-16","weekly_close":false,"main_dir":"up","breadth":{"n":8422,"t_up":1197,"t_down":5333,"prev":{"date":"2026-10-15","t_up":1210,"t_down":5300},"changes_total":3412,"changes_by_layer":{"trend":485}},"indices":[...],"drivers":[{"kind":"index","name":"道琼斯","chg":1.08,"events":[]}],"sectors":[...],"stories":[{"sym":"AA.US","name":"美国铝业公司","score":7.8,"result":[{"L":"trend","t":"×待确认作废","v":41.45,"w":"..."}],"prior":{"L":"trend","bt":0,"bp":1,"since":"2026-09-19","weeks":4},"attribution":"sector","sector_ref":"ent_...","evidence":[...],"levels":[{"name":"周中线","v":49.92,"dist":20.4}],"options":{...},"score_parts":{...},"text":{"template":"结果: ...。模型依据: ...。同日关联: ...。观察位: ...。","result":"...","basis":"...","link":"...","levels":"..."}}],"others":[...],"macro":[],"calendar_next":[...],"sources":[{"id":"s1","title":"...","url":"...","src":"Reuters"}],"text":{"template":"..."}}],"text_source":"template","disclaimer":"..."}
```

### 指定交易日的日报

`GET /api/v1/daily/{date}`

同 /daily, 取指定交易日; 不存在返回 404。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| date | path | string | 是 | 交易日 YYYY-MM-DD |
| mkt | query | string |  | 同 /daily |
| lang | query | string |  | zh / en |
| text | query | string |  | template |
| format | query | string |  | markdown |

示例: `GET /api/v1/daily/2026-10-16?format=markdown`

```json
{同 /daily}
```

### 每周市场周期周报

`GET /api/v1/weekly`

把一周(周一到周日)的日报汇总: 各市场首尾宽度对比、状态变化总数与分图层数量、本周重点条目(同一标的取最高分, 前 10)、板块聚集出现天数、经济数据与宏观异动、最新指数状态与未来日历, 附模板文字。date 为周内任意一天, 默认最新日报所在周。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| date | query | string |  | 周内任意一天 YYYY-MM-DD |
| mkt | query | string |  | 同 /daily |
| lang | query | string |  | zh / en |
| format | query | string |  | markdown |

示例: `GET /api/v1/weekly?date=2026-10-16`

```json
{"week_start":"2026-10-12","week_end":"2026-10-18","dates":["2026-10-12",...],"headline":{"facts":[...],"text":{...}},"sections":[{"mkt":"US","days":[...],"start":{"date":"...","breadth":{...}},"end":{...},"changes_total":1234,"changes_by_layer":{...},"stories":[...],"sectors":[{"id":"ent_...","name":"半导体","days":3,"max_n":12}],"drivers":[...],"indices":[...],"calendar_next":[...],"text":{"template":"...","final":"..."}}],"lang":"zh","disclaimer":"..."}
```

### 周报归档列表

`GET /api/v1/weekly/index`

有日报的各周(倒序), 每项 week_start / week_end / dates。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| limit | query | integer |  | 默认 26, 最大 520 |

示例: `GET /api/v1/weekly/index`

```json
{"rows":[{"week_start":"2026-10-12","week_end":"2026-10-18","dates":["2026-10-16","2026-10-15"]}]}
```

### 每日复盘(精简格式)

`GET /api/v1/analysis/daily`

给合作方嵌入用的日报精简版: 标题、今日要点、整份 Markdown、按条目的 highlights(sym + 四段文字)与各板块总述。内容与 /daily 相同(润色优先, 否则模板)。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| mkt | query | string |  | US / HK / CN / JP / KR / CRYPTO / CMDTY / MACRO, 逗号分隔, all(默认) |
| date | query | string |  | 交易日, 默认最新 |
| lang | query | string |  | zh / en |
| format | query | string |  | markdown |

示例: `GET /api/v1/analysis/daily?mkt=US`

```json
{"d":"2026-10-16","mkt":"US","generated":1792214054,"title":"2026-10-16 美股市场周期日报","summary":"...","markdown":"(整份 Markdown)","highlights":[{"mkt":"US","sym":"AA.US","name":"美国铝业公司","text":"结果: ...。模型依据: ...。同日关联: ...。观察位: ...。","attribution":"sector"}],"sections":[{"mkt":"US","asof":"2026-10-16","text":"..."}],"text_source":"template","lang":"zh","model_v":"1.1.0","disclaimer":"..."}
```

### 日报归档列表

`GET /api/v1/daily/index`

已有日报的日期列表(倒序), 每项含各板块 asof 与条目数、headline、thin(条目过少, 落地页可 noindex)、首次与最后生成时间。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| limit | query | integer |  | 默认 60, 最大 1000 |

示例: `GET /api/v1/daily/index?limit=60`

```json
{"v":1,"rows":[{"date":"2026-10-16","generated":1792214054,"first_generated":1792200000,"thin":false,"weekly_close":true,"headline":{"facts":[...],"text":{"template":"..."}},"sections":[{"mkt":"US","asof":"2026-10-16","stories":8,"sectors":2}]}]}
```

### 语义筛选

`GET /api/v1/screen`

按周期状态语义筛选全市场, 每条附入选理由 why。可组合: 大趋势、阶段、周期态、贴近关键位、最近 N 天的状态变化、美股期权场景。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| market | query | string |  | 市场: US 美股 / HK 港股 / CN A股 / JP 日股 / KR 韩股 / CRYPTO 加密 / CMDTY 商品, all 为全部 |
| kind | query | string |  | 品种: stock / etf / index / equity / crypto / cmdty, 默认全部 |
| trend | query | string |  | 大趋势: up / down / pending_up / pending_down / none |
| stage | query | string |  | 阶段: up / down / none |
| regime | query | string |  | 周线周期态: 单边上涨 / 单边下跌 / 震荡 |
| near | query | string |  | 贴近关键位: weekly_mid / weekly_upper / weekly_lower / ema120 / ema250 / downtrend_line / low3y / monthly_ema120 / monthly_ema250 |
| within | query | number |  | 与 near 搭配: 距关键位不超过多少 %, 默认 2 |
| event | query | string |  | 最近的状态变化: 图层 id(trend/stage/alert/bigpiv/dbl2/wfrac/topbox/flag/range/overheat/e250)或事件名称片段 |
| days | query | integer |  | 与 event 搭配: 最近几个交易日, 默认 3 |
| scenario | query | string |  | 美股期权场景: gamma_squeeze / squeeze / near_support / near_resist / magnet_up / magnet_down |
| liquid | query | integer |  | 0 = 不过滤流动性, 默认只看达标 |
| sort | query | string |  | amt(默认) / chg / chg5 / chg20 / chg60 / chg250 / ytd / mcap / dist |
| limit | query | integer |  | 默认 30, 最大 200 |

示例: `GET /api/v1/screen?trend=up&near=weekly_mid&market=US`

```json
{"total":12,"rows":[{"sym":"...","name":"...","close":0,"chg":0,"trend":"上涨趋势","stage":"阶段上涨","regime":"单边上涨","why":"大趋势上涨趋势 + 阶段上涨; 距周中线 +0.8%","matched":{...}}]}
```

### 原始 K 线

`GET /api/v1/bars/{sym}`

日线或周线 OHLCV, 日期为 YYYY-MM-DD。原始数据, 用于画图/导出; 趋势与支撑压力请用 /analysis, 不要用 K 线自己重算。format=csv 返回 CSV。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sym | path | string | 是 | 标的代码 |
| period | query | string |  | d 日线(默认) / w 周线 |
| limit | query | integer |  | 最近多少根, 默认 120, 最大 1000 |
| format | query | string |  | csv |

示例: `GET /api/v1/bars/NVDA.US?period=d&limit=120`

```json
{"sym":"NVDA.US","period":"d","rows":[{"date":"2026-10-15","open":0,"high":0,"low":0,"close":0,"volume":0}],"note":"原始数据; 趋势/支撑压力请用 /analysis"}
```

### 术语表

`GET /api/v1/glossary`

澄澜术语与字段口径: 大趋势/待确认/阶段/周期态、各关键位、状态变化图层、期权结构术语(GEX、伽马翻转位、最大痛点、PCR、IV 偏斜等)。/glossary/{term} 按名称、别名或 id 查单个。

示例: `GET /api/v1/glossary`

```json
{"rows":[{"id":"trend","name":"大趋势","text":"..."}]}
```

### 数据版本

`GET /api/v1/meta`

引擎版本、生成时间、覆盖标的数、各市场最新交易日。可用来判断数据是否已更新。

示例: `GET /api/v1/meta`

```json
{"v":"1.1.0","spec":"...","generated":1760500000,"n":1529,"asof":{"US":"2026-10-14"}}
```

### 市场周期宽度

`GET /api/v1/markets`

各市场的周期温度: 大趋势上涨/下跌/未定家数、待确认、阶段、周线周期态分布、涨跌家数, 并附各市场主要指数的摘要。

示例: `GET /api/v1/markets`

```json
{"meta":{...},"markets":[{"mkt":"US","asof":"2026-10-14","n":600,"t_up":310,"t_down":180,"t_none":110,"pend_up":12,"pend_down":9,"stage_up":330,"stage_down":270,"regimes":{"单边上涨":240,"震荡":260,"单边下跌":70,"数据不足":30},"adv":350,"dec":250,"indices":["SPX.IDX"],"index_rows":[{...摘要}]}]}
```

### 标的列表(筛选 / 排序 / 分页)

`GET /api/v1/list`

按市场、品种、周期状态筛选, 按任意数值字段排序。返回摘要对象数组(字段见下方「摘要字段」)。语义筛选请优先用 /screen。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| mkt | query | string |  | 市场: US 美股 / HK 港股 / CN A股 / JP 日股 / KR 韩股 / CRYPTO 加密 / CMDTY 商品, all 为全部 |
| kind | query | string |  | 品种: stock / etf / index / crypto / cmdty / equity(股票+ETF) |
| bt | query | integer |  | 大趋势: 1 上涨 / -1 下跌 / 0 未定 |
| bp | query | integer |  | 待确认: 1 上涨待确认 / -1 下跌待确认 / 0 无 |
| st | query | integer |  | 阶段: 1 上涨阶段 / -1 下跌阶段 / 0 未定 |
| rg | query | string |  | 周线周期态: 单边上涨 / 单边下跌 / 震荡 / 数据不足 |
| liq | query | integer |  | 1 = 只看流动性达标的标的 |
| q | query | string |  | 代码前缀或名称关键字 |
| sort | query | string |  | 排序字段: amt(默认) / chg / chg5 / chg20 / chg60 / chg250 / ytd / close / pos / mcap |
| order | query | string |  | desc(默认) / asc |
| offset | query | integer |  | 分页偏移, 默认 0 |
| limit | query | integer |  | 每页条数, 默认 100, 最大 500 |

示例: `GET /api/v1/list?mkt=US&bt=1&sort=chg20&limit=50`

```json
{"total":310,"rows":[{摘要}, ...]}
```

### 单个标的摘要

`GET /api/v1/symbol/{sym}`

单个标的的最新周期状态、关键位、区间涨跌与最近一次状态变化。白话结论请用 /analysis/{sym}。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sym | path | string | 是 | 标的代码(带市场后缀) |

示例: `GET /api/v1/symbol/NVDA.US`

```json
{"sym":"NVDA.US","code":"NVDA","name":"英伟达","mkt":"US","kind":"stock","date":"2026-10-14","close":181.2,"chg":1.3,"bt":1,"bp":0,"st":1,"rg":"单边上涨","rs":"...","lv":{"mid":172.4,"up":195.1,"dn":149.7,"e120":141.0,"e250":118.3,"ll":null,"tl":null,"m120":null,"m250":null},"pos":0.69,"last":{"d":"2026-10-09","t":"周底分型","L":"wfrac","ago":3},"spark":[...]}
```

### 批量摘要

`GET /api/v1/batch`

一次取多个标的的摘要(适合自选列表)。不存在的代码会被忽略。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| syms | query | string | 是 | 逗号分隔的标的代码, 最多 200 个(超出返回 400) |

示例: `GET /api/v1/batch?syms=NVDA.US,AAPL.US,BTC.CRYPTO`

```json
{"rows":[{摘要}, ...]}
```

### 搜索

`GET /api/v1/search`

按代码或名称搜索标的; 代码完全匹配优先, 其次代码前缀, 再次名称包含, 同级按成交额。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| q | query | string | 是 | 关键字 |
| limit | query | integer |  | 默认 12, 最大 50 |

示例: `GET /api/v1/search?q=腾讯`

```json
{"rows":[{"sym":"00700.HK","code":"00700","name":"腾讯控股","mkt":"HK","kind":"stock","close":512.0,"chg":0.8,"bt":1,"bp":0}]}
```

### 状态变化(异动)

`GET /api/v1/changes`

最近 N 个交易日内的周期状态变化事件(大趋势触发/确认、阶段建立、周线分型、形态突破等), 附标的最新价格与状态。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| mkt | query | string |  | 市场: US 美股 / HK 港股 / CN A股 / JP 日股 / KR 韩股 / CRYPTO 加密 / CMDTY 商品, all 为全部 |
| sym | query | string |  | 只看某些标的, 逗号分隔 |
| layers | query | string |  | 图层过滤, 逗号分隔: trend / stage / alert / bigpiv / dbl2 / wfrac / topbox / flag / range / overheat / e250 等 |
| days | query | integer |  | 最近几个交易日, 默认 5 |
| since | query | string |  | YYYY-MM-DD: 只取该日(含)之后的变化, 优先于 days; 增量同步时传上次响应的 cursor(最新事件日期) |
| liq | query | integer |  | 1 = 只看流动性达标的标的 |
| dir | query | string |  | up = 只看偏多, down = 只看偏空 |
| limit | query | integer |  | 默认 500, 最大 3000 |
| offset | query | integer |  | 分页偏移, 默认 0 |
| stats | query | integer |  | 1 = 附带 total(符合条件总数)、dates(每日条数)、up / down(偏多 / 偏空条数, 不受 dir 影响) |

示例: `GET /api/v1/changes?mkt=US&layers=trend,stage&days=3`

```json
{"cursor":"2026-10-14","offset":0,"rows":[{"sym":"AAPL.US","d":"2026-10-14","t":"上涨确认","L":"trend","v":228.1,"w":"...","name":"苹果","mkt":"US","close":230.5,"chg":0.9,"bt":1,"bp":0,"st":1}]}
```

### 宏观总览(数据)

`GET /api/v1/macro`

美债收益率、VIX、美元指数与主要汇率、商品、加密、主要指数的最新周期状态, 以及 10Y-2Y 期限利差序列(近 3 年)。白话结论用 /analysis/macro。

示例: `GET /api/v1/macro`

```json
{"factors":[{"group":"利率","sym":"US10Y.MACRO","name":"美债10年收益率","close":5.19,"chg":-0.38,"bt":-1,"bp":0,"st":-1,"rg":"单边上涨",...}],"spread":{"name":"10Y-2Y 期限利差","last":0.37,"inverted":false,"d":[...],"v":[...]}}
```

### 宏观与财报日历

`GET /api/v1/calendar`

美国、中国、欧元区、日本的重要宏观数据与议息(过去约 75 天到未来 35 天, 含公布值/预期/前值, 时间为 UTC), 以及未来两周标的池内美股的财报日。

示例: `GET /api/v1/calendar`

```json
{"asof":"2026-10-15","econ":[{"id":"...","t":"2026-10-28T18:00:00.000Z","country":"US","title":"Fed Interest Rate Decision","actual":null,"forecast":null,"previous":4}],"earnings":[{"d":"2026-10-21","sym":"TSLA.US","name":"特斯拉","time":"amc"}]}
```

### 个股事件: 财报 / 期权墙

`GET /api/v1/ext/{sym}`

下次与过往财报日(time: bmo 盘前 / amc 盘后), 以及期权墙(45 天内到期合约: 看涨墙、看跌墙、最大痛点、看跌/看涨未平仓量比、IV30、主要行权价未平仓量、GEX 与场景)。期权覆盖美股成交额前 200; 没有数据时只返回 {sym}。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sym | path | string | 是 | 标的代码 |

示例: `GET /api/v1/ext/AAPL.US`

```json
{"sym":"AAPL.US","asof":"2026-10-15","earnings":{"next":{"d":"2026-11-02","time":"amc","eps_f":"$1.99"},"past":[...]},"options":{"spot":345.06,"iv30":26.22,"call_wall":{"k":360,"oi":103627},"put_wall":{"k":300,"oi":63431},"max_pain":{"k":330,"exp":"2026-10-16"},"pc":0.79,"gex":0.29,"regime":"pos","flip":330.5,"scn":[...],"strikes":[...]}}
```

### 期权结构榜

`GET /api/v1/options/board`

全部有期权数据美股的墙位、GEX、伽马翻转位与场景(scn)汇总。

示例: `GET /api/v1/options/board`

```json
{"v":3,"asof":"2026-10-15","rows":[{"sym":"AAPL.US","name":"苹果","spot":345.06,"call_wall":360,"put_wall":300,"max_pain":330,"gex":0.29,"regime":"pos","flip":330.5,"pc":0.79,"iv30":26.2,"skew":null,"scn":[...]}]}
```

### 宏观仪表盘

`GET /api/v1/macro/dashboard`

50+ 条宏观序列(利率与政策、通胀、就业与增长、流动性、信用、家庭与地产、估值、衰退信号等): 最新值、较上期、近 1 月 / 1 年变化、同比、近 10 年分位、异动评分(tier: critical 显著 / notable 一般), 以及宏观因子与异动榜。每日更新。

示例: `GET /api/v1/macro/dashboard`

```json
{"asof":1792096000,"groups":["利率与政策",...],"series":[{"key":"DGS10","name":"美债10年收益率","group":"利率与政策","unit":"%","freq":"D","date":"2026-10-13","value":5.21,"chg":-0.03,"chg_1m":0.25,"chg_1y":1.16,"yoy":null,"pct10y":1.0,"anomaly":{"tier":"notable","sig":0.52,"dir":1,"reasons":["..."]},"spark":[...]}],"factors":[{"id":"macro.net_liquidity","name":"...","value":...}],"anomalies":[...]}
```

### 宏观序列历史

`GET /api/v1/macro/series/{key}`

单条宏观序列的完整历史(key 取自仪表盘 series[].key)。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| key | path | string | 是 | 序列 key |

示例: `GET /api/v1/macro/series/WALCL`

```json
{"key":"WALCL","name":"美联储总资产","unit":"万亿美元","d":["2002-12-16",...],"v":[0.7195,...]}
```

### 个股新闻

`GET /api/v1/news/{sym}`

美股 / 港股 / A 股个股新闻(中文, TradingView 聚合), 最近 40 条, 约 15 分钟更新。t 为发布时间(UTC 秒), d 为交易所当地日期, related 为关联标的(TradingView 代码)。数据源暂不可用时返回缓存并带 stale: true。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sym | path | string | 是 | 标的代码 |

示例: `GET /api/v1/news/00700.HK`

```json
{"sym":"00700.HK","tv":"HKEX:700","asof":1792096473,"items":[{"id":"...","t":1792058293,"d":"2026-10-15","title":"...","src":"Gelonghui","url":"...","urgency":2,"related":["HKEX:700"]}]}
```

### SEC 内部人交易与发债备案(美股)

`GET /api/v1/sec/{sym}`

最近 10 份 Form 4 中的股票交易(code: P 公开市场买入 / S 卖出 / A 授予 / M 行权 / F 缴税扣股 / G 赠与; side: A 增持向 / D 减持向), 以及最近 12 条债务与证券发行备案(8-K 2.03 新增直接债务、424B 招募书、FWP)。约 12 小时更新; 非美股返回 available: false。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sym | path | string | 是 | 美股代码 |

示例: `GET /api/v1/sec/AAPL.US`

```json
{"sym":"AAPL.US","available":true,"cik":"0000320193","name":"Apple Inc.","insider":[{"d":"2026-10-08","owner":"...","code":"S","side":"D","shares":2399,"price":332.01,"value":796491.99,"url":"..."}],"debt":[...],"asof":1792096476}
```

### 美股最新内部人交易(全市场)

`GET /api/v1/sec/latest`

SEC 最新 Form 4 备案中的股票交易, 附发行人与代码, 约每小时更新。

示例: `GET /api/v1/sec/latest`

```json
{"rows":[{"d":"2026-10-15","issuer":"Lifeway Foods, Inc.","ticker":"LWAY","owner":"...","code":"S","side":"D","shares":30000,"price":22.64,"value":679200,"url":"..."}],"asof":1792096483}
```

### 做空成交量(美股)

`GET /api/v1/short/{sym}`

FINRA RegSHO 最近 20 个交易日的做空量、FINRA 报告成交量与占比(pct = short / total)。报告成交量来自场外报告设施, 不是全市场成交量; 占比是做空压力的代理指标。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sym | path | string | 是 | 美股代码 |

示例: `GET /api/v1/short/TSLA.US`

```json
{"sym":"TSLA.US","available":true,"asof":"2026-10-14","series":[{"d":"2026-10-14","short":9631784,"total":16757127,"pct":0.575}]}
```

### 做空占比榜(美股个股)

`GET /api/v1/short`

最新一个交易日 FINRA 报告成交 ≥ 50 万股的个股按做空占比排序(前 100, 不含 ETF 与权证), avg 为前 19 日平均占比。

示例: `GET /api/v1/short`

```json
{"asof":"2026-10-14","days":20,"rows":[{"sym":"...","code":"...","name":"...","pct":0.71,"short":13280435,"total":18614973,"avg":0.63}]}
```

### 图谱: 实体搜索

`GET /api/v1/ontology/search`

按名称 / 代码 / 别名召回知识图谱实体(公司、行业、板块、主题、宏观因子等); 精确命中在前。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| q | query | string | 是 | 名称 / 代码 / 别名 |
| limit | query | integer |  | 默认 20, 最大 50 |

示例: `GET /api/v1/ontology/search?q=半导体`

```json
{"q":"半导体","exact":1,"rows":[{"id":"ent_...","t":"industry","name":"半导体","w":0.9,"exact":true}]}
```

### 图谱: 实体详情

`GET /api/v1/ontology/entities/{id}`

实体信息 + 按关系类型分组的直接关系(每组按权重取前 30, 附总数)。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| id | path | string | 是 | 实体 id(ent_ 开头) |

示例: `GET /api/v1/ontology/entities/ent_...`

```json
{"asof":"2026-10-15","entity":{"id":"ent_...","t":"company","name":"英伟达","sym":"NVDA.US","al":[...],"w":1.0,"desc":"..."},"relations":[{"t":"belongs_to","dir":"out","n":3,"rows":[{...}]}]}
```

### 图谱: 子图

`GET /api/v1/ontology/entities/{id}/graph`

以实体为中心的子图(广度优先, 枢纽节点只展开权重最高的一部分)。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| id | path | string | 是 | 实体 id |
| depth | query | integer |  | 1 或 2, 默认 1 |
| limit | query | integer |  | 节点上限, 默认 60 |

示例: `GET /api/v1/ontology/entities/ent_.../graph?depth=2`

```json
{"root":"ent_...","nodes":[{"id":"ent_...","t":"company","name":"...","depth":0}],"edges":[{"s":"ent_a","d":"ent_b","t":"belongs_to","w":0.9,"dir":1}]}
```

### 图谱: 标的关联

`GET /api/v1/ontology/symbol/{sym}`

标的对应实体 + 分组直接关系 + 同行业公司(peers)。回答"属于什么板块、和谁联动"。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sym | path | string | 是 | 标的代码 |

示例: `GET /api/v1/ontology/symbol/NVDA.US`

```json
{"asof":"2026-10-15","entity":{...},"relations":[...],"peers":[{...}]}
```

### 图谱: 牵动分析

`GET /api/v1/ontology/impact`

从给定实体沿有符号关系传播 3 跳, 返回受牵动实体(得分正负 = 同向/反向)与最强路径。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| ents | query | string | 是 | 逗号分隔的实体 id, 最多 8 个 |
| hops | query | integer |  | 跳数 1-3, 默认 3 |

示例: `GET /api/v1/ontology/impact?ents=ent_...`

```json
{"seeds":[{...}],"rows":[{"id":"ent_...","name":"...","score":0.42,"path":["...","..."]}]}
```

### 图谱: 统计

`GET /api/v1/ontology/stats`

实体与关系数量、类型分布。

示例: `GET /api/v1/ontology/stats`

```json
{"asof":"2026-10-15","entities":1200,"edges":3400,"types":{...},"edge_types":{...}}
```

### 感知: 事件流

`GET /api/v1/perception/feed`

近 72 小时挂到图谱实体的公开新闻事件流(按时间倒序), 可按类型 / 实体 / 标的 / 关键词过滤。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| kind | query | string |  | 事件类型 |
| ent | query | string |  | 实体 id |
| sym | query | string |  | 标的代码 |
| q | query | string |  | 标题关键词 |
| before | query | integer |  | 翻页: 只取早于该时间戳(UTC 秒)的 |
| limit | query | integer |  | 默认 50, 最大 200 |

示例: `GET /api/v1/perception/feed?sym=NVDA.US`

```json
{"asof":1792096000,"hours":72,"kinds":[...],"rows":[{"id":"...","t":1792058293,"title":"...","src":"...","url":"...","kind":"...","ents":[...]}],"next":null}
```

### 感知: 热度榜与主线

`GET /api/v1/perception/heat`

实体新闻热度榜(半衰期加权)与市场主线 mainline。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| t | query | string |  | 实体类型, 逗号分隔(company/industry/board/theme/actor/...), 不传为全部 |
| limit | query | integer |  | 默认 30, 最大 200 |

示例: `GET /api/v1/perception/heat`

```json
{"asof":1792096000,"half_life_h":24,"mainline":[{"id":"ent_...","name":"...","days":5,"heat":12.3}],"rows":[{"id":"ent_...","t":"company","name":"...","heat":8.2,"n24":3,"n7":9,"burst":2.1}]}
```

### 图表数据(原始)

`GET /api/v1/chart/{sym}`

原始数据, 用于画图: 日线 OHLCV + 周线指标实时值 + 逐日周期状态序列 + 周线K + 全部技术标记(点/线/箱体)。t 为自 1970-01-01 起的天数。要可读日期用 /bars/{sym}; 要结论用 /analysis/{sym}, 不要自己重算。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sym | path | string | 是 | 标的代码 |

示例: `GET /api/v1/chart/TSLA.US`

```json
{"sym":"TSLA.US","v":"1.1.0","d":{"t":[...],"o":[...],"h":[...],"l":[...],"c":[...],"vol":[...],"bt":[...],"bp":[...],"st":[...]},"w":{...},"marks":{"points":[...],"lines":[...],"boxes":[...]}}
```

## 摘要字段

| 字段 | 说明 |
|---|---|
| sym / code / name | 标的代码(带市场后缀) / 交易代码 / 名称 |
| mkt / kind | 市场 / 品种 |
| date / close / chg | 最新交易日 / 收盘价 / 当日涨跌幅(%) |
| chg5 / chg20 / chg60 / chg250 / ytd | 5/20/60/250 日与年初至今涨跌幅(%) |
| amt / mcap / liq | 成交额 / 市值 / 流动性是否达标 |
| bt | 大趋势: 1 上涨 / -1 下跌 / 0 未定(两步确认: 触发 → 待确认 → 确认/作废) |
| bp | 待确认: 1 上涨待确认 / -1 下跌待确认 / 0 无 |
| st | 阶段: 1 上涨阶段(周线底部建立) / -1 下跌阶段(周线顶部建立) / 0 未定 |
| rg / rs | 周线周期态(单边上涨 / 单边下跌 / 震荡 / 数据不足) 与说明 |
| since | 当前大趋势 / 待确认 / 阶段 / 周期态各自连续开始的日期(bp 为 0 时 since.bp 为 null) |
| lv | 关键位(周线实时值): mid 中线, up/dn 布林上下轨, e120/e250 周EMA, ll 3年低位, tl 下降趋势线, m120/m250 月EMA |
| pos | 在周线布林带中的位置: 0 = 下轨, 0.5 = 中线, 1 = 上轨 |
| last | 最近一次状态变化 {d 日期, t 名称, L 图层, ago 距今交易日} |
| spark | 近 60 日收盘(迷你走势) |
| mi | 宏观敏感度: 近两年周度涨跌与美债10年收益率、美元指数、原油、黄金(A股/港股另含美元兑人民币)的相关系数 r 与 beta, 按 |r| 排序, sig 为是否显著 |