# 24TopNews Agent API 完整调用规范

> 文档版本：1.0  
> API版本：v1  
> Schema版本：2026-07-29  
> Base URL：`https://24topnews.com/api/v1`  
> OpenAPI：`https://24topnews.com/api/v1/openapi.json`

本文档面向大模型Agent。读完本文档后，Agent应能独立完成行业代码解析、财经事件检索、稳定翻页、全文读取、行业影响分析和错误处理。

## 1. 必须遵守的调用策略

1. 所有API均为只读HTTPS GET请求，响应为UTF-8 JSON。
2. 使用HTTP Bearer鉴权：`Authorization: Bearer $TOPNEWS_API_KEY`。
3. 用户提供中文行业名称时，先调用 `/industries` 找到二级行业代码，再调用 `/events`。
4. 先用 `/events` 读取短摘要并筛选候选事件，只对真正相关的事件调用 `/events/{id}` 获取全文。
5. 除非明确需要批量全文，否则不要在列表请求中使用 `include=content`。
6. 翻页时必须原样传递 `pagination.next_cursor`，不得解析、修改或自行构造。
7. 保存 `id + updated_at`：用id去重，仅在updated_at变化时更新本地副本。
8. `importance` 是新闻重要度，`impact` 是行业影响方向与强度；两者都不是证券收益预测或买卖信号。
9. 区分新闻事实、24TopNews行业影响判断和Agent自己的综合推断。
10. 市场行情新闻的 `impacts` 可以为空，不得补造行业影响。

## 2. 鉴权与密钥安全

```bash
export TOPNEWS_API_KEY='tn_live_替换为完整密钥'

curl --fail --silent --show-error \
  'https://24topnews.com/api/v1/events?range=24h&limit=10' \
  -H "Authorization: Bearer $TOPNEWS_API_KEY"
```

- 完整API Key只在生成时显示一次。
- 不要把API Key写入URL、浏览器公开代码、提示词、回答、日志或公开仓库。
- 推荐通过服务端环境变量或密钥管理服务注入。
- Public Beta可能允许匿名请求，但Agent不应依赖匿名额度。

API Key响应头：

| 响应头 | 含义 |
|---|---|
| X-24TopNews-API-Access | `anonymous`或`api_key` |
| X-RateLimit-Limit-Minute | 每分钟额度 |
| X-RateLimit-Remaining-Minute | 当前分钟剩余额度 |
| X-RateLimit-Reset-Minute | 分钟额度重置秒数 |
| X-RateLimit-Limit-Day | 每日额度 |
| X-RateLimit-Remaining-Day | 当日剩余额度 |
| X-RateLimit-Reset-Day | 每日额度重置秒数 |
| Retry-After | 429后建议等待秒数 |

## 3. 接口总览

| 方法与路径 | operationId | 用途 |
|---|---|---|
| GET /api/v1 | — | API版本、文档和接口发现 |
| GET /api/v1/events | listEvents | 检索事件；默认只返回短摘要 |
| GET /api/v1/events/{id} | getEvent | 读取单条事件全文及全部行业影响 |
| GET /api/v1/industries | listIndustries | 查询一级、二级行业名称和代码 |
| GET /api/v1/openapi.json | — | OpenAPI 3.1机器规范 |
| GET /rss.xml | — | 可筛选的全文RSS 2.0 |

## 4. listEvents完整参数

请求：`GET https://24topnews.com/api/v1/events`

多个筛选参数按AND关系组合。

