---
title: 特征定义查询
description: 按指标、事件或状态类型、特征 ID 查询特征定义，供 AI Agent、绘图组件和下游应用使用。
---

# 特征定义查询

`GET /api/indicators/signals` 返回按指标分组的特征定义：有哪些特征、判断规则、含义和有效条件。
它不返回某个标的当前是否发生了特征，也不返回买卖建议。

Base URL：`https://api.mobiusquant.ai`。沿用普通 API 的[可选 Bearer Token 与限流规则](/zh/token)，不需要管理员账号。

## 请求

```bash
# 全部指标，包括没有独立特征的指标及原因
curl 'https://api.mobiusquant.ai/api/indicators/signals'

# MACD 的全部特征
curl 'https://api.mobiusquant.ai/api/indicators/signals?indicator=macd'

# MACD 的事件特征，不包含持续状态
curl 'https://api.mobiusquant.ai/api/indicators/signals?indicator=macd&kind=event'

# 单个特征的定义
curl 'https://api.mobiusquant.ai/api/indicators/signals?id=macd.cross_up'
```

| 参数 | 类型 | 必填 | 含义 |
| --- | --- | --- | --- |
| `indicator` | string | 否 | 精确指标名，与 `calc[].name` 相同，例如 `macd`；不带则查询全部指标 |
| `kind` | `event` / `state` | 否 | 只返回事件或状态；不带则包含两类 |
| `id` | string | 否 | 完整特征 ID，例如 `macd.cross_up` |

名称与 ID 区分大小写，不接受模糊匹配。多个条件按 **AND** 组合；同时传入 `indicator` 和 `id` 时，ID 必须属于该指标。

- 不传 `kind`、`id`：保留没有独立特征的指标，返回原因及 `signals: []`。
- 传入 `kind` 或 `id`：仅保留具有匹配特征的指标组。
- 合法条件无匹配：返回 `200`，内容为 `{"count":0,"signal_count":0,"indicators":{}}`。例如 `indicator=cvd&kind=state`。
- 空字符串不是省略参数；空值返回 `422`。

## 响应

查询 `?id=macd.cross_up`：

```json
{
  "count": 1,
  "signal_count": 1,
  "indicators": {
    "macd": {
      "has_signals": true,
      "signal_status": "supported",
      "signal_reason": "",
      "signals": [
        {
          "id": "macd.cross_up",
          "label": "MACD 金叉",
          "kind": "event",
          "description": "前根 MACD <= Signal，本根 MACD > Signal。",
          "meaning": "MACD 相对信号线或零轴的动量关系；事件只在交叉根出现，状态可持续，不是买卖指令。",
          "required_history": "max(fast, slow) + signal 根连续有效输入",
          "version": 1,
          "details": [],
          "supports_forming": true
        }
      ]
    }
  }
}
```

### 分组字段

| 字段 | 含义 |
| --- | --- |
| `count` | 筛选后返回的指标组数量 |
| `signal_count` | 筛选后返回的特征总数 |
| `indicators` | 以指标名为 key 的对象；按 key 读取，不依赖顺序 |
| `has_signals` | 该指标是否提供特征输出，不代表当前行情数据已满足计算条件 |
| `signal_status` | `supported`：提供特征；`none`：没有独立特征；`unreviewed`：尚无特征能力结论 |
| `signal_reason` | 不提供特征的原因；支持特征时为空字符串 |
| `signals` | 匹配的定义列表，不是计算结果；无特征时为空数组 |

不应将 `none` 与 `unreviewed` 混为一谈，也不应把按类型筛选得到的空结果理解为“该指标没有任何特征”。

### 特征字段

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `id` | string | 稳定特征标识，与计算结果列名、图表标记的 `signal_ids` 一致 |
| `label` | string | 展示名称 |
| `kind` | string | `event`：只在发生柱成立；`state`：逐根判断，可连续成立 |
| `description` | string | 判定规则，参数取实际计算请求值 |
| `meaning` | string | 特征所代表的含义 |
| `required_history` | string | 历史长度与有效性要求；可能含参数公式，不是固定整数 |
| `version` | integer | 该特征定义的版本 |
| `details` | string[] | 额外边界条件或确认要求；没有时为空数组 |
| `supports_forming` | boolean | 是否支持 `include_forming: true` 末根试算；不代表当前输入足够判断 |

