Etf list paginated

ETF 分页列表 - 分页、排序、筛选

1. 接口描述

项目	说明
接口名称	ETF 分页列表
外部接口	GET /api/v1/market/data/daec/etfs
请求方式	GET
适用场景	分页获取 A 股 ETF 列表，支持按字段排序、按条件筛选、按需返回字段（masks）；不传分页参数时返回全部（先筛选、排序后再截断）

2. 请求参数

说明：所有参数均为可选项。不传 order_by 且不传 ob 时默认按 change_rate desc 排序；不传分页时返回满足条件的全部 ETF。

参数名	类型	是否必填	描述	取值示例	备注
order_by	string	否	排序方式，格式为「字段 方向」，多字段用逗号分隔	change_rate desc、name asc	方向：asc/a 升序，desc/d 降序；字段为 Etf 字段名
ob	string	否	与 order_by 同义	同 order_by	与 order_by 二选一，同时传以 order_by 为准
filter	string	否	过滤条件表达式	change_rate != null、name ~ "沪深"	见下方 filter 取值说明
masks	string	否	字段掩码，逗号分隔，仅返回这些字段	name,symkey,latest,change_rate	不传则返回全部字段
page_size	int	否	每页条数	20	不传则不分页
page_no	int	否	页码，从 1 开始	1	不传且传了 page_size 时默认为 1
filter_index	boolean	否	是否需要指数过滤	true、false	默认 false

filter 取值说明：表达式语法为 字段 操作符 值。比较操作符：=、!=、>、>=、<、<=；~ 子串包含；: 包含。逻辑组合：AND、OR、NOT，可用 () 分组。值可为 null、true、false、数字、双引号字符串。复杂表达式可 Base64 编码后以 _B64: 开头传入。示例：change_rate != null、change_rate >= 0 AND change_rate <= 0.1、name ~ "科技"。

3. 响应说明

返回分页后的 ETF 列表及总数。列表中每项为单只 ETF 对象（结构同单只 ETF 详情）；不传 masks 时每只返回全部字段。

{
    "total_size": 800,
    "etfs": [
        { "name": "上证50ETF", "symkey": "510050.XSHG", "latest": 2.85, "change_rate": 0.0018 },
        { "name": "创业板ETF", "symkey": "159915.XSHE", "latest": 1.92, "change_rate": -0.0052 }
    ]
}

字段名	类型	说明
total_size	int	满足筛选条件的 ETF 总数（分页前）
etfs	array	当前页的 ETF 列表；单条字段同「单只 ETF 详情」（name、symkey、latest、change_rate、volume、turnover 等）

4. 用法

通过主目录 run.py 调用（参数均可选）：

python <RUN_PY> etf-list-paginated
python <RUN_PY> etf-list-paginated --order_by "change_rate desc" --page_size 20 --page_no 1
python <RUN_PY> etf-list-paginated --order_by "name asc" --masks name,symkey,latest,change_rate --page_size 50
python <RUN_PY> etf-list-paginated --filter "change_rate >= 0.01 AND change_rate <= 0.05"

<RUN_PY> 为主 SKILL.md 同级的 run.py 绝对路径。脚本输出 JSON，请求头已内置 X-Client-Name: ft-claw。

5. 请求示例

GET /api/v1/market/data/daec/etfs?order_by=change_rate%20desc&page_size=20&page=1

6. 注意事项

• 涨跌幅等比率字段可能为小数形式，展示时按需乘以 100 转为百分比
• 不传 page_size/page_no 时返回全部满足条件的 ETF，数据量大时注意响应体积