China iFinD Skill(同花顺Skill)

同花顺 iFinD (51ifind.com) 金融数据查询。支持 A 股/基金/债券/期货/指数的实时行情、历史行情、财务指标、宏观经济数据等 18 个 API 接口。 Chinese financial data query skill powered by THS iFinD (51ifind.com) API. Covers real-time quotes, historical data, financial indicators, macro economics, fund valuation, and more across 18 API endpoints for A-shares, funds, bonds, futures, and indices.

# iFinD 金融数据查询 Skill

## Overview

| # | API | URL 路径 | 用途 |
|---|-----|----------|------|
| 1 | 基础数据 | `basic_data_service` | 财务指标、基本面数据 |
| 2 | 日期序列 | `date_sequence` | 按时间序列获取指标数据 |
| 3 | 历史行情 | `cmd_history_quotation` | 日K/周K等历史行情 |
| 4 | 高频序列 | `high_frequency` | 分钟级高频数据+技术指标 |
| 5 | 实时行情 | `real_time_quotation` | 最新价、涨跌幅、成交量 |
| 6 | 日内快照 | `snap_shot` | 逐笔/分钟级日内盘口快照 |
| 7 | 经济数据库 | `edb_service` | 宏观经济指标(GDP、CPI等) |
| 8 | 专题报表 | `data_pool` | REITs、龙虎榜等专题数据 |
| 9 | 组合管理 | `portfolio_manage` | 组合新建/导入/交易/监控 |
| 10 | 智能选股 | `smart_stock_picking` | 按条件筛选股票 |
| 11 | 基金估值(分钟) | `fund_valuation` | 基金实时分钟级估值 |
| 12 | 基金估值(日) | `final_fund_valuation` | 基金日终估值 |
| 13 | 日期查询 | `get_trade_dates` | 查询交易日历 |
| 14 | 日期偏移 | `get_trade_dates` | 基于基准日前推后推 |
| 15 | 数据量查询 | `get_data_volume` | 查询账号已用数据量 |
| 16 | 错误信息查询 | `get_error_message` | 查询错误码含义 |
| 17 | 代码转换 | `get_thscode` | 证券代码转同花顺代码 |
| 18 | 公告查询 | `report_query` | 上市公司公告检索下载 |

## 首次使用检查（AI Agent 必读）

**每次调用 API 前，必须先检查 `IFIND_REFRESH_TOKEN` 是否已配置：**

```bash
grep -q 'IFIND_REFRESH_TOKEN=.' ~/.openclaw/skills/ifind-data/.env 2>/dev/null && echo "ok" || echo "missing"
```

如果返回 `missing`，**停止执行**，向用户提示：

> 使用 iFinD 金融数据查询需要你的 refresh_token。获取方式：
> - **还没有账号**：访问 https://ft.10jqka.com.cn 申请 iFinD 量化数据终端
> - **已有账号**：打开 iFinD 超级命令客户端 → 工具 → refresh_token 查询；或登录 https://quantapi.51ifind.com 在账号信息中查看
>
> 请把你的 refresh_token 发给我，我帮你配置好。

用户回复 token 后，**静默写入配置，不要展示命令**：
```bash
sed -i 's/^IFIND_REFRESH_TOKEN=.*/IFIND_REFRESH_TOKEN=用户提供的token/' ~/.openclaw/skills/ifind-data/.env
```
写入后告诉用户「已配置好，正在为你查询...」，然后继续执行 API 调用。

## SkillPay 计费规则（AI Agent 必读）

1. **永远不要让用户去 skillpay.me 注册** — 用户不需要注册
2. **余额不足时，直接把 payment_url 发给用户** — 告诉他们点击链接用 USDT 充值
3. **user_id 由脚本自动生成** — 不要问用户要
4. **查余额是免费的** — 只有实际执行 API 查询时才扣费（0.0001 USDT/次）
5. 用户充值后余额自动到账，可继续使用

## 试用期提示（AI Agent 必读）

脚本 stderr 中如果出现 `[TRIAL]` 开头的行，说明用户处于免费试用期。**每次**看到此标记时，在回复数据结果之后，必须附加如下提示：

> ---
> 🎁 您正在免费试用中，剩余 {trial_remaining_days} 天。试用期结束后按 0.0001 USDT/次计费（约 ¥0.0007/次），充值 1 USDT 可使用约 10000 次查询。

从 `[TRIAL]` 后的 JSON 中提取 `trial_remaining_days` 填入。**不要省略这个提示，每次试用期调用都要显示。**

## 调用方式

所有 API 通过 `scripts/ifind-api` 二进制调用：

```bash
./scripts/ifind-api "<api_endpoint>" '<json_body>'
```