| 参数 | 允许值与默认值 | 含义 |
|---|---|---|
| range | `24h`、`3d`、`7d`、`20d`、`60d`、`200d`；默认`24h` | 相对until向前计算的窗口；提供since后不再决定起点 |
| since | ISO 8601；可选 | 自定义起点，例如`2026-07-01T00:00:00Z` |
| until | ISO 8601；默认当前时间 | 自定义终点；必须晚于since；跨度不超过366天 |
| type | `all`、`macro`、`domestic_macro`、`global_macro`、`market`、`industry`、`company`；默认`all` | `macro`同时包含国内宏观与国外宏观 |
| market | `all`、`A股`、`港股`、`美股`、`商品`、`其他`；默认`all` | 中文值需要URL编码；curl推荐使用`--data-urlencode` |
| industry | 一个二级行业代码；可选 | 例如`10.1`；不接受中文名称、一级代码或逗号分隔多值 |
| direction | `all`、`positive`、`negative`、`mixed`；默认`all` | 至少一个行业影响符合该方向 |
| min_importance | 0—100；默认0 | 事件重要度下限 |
| min_impact | 0—100；默认0 | 至少一个行业影响的绝对强度达到该值 |
| min_confidence | 0—100；默认0 | 至少一个行业影响判断的置信度达到该值 |
| q | 最多120字符；可选 | 在公开标题和正文中做关键词包含检索，不是语义搜索 |
| include | `content`；可选 | 列表增加完整`content_text` |
| limit | 1—50；默认20 | 单页事件数 |
| cursor | 上一页`next_cursor`；可选 | 读取下一页；必须原样传入 |

示例：

```bash
# 过去7天半导体产业链的重要负面事件
curl --get 'https://24topnews.com/api/v1/events' \
  -H "Authorization: Bearer $TOPNEWS_API_KEY" \
  --data-urlencode 'range=7d' \
  --data-urlencode 'industry=10.1' \
  --data-urlencode 'direction=negative' \
  --data-urlencode 'min_importance=50' \
  --data-urlencode 'min_confidence=70' \
  --data-urlencode 'limit=20'

# 自定义时间范围内的宏观事件
curl --get 'https://24topnews.com/api/v1/events' \
  -H "Authorization: Bearer $TOPNEWS_API_KEY" \
  --data-urlencode 'since=2026-07-01T00:00:00Z' \
  --data-urlencode 'until=2026-07-08T00:00:00Z' \
  --data-urlencode 'type=macro' \
  --data-urlencode 'min_importance=60'

# A股公司事件关键词检索
curl --get 'https://24topnews.com/api/v1/events' \
  -H "Authorization: Bearer $TOPNEWS_API_KEY" \
  --data-urlencode 'range=20d' \
  --data-urlencode 'type=company' \
  --data-urlencode 'market=A股' \
  --data-urlencode 'q=产能'
```

## 5. listEvents响应与翻页

```json
{
  "schema_version": "2026-07-29",
  "data": [],
  "pagination": {
    "limit": 20,
    "has_more": true,
    "next_cursor": "不透明字符串"
  },
  "meta": {
    "generated_at": "ISO 8601",
    "time_window": {
      "range": "7d",
      "since": "ISO 8601",
      "until": "ISO 8601"
    },
    "filters": {}
  }
}
```

稳定翻页算法：

```text
cursor = null
循环：
  请求/events并保留原筛选参数
  如果cursor不为空，把cursor原样传入
  按event.id写入本地Map去重
  如果has_more=false则停止
  cursor = next_cursor
```

## 6. Event事件字段

| 字段 | 类型 | 含义 |
|---|---|---|
| id | UUID | 稳定事件ID；用于详情查询、本地去重和增量更新 |
| url | URL | 24TopNews永久中文新闻页面 |
| type | string | `domestic_macro`、`global_macro`、`market`、`industry`或`company` |
| type_label | string | 中文类型名称 |
| markets | string[] | A股、港股、美股、商品或其他 |
| title | string | 重复合并与质量审核后的事实标题 |
| summary | string | 列表候选筛选用短摘要 |
| content_text | string，可选 | 完整公开正文；详情始终返回，列表需`include=content` |
| published_at | ISO 8601 | 事件发布时间 |
| updated_at | ISO 8601 | 正文或分析最后修订时间 |
| first_seen_at | ISO 8601 | 系统首次识别时间 |
| last_seen_at | ISO 8601 | 最近收到支持报道的时间 |
| importance | integer 0—100 | 新闻重要度 |
| is_key_event | boolean | 是否达到重点事件标准 |
| source_count | integer | 重复合并后的独立RSS来源数量 |
| impacts | IndustryImpact[] | 对一个或多个二级行业的影响；市场新闻可为空 |