名称及规则说明当前使用中文，ID 与枚举值不随语言变化。计算参数、默认值及指标周期限制通过
[`GET /api/indicators/registry`](https://api.mobiusquant.ai/api/indicators/registry) 查询。
`GET /api/indicators/registry?include_signals=true` 仍可获取简版特征定义。

## 与计算、绘图结合

1. 查询本接口，按 `indicator` 和 `id` 选择需要的特征。
2. 向 `/api/indicators` 或 `/api/indicators/compute` 发送计算请求，顶层设置 `"signals": true`。
3. 用定义的 `id` 查找 `indicators[响应key].signals.columns`，再读取 `data` 中对应列。

绘图时，向 `/api/chart` 设置 `"signals": true`。特征表位于 `indicator_signals[响应key]`；
事件标记中的 `signal_ids` 可关联本接口的名称、规则和含义。状态不逐根生成事件标记。
同一指标使用多组参数时，用响应 key／`indicator_key` 区分实例；特征 ID 不会因参数改变。
查询参数 `id` 是特征 ID，不是计算请求中自定义的 `calc[].id`。

特征定义与实际数据可判断性不同。默认模式下：

| 计算结果 | 含义 |
| --- | --- |
| `true` | 已收盘 K 线上的事件发生，或状态成立 |
| `false` | 数据可判断，但事件未发生或状态不成立 |
| `null` | 未收盘、历史不足、依赖值无效或输入存在缺口，不能可靠判断 |

实时特征支持 Binance、Bybit、OKX、Hyperliquid 已接入行情，包含[币安股票永续](/zh/markets#binance-stock-perp)，不包含股票现货。BYO 必须提供 `interval` 和连续、固定时长的 K 线，并满足所选指标的限制。
末根未收盘时设置 `last_bar_closed: false`。输入出现周期缺口或无效 OHLCV 后，本次输入后续特征为 `null`。
`open_time`、`confirmed_at_ms` 为毫秒，图表标记 `time` 为秒；确认时间存在不代表该根一定触发了事件。
没有特征能力的指标在计算中返回整个 `signals: null`，不同于目录中的 `signals: []`。

完整调用示例见[特征计算](/zh/compute#native-features)和[信号绘图](/zh/compute#feature-chart)。

## 盘中特征试算 {#forming}

在 `/api/indicators`、`/api/indicators/compute` 或 `/api/chart` 请求顶层，同时设置
`signals: true` 和 `include_forming: true`。`include_forming` 默认为 `false`，只接受 JSON 布尔值；
未开启 `signals` 时使用该选项返回 `422`。

```bash
curl -X POST 'https://api.mobiusquant.ai/api/indicators?explain=false' \
  -H 'Content-Type: application/json' \
  -d '{"exchange":"binance","market":"perp","symbol":"BTCUSDT","interval":"5m","limit":2,"signals":true,"include_forming":true,"calc":[{"name":"macd","id":"m"}]}'
```

引擎将最后一根尚未收盘 K 线的**当前实际 OHLCV 当作完整样本**，按原算法计算。
不预测最终收盘值，不补足不存在的后续 K 线；历史长度、输入连续性、原生阈值和模型确认条件不变。
金叉等前后关系仍比较相邻 K 线，不比较前后两次请求。同一根重复请求不会累计确认次数或去重。

仍然只返回一套结果：计算接口读 `indicators[key].signals`，绘图接口读 `indicator_signals[key]`。
信号表在已有列末尾追加 `bar_status`，请按列名读取：

| bar_status | 含义 | confirmed_at_ms |
| --- | --- | --- |
| `closed` | 收盘计算结果 | 原有按周期计算的收盘时间 |
| `forming` | 未收盘末根的当前快照试算 | 始终为 `null` |

`true` 表示当前条件成立，可用于盘中预警；`false` 表示当前条件不成立；`null` 仍表示依赖不足等不可判断。
**盘中特征可以在下一次更新或收盘时消失，不能当作已确认事件。** 数值、特征、原因及原生对象来自同次计算。
例如 CVD 背离 ID 含 `confirmed` 不代表实际收盘，应读取 `bar_status` 和对象 `status`。
CVD 在试算模式使用 `objects.schema_version=2`，盘中背离对象为 `status=forming`、`confirmed_at_ms=null`。

BYO 请求仍需如实传 `last_bar_closed: false`，并提供 `interval`；可以使用历史时点的盘中快照。
之前各根必须已收盘，不得把多根未收盘数据交给此选项。输入已全部收盘时，各行均为 `closed`。
实时最新查询缺少当前形成中的 K 线时返回 `503` 和 `Retry-After`；显式历史窗口不会被上一根冒充盘中结果。
该模式不提供历史盘中快照回放，也不额外保证数据源终态完整性；`calculation.as_of_ms` 不是上游数据观察时间。

`/api/chart` 使用同一计算方式，事件标记增加相同的 `bar_status`，盘中标记确认时间为空；
不增加颜色规则或专用图元。`include` 的原因和属性关联选项仍然可用；
`calculation` 在本模式额外包含 `include_forming=true`、`signal_evaluation_version=1`。
结构化定义的 `limits.live_features.supports_forming` 与特征目录声明支持情况；不支持时末根特征为 `null`，
开启原因信息后可读 `forming_not_supported`。没有原生特征的指标仍返回 `signals: null`。

省略或设置 `include_forming: false` 时，旧数值、对象、特征及图表行为不变，也不增加 `bar_status` 列。
预警记录、盘中与收盘结果关联、通知、去重和冷却由消费端负责。

## 单次计算的可选信息 {#single-calculation}

计算和绘图请求可以通过顶层 `include` 选择附加信息。省略或传 `[]` 时不附加这些字段，
现有数值、特征和图表协议保持不变。

```json
{
  "exchange": "binance",
  "market": "perp",
  "symbol": "BTCUSDT",
  "interval": "5m",
  "limit": 100,
  "calc": [
    {"name": "macd", "id": "macd"},
    {"name": "cvd", "id": "cvd"},
    {"name": "hmm_regime", "id": "hmm"}
  ],
  "signals": true,
  "include": ["signal_reasons", "signal_details", "calculation", "definition"]
}
```

向 `/api/indicators?explain=false` 或 `/api/chart` 发送上述请求；BYO 使用同样的选项。
`include` 为可选值数组，不接受重复项或未知值。`signal_reasons` 和 `signal_details` 必须同时开启
`signals: true`，否则返回 `422`；`calculation` 和 `definition` 可独立使用。

| 选项 | 计算响应中的位置 | 图表响应中的位置 |
| --- | --- | --- |
| `signal_reasons` | `indicators[key].signals.invalid_reasons` | `indicator_signals[key].invalid_reasons` |
| `signal_details` | `indicators[key].signals.details` | `indicator_signals[key].details` |
| `calculation` | `indicators[key].calculation` | `indicator_calculations[key]` |
| `definition` | `indicators[key].definition` | `indicator_definitions[key]` |

无独立特征的指标仍返回整个 `signals: null`，不为其制造原因或事件。

### 不可判断原因

`invalid_reasons` 采用 `{columns, data}`，第一列为毫秒 `open_time`，其余列为特征 ID。
它只保留至少有一个特征为 `null` 的行：不可判断的单元格为原因码数组，可判断的单元格为 `null`。
这里单元格的 `null` 表示“没有不可判断原因”，不取代原 `signals.data` 中的三态值。
没有不可判断行时，`data` 为空数组。

| 原因码 | 含义 |
| --- | --- |
| `bar_not_closed` | 所需 K 线尚未收盘 |
| `insufficient_history` | 未满足该特征的历史长度，或缺少所需前值 |
| `input_gap` | 本次计算输入存在周期缺口，影响当前判断 |
| `invalid_input` | 本次输入存在无效 OHLCV，影响当前判断 |
| `invalid_dependency` | 依赖数值、成交量条件或原生对象不可用 |
| `state_unavailable` | 尚无该特征要求的有效方向或状态 |
| `not_applicable` | 当前不满足该特征的适用前提，例如 HMM 已切换方向，不判断原方向的支持恢复 |

原因按特征、按 K 线提供，可同时出现多个；事件还可能受前一根的有效性影响。
例如同一根 RSI 的超买状态可以判断，而进入超买区事件仍缺少有效前值。
此选项解释已有 `null`，不改变其判断结果。BYO 请求中的 NaN/inf 仍在输入校验时被拒绝，
不会因为开启原因说明而放宽输入要求。

### 原生数值与对象关联

`details.bindings` 以特征 ID 为 key，说明如何读取该次计算已有的属性。

- `values[]`：每项含 `field` 和 `offset`。`offset=0` 为信号所在柱，`-1` 为前一根输入柱。
- `objects`：含 `collection`、`match`、`id_field`、`fields` 和响应内的 `container`；
  图表还提供实际 `object_key`，不要假设它一定等于指标名。
- `context`：`{columns, data}`，仅补充同一响应中无法直接读取的必要数值行。时间仍为毫秒。

当前 MACD、RSI、CVD、HMM 提供显式关联。其他指标未声明额外属性关联时，
`bindings` 为空对象，`context.data` 为空数组；这不影响其特征输出能力。

CVD 按同一实例的 `confirmation_bar_time_ms = 信号 open_time` 和背离方向匹配
`objects.divergences`，读取已有 `id`、`strength`、`start/end`、`confirmed_at_ms`。
图表从 `indicator_objects[object_key].divergences` 读取。强度不会再复制一份到信号中；
对象 ID 是结果关联，不是通知去重保证。

HMM 的方向变化关联前后两根 `hmm_state` 或 `hmm_context_state`；支持变化还关联
`hmm_supported`。计算接口已返回的数值行不会重复放入 `context`，但窗口外必要前值会补入。
图表没有完整数值表，因此 `context` 提供触发事件或成立状态涉及的必要字段。
先按绑定读取同一响应中的数值或 `context`，不要另发一次请求取前值。

### 计算元信息

每个指标实例分别返回：

| 字段 | 含义 |
| --- | --- |
| `algorithm_version` | 当前指标算法版本，不是部署版本 |
| `effective_params` | 补齐默认值后的实际调用参数 |
| `resolved` | 自动选择的实际模式；HMM 的 `normalization=auto` 会解析为 `d1` 或 `legacy` |
| `signal_versions` | 特征 ID 到定义版本的映射；无特征时为空对象 |
| `input` | 实际计算输入的 `start_open_time_ms`、`end_open_time_ms`、`bars` |
| `output` | 本次返回窗口的同名范围字段，可能比输入短 |
| `interval_ms` | 计算上下文的周期时长；未提供时为 `null` |
| `as_of_ms` | 实时判断使用的截止时刻；BYO 通常为 `null` |
| `last_bar_closed` | 实际输入末根是否已收盘；BYO 使用调用方声明 |

范围端点均为 K 线开盘毫秒时间，空范围端点为 `null`、根数为 `0`。
实际输入范围不承诺连续或已经满足预热条件，也不代表行情永久不变。
相同参数、版本和范围不能替代对原始行情数据的保存；历史修订可能改变结果。
版本的保存、变化检测和迁移由消费端负责。

## 结构化指标定义 {#indicator-definition}

在现有注册表查询中开启结构化定义：

```http
GET /api/indicators/registry?include_schema=true
```

每个指标增加 `definition`，包含 `parameters`、`outputs`、`limits`、
`algorithm_version`、`effective_params`、`resolved`、`signal_versions` 和 `signal_value_bindings`。
它不读取行情，也不返回某个标的的特征值。

按实际参数解析动态字段时使用：

```http
POST /api/indicators/registry/resolve
Content-Type: application/json
```

```json
{
  "interval": "4h",
  "calc": [
    {"name": "ema", "params": {"period": 50}, "id": "ema50"},
    {"name": "hmm_regime", "id": "hmm"}
  ]
}
```

返回 `{count, indicators}`，以计算响应 key 分组：EMA 的输出字段解析为 `ema_50`，
HMM 的实际归一化解析为 `legacy`。不需要提供 K 线；`interval` 可选，不提供时不解析依赖周期的自动模式。
`calc` 最多 100 项，同名同参数多实例仍需用不同 `id` 消歧。

- `parameters`：参数名为 key，包含声明类型、默认值、是否必填、是否可为空及 `constraints`。
  `constraints` 提供已明确声明的上下界、枚举或条件要求；`validation=native` 表示仍沿用指标原有校验。
- `parameter_constraints_complete=false`：参数约束尚未完整声明，空约束不能理解为接受任意值。
  解析成功只表示已声明条件通过，不承诺任意输入行情都能计算成功，不改变原有参数校验规则。
- `outputs[]`：字段 `name/type/nullable/unit`，部分字段还含上下界、说明和 `enum` 的取值含义。
  动态列名随参数解析，不应把默认 `ema_20` 写死。
- `unit=price` 沿用输入行情价格单位，`input_volume` 沿用输入成交量单位；
  `unix_ms` 为毫秒时间，`category` 为枚举，`model_weight` 不是校准预测概率。
- `limits`：指标支持的周期、实时周期、资产类别、成交量要求、受限 venue 及实时特征市场。
  周期或资产列表为 `null` 表示未追加指标专属限制，仍须通过 `/api/markets`、`/api/intervals`
  检查具体 venue；不表示任意市场都提供数据。`unsupported_venues` 为明确不支持的组合。
- `signal_value_bindings`：数据无关的原生属性关联定义；实际图表对象 key 以本次 `signals.details` 为准。

`calculation` 和 `definition` 不包含监控规则、轮询进度、通知或买卖建议。

## 错误

| HTTP 状态 | 原因 | 处理 |
| --- | --- | --- |
| `400` | 未知指标、未知特征 ID，或指标与 ID 不对应 | 读取 `detail` 并修正查询 |
| `422` | 非法 `kind`、空参数，或名称/ID 超长 | `indicator` 最长 128 字符，`id` 最长 200 字符；使用合法枚举 |
| `401` | 提供了无效、过期或撤销的 Token | 修正 Token，不降级匿名重试 |
| `429` | 超过 API 频率限制 | 按 `Retry-After` 等待，不应每根 K 线都重查目录 |
| `405` | 使用 POST、PUT、PATCH 或 DELETE | 此接口仅供 GET 查询 |

字段类型和查询参数也可通过 [OpenAPI](https://api.mobiusquant.ai/openapi.json) 读取。