- `api_endpoint`: 下方各 API 的路径名（如 `real_time_quotation`）
- `json_body`: JSON 格式的请求参数

二进制自动处理：user_id 生成 → 计费验证 → iFinD Token 获取 → API 请求 → 返回结果。

**日志排查**：出问题时查看 `.data/ifind.log`，每次请求记录 endpoint、状态、耗时等信息，日志超过 1MB 自动轮转。

---

## API 1: 基础数据

**Endpoint**: `basic_data_service`

**参数**:

| key | 必须 | 说明 | 示例 |
|-----|------|------|------|
| codes | 是 | 逗号分隔的证券代码 | `"300033.SZ,600030.SH"` |
| indipara | 是 | 指标及参数数组 | 见下方 |

**indipara 格式**:
```json
[{
  "indicator": "ths_roe_stock",
  "indiparams": ["20241231"]
}]
```

**示例**:
```json
{
  "codes": "300033.SZ,600030.SH",
  "indipara": [{
    "indicator": "ths_roe_stock",
    "indiparams": ["20241231"]
  }, {
    "indicator": "ths_roe_avg_by_ths_stock",
    "indiparams": ["20241231"]
  }]
}
```

> 指标名过多，推荐使用超级命令生成。常用：`ths_roe_stock`(ROE)、`ths_eps_stock`(EPS)、`ths_pe_stock`(PE)等。

---

## API 2: 日期序列

**Endpoint**: `date_sequence`

**参数**:

| key | 必须 | 说明 | 示例 |
|-----|------|------|------|
| codes | 是 | 逗号分隔的证券代码 | `"300033.SZ,600030.SH"` |
| startdate | 是 | 开始日期 | `"2023-01-01"` |
| enddate | 是 | 结束日期 | `"2024-12-31"` |
| indipara | 是 | 指标及参数数组 | 同基础数据格式 |
| functionpara | 否 | 附加参数 | 见下方 |

**functionpara 选项**:

| 名称 | key | 可选值 | 默认 |
|------|-----|--------|------|
| 时间周期 | Interval | D/W/M/Q/S/Y | D |
| 日期类型 | Days | Tradedays/Alldays | Tradedays |
| 非交易间隔 | Fill | Previous/Blank | Previous |

**示例**:
```json
{
  "codes": "300033.SZ,600030.SH",
  "startdate": "20230101",
  "enddate": "20241231",
  "functionpara": {"Days": "Alldays", "Fill": "Blank", "Interval": "Y"},
  "indipara": [{
    "indicator": "ths_total_equity_atoopc_stock",
    "indiparams": ["", "100"]
  }]
}
```

---

## API 3: 历史行情

**Endpoint**: `cmd_history_quotation`

**参数**:

| key | 必须 | 说明 | 示例 |
|-----|------|------|------|
| codes | 是 | 逗号分隔的证券代码 | `"300033.SZ,600030.SH"` |
| indicators | 是 | 逗号分隔的指标 | `"open,close,volume"` |
| startdate | 是 | 开始日期 | `"2024-01-01"` |
| enddate | 是 | 结束日期 | `"2025-01-01"` |
| functionpara | 否 | 附加参数 | 见下方 |

**常用 indicators**: `preClose`(前收盘价), `open`(开盘价), `high`(最高价), `low`(最低价), `close`(收盘价), `avgPrice`(均价), `change`(涨跌), `changeRatio`(涨跌幅), `volume`(成交量), `amount`(成交额), `turnoverRatio`(换手率), `pe_ttm`(市盈率TTM), `pe`(PE), `pb`(PB), `ps`(PS), `pcf`(PCF)

基金专用: `netAssetValue`(单位净值), `adjustedNAV`(复权单位净值), `accumulatedNAV`(累计单位净值)

**functionpara 选项**:

| 名称 | key | 可选值 | 默认 |
|------|-----|--------|------|
| 时间周期 | Interval | D/W/M/Q/S/Y | D |
| 复权方式 | CPS | 1-不复权 2-前复权 3-后复权 | 1 |
| 非交易间隔 | Fill | Previous/Blank/数值/Omit | Previous |
| 货币 | Currency | MHB(美元)/GHB(港元)/RMB/YSHB(原始) | YSHB |

**示例**:
```json
{
  "codes": "300033.SZ,600030.SH",
  "indicators": "open,close,volume",
  "startdate": "2024-08-25",
  "enddate": "2025-08-25",
  "functionpara": {"Interval": "W", "CPS": "3", "Currency": "RMB", "Fill": "Blank"}
}
```

---

## API 4: 高频序列

**Endpoint**: `high_frequency`

**参数**:

| key | 必须 | 说明 | 示例 |
|-----|------|------|------|
| codes | 是 | 逗号分隔的证券代码 | `"300033.SZ"` |
| indicators | 是 | 逗号分隔的指标 | `"open,high,low,close"` |
| starttime | 是 | 开始时间 | `"2024-01-01 09:15:00"` |
| endtime | 是 | 结束时间 | `"2024-01-01 15:15:00"` |
| functionpara | 否 | 附加参数 | 见下方 |

**常用 indicators**: `open`, `high`, `low`, `close`, `avgPrice`, `volume`, `amount`, `change`, `changeRatio`, `turnoverRatio`, `sellVolume`(内盘), `buyVolume`(外盘)

技术指标: `MA`, `MACD`, `KDJ`, `RSI`, `BOLL`, `CCI`, `OBV`, `ATR` 等（需在 functionpara.calculate 中配置参数）

资金流向: `large_amt_timeline`(主力净流入), `active_buy_large_volume`(主动买入特大单量) 等

**functionpara 选项**:

| 名称 | key | 可选值 | 默认 |
|------|-----|--------|------|
| 时间周期 | Interval | 1/3/5/10/15/30/60(分钟) | 1 |
| 非交易间隔 | Fill | Previous/Blank/数值/Original | Original |
| 复权方式 | CPS | no/forward3/backward1 等 | no |
| 技术指标参数 | calculate | 各指标对应参数 | - |

**技术指标 calculate 示例**:
```json
{
  "Interval": "1",
  "calculate": {
    "MACD": "12,26,9,MACD",
    "KDJ": "9,3,3,K"
  }
}
```

---

## API 5: 实时行情

**Endpoint**: `real_time_quotation`

**参数**:

| key | 必须 | 说明 | 示例 |
|-----|------|------|------|
| codes | 是 | 逗号分隔的证券代码 | `"300033.SZ,600000.SH"` |
| indicators | 是 | 逗号分隔的指标 | `"open,high,low,latest"` |

**常用 indicators**:

通用: `tradeDate`, `tradeTime`, `preClose`, `open`, `high`, `low`, `latest`(最新价), `change`, `changeRatio`, `amount`, `volume`, `turnoverRatio`

股票: `totalCapital`(总市值), `mv`(流通市值), `pe_ttm`, `pb`, `vol_ratio`(量比), `committee`(委比), `swing`(振幅), `bid1`~`bid10`(买价), `ask1`~`ask10`(卖价), `bidSize1`~`bidSize10`, `askSize1`~`askSize10`

资金流向: `mainNetInflow`(主力净流入), `largeNetInflow`(超大单净流入), `bigNetInflow`(大单净流入)

**示例**:
```json
{
  "codes": "300033.SZ,600000.SH",
  "indicators": "open,high,low,latest,changeRatio,volume,amount"
}
```

---

## API 6: 日内快照

**Endpoint**: `snap_shot`

**参数**:

| key | 必须 | 说明 | 示例 |
|-----|------|------|------|
| codes | 是 | 逗号分隔的证券代码 | `"300033.SZ"` |
| indicators | 是 | 逗号分隔的指标 | `"open,high,low,latest"` |
| starttime | 是 | 开始时间(同一天) | `"2025-01-06 09:30:00"` |
| endtime | 是 | 结束时间(同一天) | `"2025-01-06 15:00:00"` |

> 注意：起始和结束日期必须是同一天。

**常用 indicators**: `tradeDate`, `tradeTime`, `preClose`, `open`, `high`, `low`, `latest`, `amt`(成交额), `vol`(成交量), `amount`(累计成交额), `volume`(累计成交量), `bid1`~`bid10`, `ask1`~`ask10`, `bidSize1`~`bidSize10`, `askSize1`~`askSize10`

---

## API 7: 经济数据库 (EDB)

**Endpoint**: `edb_service`

**参数**:

| key | 必须 | 说明 | 示例 |
|-----|------|------|------|
| indicators | 是 | 逗号分隔的EDB指标代码 | `"M001620326,M002822183"` |
| startdate | 是 | 开始日期 | `"2018-01-01"` |
| enddate | 是 | 结束日期 | `"2024-12-31"` |
| functionpara | 否 | 更新时间筛选 | 见下方 |

> EDB 指标代码需通过超级命令查询，如 GDP、CPI、PMI 等宏观指标。

**示例**:
```json
{
  "indicators": "M001620326,M002822183",
  "startdate": "2018-01-01",
  "enddate": "2024-12-31"
}
```

---

## API 8: 专题报表

**Endpoint**: `data_pool`

**参数**:

| key | 必须 | 说明 | 示