## 7. getEvent读取全文

请求：`GET /api/v1/events/{id}`

```bash
curl 'https://24topnews.com/api/v1/events/事件UUID' \
  -H "Authorization: Bearer $TOPNEWS_API_KEY"
```

详情响应：

```json
{
  "schema_version": "2026-07-29",
  "data": {
    "id": "UUID",
    "title": "标题",
    "summary": "短摘要",
    "content_text": "完整正文",
    "impacts": []
  },
  "meta": { "generated_at": "ISO 8601" }
}
```

## 8. listIndustries行业名称转代码

请求：`GET /api/v1/industries`

| 参数 | 允许值 | 含义 |
|---|---|---|
| level | `all`、`1`、`2`；默认`all` | 1返回一级行业；2返回可用于events筛选的二级行业 |
| q | 名称、代码或一级行业名称；最多80字符 | 包含匹配，例如`q=科技`可返回科技下属二级行业 |

返回字段：`id`、`name`、`level`、`parent_id`、`parent_name`、`description`、`url`。

```bash
# 名称转代码
curl --get 'https://24topnews.com/api/v1/industries' \
  -H "Authorization: Bearer $TOPNEWS_API_KEY" \
  --data-urlencode 'level=2' \
  --data-urlencode 'q=人工智能'

# 返回10.4后查询事件
curl 'https://24topnews.com/api/v1/events?range=7d&industry=10.4' \
  -H "Authorization: Bearer $TOPNEWS_API_KEY"
```

行业规则：

- `industry`只接受一个二级行业代码。
- 一级行业只组织目录，不能直接作为events的有效行业筛选值。
- 多行业比较应分别请求，再按事件`id`合并；不要传`10.1,10.4`。
- 一个事件可影响多个行业。industry决定事件是否入选，不会删除返回中的其他impacts。

## 9. 完整行业代码：16个一级、139个二级

### 1 能源

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 1.1 | 煤炭 | 煤矿开采、煤炭运输、煤机设备、焦炭、煤化工、洗煤 |
| 1.2 | 油气开采 | 石油、天然气勘探与开采 |
| 1.3 | 油气设备 | 钻探、油田服务设备 |
| 1.4 | 油气炼化 | 炼油、石化加工 |
| 1.5 | 油气配销 | 燃气销售、加油站、成品油销售 |
| 1.6 | 核能发电 | 核电站运营、核电设备 |
| 1.7 | 核能设备 | 核电设备制造 |
| 1.8 | 火力发电 | 火电、热电运营 |
| 1.9 | 水力发电 | 水电站运营 |
| 1.10 | 风光发电 | 光伏、风力、太阳能发电运营 |
| 1.11 | 风光设备 | 光伏组件、硅片、风机设备制造 |
| 1.12 | 电力设备 | 变压器、开关柜、配电设备 |
| 1.13 | 输电网络 | 电网、特高压、电缆 |
| 1.14 | 电池与储能 | 锂电池、动力电池及材料、储能设备制造与电站运营 |

### 2 矿业资源

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 2.1 | 能源金属 | 锂、钴、稀土等新能源关键金属 |
| 2.2 | 贵金属矿 | 黄金、白银、贵金属矿 |
| 2.3 | 有色金属 | 铜、铝、锌、钨等有色金属采选冶炼 |
| 2.4 | 非金属矿 | 石灰石、萤石、石墨、盐湖等非金属矿采选 |
| 2.5 | 资源回收 | 再生资源、危废、垃圾处理、电子废弃物回收，不含水务 |

### 3 化工材料

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 3.1 | 基础化学 | 氯碱、纯碱、无机盐、化学原料、烧碱 |
| 3.2 | 特种化学 | 精细化工、新材料、氟化工、聚氨酯、钛白粉、染料 |
| 3.3 | 电子化学 | 电子化学品、光刻胶、湿电子化学品、抛光液 |
| 3.4 | 农药化肥 | 农药、复合肥、尿素、化肥、杀虫剂、除草剂 |
| 3.5 | 医药化学 | 原料药、医药中间体、药用辅料、API |
| 3.6 | 基础建材 | 水泥、玻璃、陶瓷、石膏、混凝土 |
| 3.7 | 功能建材 | 防水、耐火、保温材料、管材、玻纤、涂料 |
| 3.8 | 造纸 | 纸浆、文化纸、包装纸、生活用纸、造纸 |

### 4 农林牧渔

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 4.1 | 种植业 | 种植、种业、林业、经济作物 |
| 4.2 | 渔业 | 水产、海洋捕捞、水产品 |
| 4.3 | 畜牧业 | 生猪、家禽、饲料、畜禽养殖 |

### 5 食品饮料

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 5.1 | 粮油食品 | 粮油、肉制品、食品加工、食用油、面粉、大米 |
| 5.2 | 调味料 | 酱油、醋、味精、调味品、蚝油 |
| 5.3 | 生鲜果蔬 | 蔬菜、水果、生鲜、果蔬 |
| 5.4 | 方便食品 | 烘焙、速冻食品、预制菜、糕点、面包 |
| 5.5 | 零食 | 坚果、糖果、休闲食品、零食、卤味 |
| 5.6 | 饮品 | 果汁、茶饮、软饮料、功能饮料、乳业、牛奶、奶粉、酸奶 |
| 5.7 | 酒类 | 白酒、啤酒、黄酒、葡萄酒 |
| 5.8 | 烟草 | 烟草、卷烟 |

### 6 制造业

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 6.1 | 钢铁制造 | 钢铁、钢材、特钢、钢板 |
| 6.2 | 纺织制造 | 棉纺、化纤、纱线、面料、纺织品、印染 |
| 6.3 | 包装印刷 | 包装制品、印刷、烟标、酒盒、纸盒、瓦楞纸箱 |
| 6.4 | 工业通用设备 | 机床、数控、电梯、阀门、泵、仪器仪表、工业自动化、工业空调、紧固件、模具 |
| 6.5 | 化学设备 | 化工设备、压力容器、反应釜、锅炉 |
| 6.6 | 食品设备 | 食品、包装机械、灌装设备 |
| 6.7 | 农业设备 | 农机、拖拉机、收割机 |
| 6.8 | 建筑机械 | 工程机械、挖掘机、起重机、装载机 |
| 6.9 | 铁路设备 | 轨道交通、机车、高铁、地铁车辆 |
| 6.10 | 船舶制造 | 造船、船舶、海洋工程 |
| 6.11 | 航空制造 | 飞机、航空装备、航空器、无人机 |
| 6.12 | 军工装备 | 军工、武器、弹药、国防装备 |

### 7 建筑地产

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 7.1 | 住宅开发 | 房地产开发、住宅销售、商品房 |
| 7.2 | 商业开发 | 商业地产、商业综合体、写字楼、购物中心 |
| 7.3 | 民用建筑 | 房屋建筑施工、工程承包、房建、建筑工程 |
| 7.4 | 公用建筑 | 市政工程、水利工程、公路工程、基础设施 |
| 7.5 | 工业建筑 | 工业厂房建设 |
| 7.6 | 市政公用 | 自来水供应、污水处理、供热、供气、水环境治理 |
| 7.7 | 房产经纪 | 房产中介、二手房交易、房产代理、房产咨询 |
| 7.8 | 物业管理 | 物业管理服务、物业服务、家政保洁 |
| 7.9 | 房产信托 | REITs、房地产投资信托、房产信托 |

### 8 汽车

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 8.1 | 汽车零部件 | 汽车零部件、发动机、变速箱、轮胎、连接器 |
| 8.2 | 传统汽车 | 燃油乘用车、商用车整车制造 |
| 8.3 | 新能源车 | 新能源汽车整车制造 |
| 8.4 | 汽车服务 | 汽车经销、租赁、维修、二手车、充电桩 |
| 8.5 | 轻型出行 | 摩托车、电动自行车、电动滑板车、平衡车、全地形车 |

### 9 电子设备

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 9.1 | 电子元件 | PCB、LED、面板、显示屏、连接器、传感器、激光器 |
| 9.2 | 家电零件 | 压缩机、电机、家电零部件、热交换器 |
| 9.3 | 网络设备 | 通信设备、路由器、交换机、光通信、光模块 |

### 10 科技

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 10.1 | 半导体产业链 | 芯片设计、晶圆制造、封装测试、半导体设备、关键零部件及材料 |
| 10.2 | 物联网 | 物联网、传感器、RFID、智能计量 |
| 10.3 | 云服务 | 云计算、数据中心、IDC |
| 10.4 | 人工智能 | AI、大模型、算法、机器学习、自动驾驶 |
| 10.5 | 机器人 | 工业机器人、协作机器人、AGV、服务机器人、人形机器人、特种机器人 |
| 10.6 | 通用软件 | 通用软件、信息技术服务、系统集成、网络安全 |
| 10.7 | 专业软件 | 企业管理软件、ERP、SaaS、CRM |
| 10.8 | 专业服务 | 咨询、人力资源、检测认证、广告服务、会展 |

### 11 互联网传媒

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 11.1 | 电信运营 | 电信运营商、宽带、移动通信 |
| 11.2 | 数字营销 | 搜索引擎、在线广告、数字营销 |
| 11.3 | 社交媒体 | 社交网络、微博 |
| 11.4 | 流媒体 | 在线音乐、视频、直播、短视频 |
| 11.5 | 游戏软件 | 游戏开发运营、网络游戏、手游 |
| 11.6 | 综合互联网 | 多元化互联网平台，包括游戏、社交、广告、金融等业务 |
| 11.7 | 本地生活服务 | 外卖、网约车、同城配送、社区团购、本地生活平台 |

### 12 消费零售

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 12.1 | 家用电器 | 空调、冰箱、洗衣机、白电、小家电、厨电 |
| 12.2 | 电脑 | 计算机、服务器、PC、笔记本电脑 |
| 12.3 | 手机 | 手机、智能终端制造 |
| 12.4 | 数码电子 | 消费电子、智能硬件、耳机、智能手表、无人机 |
| 12.5 | 鞋服 | 服装、鞋类、家纺、服饰、内衣 |
| 12.6 | 居家用品 | 日用品、文具、玩具、家居用品、餐厨具 |
| 12.7 | 家装装修 | 家具、橱柜、门窗、地板、卫浴、全屋定制 |
| 12.8 | 体育用品 | 运动器材、健身器材 |
| 12.9 | 宠物行业 | 宠物食品、宠物用品 |
| 12.10 | 珠宝首饰 | 珠宝、首饰、钟表 |
| 12.11 | 潮流玩具 | 潮玩 |
| 12.12 | 奢侈品 | 高端箱包、时装、奢侈品牌 |
| 12.13 | 医药零售 | 药店、药品零售、医药流通 |
| 12.14 | 实体零售 | 超市、百货、商贸、连锁门店、便利店 |
| 12.15 | 免税零售 | 免税店、离岛免税 |
| 12.16 | 国内电商 | 电子商务、电商平台，境内业务 |
| 12.17 | 跨境电商 | 跨境出口电商 |

### 13 医疗健康

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 13.1 | 西药 | 化学制药、化学药品、制剂、仿制药、创新药 |
| 13.2 | 中药 | 中药、中成药、中药材、中药饮片 |
| 13.3 | 生物医疗 | 生物制品、血液制品、生物医药、疫苗 |
| 13.4 | 医疗耗材 | 医用耗材、注射器、输液器、敷料、胶囊 |
| 13.5 | 医疗设备 | 医疗器械、医学影像、监护仪、体外诊断设备 |
| 13.6 | 综合医院 | 综合医院运营、医疗服务 |
| 13.7 | 专科医院 | 眼科、齿科、口腔等专科医院 |
| 13.8 | 远程医疗 | 远程医疗、互联网医疗、在线问诊 |
| 13.9 | 健康管理 | 体检、健康管理、第三方医学检验 |
| 13.10 | 医疗美容 | 医美、整形、玻尿酸、肉毒素 |
| 13.11 | 营养保健 | 保健品、营养食品、膳食补充剂 |
| 13.12 | 健康个护 | 个人护理、卫生用品、卫生巾、纸尿裤 |
| 13.13 | 化妆品 | 化妆品、日化、护肤、彩妆 |
| 13.14 | 养老护理 | 养老服务、护理 |
| 13.15 | 医药研发服务 | CRO、SMO、CDMO、CRDMO、临床前研究、临床试验、药物研发外包、生物分析、数据统计、注册申报、工艺开发、生产放大及受托商业化生产 |

### 14 金融

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 14.1 | 国有银行 | 工农中建交邮储等国有大型银行 |
| 14.2 | 商业银行 | 股份制银行、商业银行 |
| 14.3 | 地方银行 | 城商行、农商行、村镇银行 |
| 14.4 | 券商 | 证券、投行、经纪业务、承销 |
| 14.5 | 公募基金 | 公募基金管理 |
| 14.6 | 私募基金 | 私募、股权投资、创投、风险投资 |
| 14.7 | 人寿保险 | 人寿、寿险、人身险 |
| 14.8 | 财产保险 | 财产保险、车险 |
| 14.9 | 再保险 | 再保险、分保 |
| 14.10 | 多元金融 | 融资租赁、小额贷款、典当、担保、AMC、信托等非银金融 |
| 14.11 | 金融科技 | 互联网金融、金融信息服务、金融软件 |
| 14.12 | 支付服务 | 第三方支付、收单、支付清算 |
| 14.13 | 数字货币 | 数字货币、区块链、加密货币 |

### 15 交通物流

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 15.1 | 公路运输 | 高速公路、公交、客运 |
| 15.2 | 铁路运输 | 铁路客货运 |
| 15.3 | 航运港口 | 航运、港口、海运、集装箱运输 |
| 15.4 | 航空运输 | 航空公司、机场、航空运输 |
| 15.5 | 物流快递 | 物流、快递、仓储、供应链、配送 |

### 16 教育文旅

| industry参数 | 标准行业名称 | 覆盖范围 |
|---|---|---|
| 16.1 | 基础教育 | 教材、教辅、K12、学前教育 |
| 16.2 | 职业教育 | 职业培训、技能培训、在线教育 |
| 16.3 | 文化出版 | 出版、图书、传媒、报刊、广电 |
| 16.4 | 影音娱乐 | 影视、电影、院线、娱乐、文创 |
| 16.5 | 旅游 | 景区、旅行社、主题公园、文旅 |
| 16.6 | 酒店 | 酒店运营、住宿、度假村 |
| 16.7 | 餐饮服务 | 餐厅、连锁餐饮、快餐、外卖 |

## 10. IndustryImpact字段

| 字段 | 类型/取值 | 含义 |
|---|---|---|
| industry_id | string | 受影响二级行业代码 |
| industry_name | string | 标准二级行业名称 |
| parent_id / parent_name | string或null | 所属一级行业代码与名称 |
| direction | `positive`、`negative`、`mixed` | 正向、负向或多空交织 |
| impact | integer -100—100 | 带方向影响值；绝对值越大影响越强 |
| confidence | integer 0—100 | 行业影响判断置信度 |
| time_horizon | `immediate`、`short`、`medium`、`long` | 即时、短期、中期或长期 |
| channels | string[] | 需求、成本、政策、供应链等传导渠道 |
| rationale | string | 方向、强度和周期的判断依据 |

## 11. Agent推荐工作流

```text
输入用户问题
→ 提取时间窗口、新闻类型、市场、行业名称、方向和阈值
→ 有行业名称但无代码：listIndustries
→ listEvents（默认不取全文）
→ 按问题相关性、importance、impact、confidence筛选
→ 对少量最终事件调用getEvent
→ 保留相反方向与不确定性
→ 输出查询窗口、事实、行业影响、传导渠道和置信度
```

推荐Agent系统指令：

```text
你可以调用24TopNews财经事件API。
用户提到中文行业名称时，先调用listIndustries找到二级行业代码。
再调用listEvents筛选时间、类型、市场、重要度、影响方向和置信度。
只对真正相关的少量事件调用getEvent读取全文。
回答时注明查询时间窗口，区分事件事实、24TopNews行业影响判断和你的综合推断。
importance和impact不是预期收益，不得据此生成买卖建议。
收到429时遵循Retry-After；其他错误按文档处理。
```

## 12. JavaScript示例

```js
const params = new URLSearchParams({
  range: "24h",
  type: "industry",
  min_importance: "60",
  limit: "20"
});

const response = await fetch(
  `https://24topnews.com/api/v1/events?${params}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.TOPNEWS_API_KEY}`,
      "User-Agent": "ExampleResearchAgent/1.0"
    }
  }
);

if (response.status === 429) {
  throw new Error(`等待 ${response.headers.get("retry-after")} 秒后重试`);
}
if (!response.ok) throw new Error(await response.text());

const result = await response.json();
for (const event of result.data) {
  console.log(event.id, event.title, event.importance);
}
```

## 13. 全文RSS

基础地址：`https://24topnews.com/rss.xml`

- 支持events接口的时间、类型、市场、行业、方向和阈值参数。
- 单次最多100条。
- `description`是短摘要。
- `content:encoded`是完整公开正文。
- `category`包含新闻类型、市场和受影响行业。

```text
https://24topnews.com/rss.xml?range=24h&limit=50
https://24topnews.com/rss.xml?range=7d&type=company&min_importance=60
https://24topnews.com/rss.xml?range=3d&industry=10.1&direction=negative
```

## 14. 错误与重试

| 状态/错误 | 原因 | Agent动作 |
|---|---|---|
| 400 invalid_parameter | 参数无效 | 修正参数，不要原样重试 |
| 400 invalid_cursor | 游标损坏或被修改 | 保留筛选条件，从第一页重新查询 |
| 400 invalid_time_window | since不早于until | 修正时间 |
| 400 time_window_too_large | 时间跨度超过366天 | 拆分窗口 |
| 400 invalid_event_id | UUID格式错误 | 使用列表返回的原始id |
| 401 invalid_api_key | 密钥无效、撤销或过期 | 停止重试并检查密钥 |
| 403 insufficient_scope | 缺少权限 | 停止重试并联系管理员 |
| 404 event_not_found | 事件不存在或未公开 | 跳过事件 |
| 429 | 分钟或每日额度用完 | 读取Retry-After，等待并降低并发 |
| 500 internal_error | 服务暂时异常 | 等待1秒、3秒、9秒，最多重试3次 |

## 15. OpenClaw

方式一：把本文档URL直接交给具有网页读取和HTTP调用能力的OpenClaw Agent：

```text
请先完整阅读 https://24topnews.com/developers/agent-guide.md，
然后使用环境变量TOPNEWS_API_KEY按文档调用24TopNews。
```

方式二：安装精简Skill：

```bash
mkdir -p ./skills/24topnews
curl --fail --location \
  'https://24topnews.com/developers/openclaw-skill' \
  --output ./skills/24topnews/SKILL.md
```

`~/.openclaw/openclaw.json`：

```json5
{
  skills: {
    entries: {
      "24topnews": {
        enabled: true,
        apiKey: "tn_live_替换为完整密钥"
      }
    }
  }
}
```

然后运行 `openclaw skills check`。如果Agent运行在Docker沙箱中，主机侧Skill密钥不会自动进入沙箱，需要单独把`TOPNEWS_API_KEY`提供给沙箱。

## 16. 数据边界

- API只返回已公开、完成重复合并、质量审核和客观重写的事件。
- 不返回原始RSS来源名称、原始标题、原始链接或后台审核信息。
- `source_count`只表示独立来源数量。
- API提供财经信息和行业影响研究，不构成证券推荐、交易指令或投资建议。