# 美国市场黄金ETF每日申购净流入 — 数据源地图与实施 (2026-08-26 探索+落地+二次验证)

需求: 美国市场黄金ETF每日净流入(用户要求: 日频+3-5年历史+多ETF覆盖; 用于中美黄金ETF资金流对比/黄金趋势)。

## 已上线数据体系(3层, 2026-08-26 全部落地)

| 层 | 源 | 频率 | 历史 | 覆盖 | 脚本 | cron |
|----|----|----|----|----|----|----|
| 每日多ETF | GoldKimp API | 日 | 2025-11起~10个月 | GLD/GLDM/IAU/SGOL/IAUM | fetch_us_gold_etf_goldkimp.py | 21509a3838d8 周二~六08:35 |
| 权威周/月 | WGC fsapi | 周/月 | 周2018起/月2003起 | 北美区=美国市场(USD+吨) | fetch_us_gold_etf_wgc.py | 8c6774ab57db 周一09:00 |
| GLD单只每日 | SSGA官方 | 日 | 自积累 | GLD(占市场~60%) | fetch_us_gold_etf.py | ed825865eb29 周二~六08:30 |

所有fetch脚本在 `quant/fetch_us_gold_etf*.py`, 输出CSV到quant/; cron script必须放~/.hermes/scripts/包装(绝对路径报错)。

## 🥇 GoldKimp API — 免费每日多ETF净流入(本次最大发现)
- **端点**: `https://goldkimp.com/wp-json/ck/v1/etf-flow`(WordPress自定义REST), 无鉴权, 代理/直连均可
- **完整结构**: `meta`(updated_at_kst/unit=10억=10亿韩元) + `table`(最近15交易日逐ETF) + `chart`(x=日期数组, **bars=5个系列数组, 顺序GLD/GLDM/IAU/SGOL/IAUM(无Total)**, **total=合计净流入201天**, **subH=金价美元/oz 201天**) + **intl.table_m**(最近15天**US$M单位**逐ETF, 与chart同数据美元口径)
- **单位**: 10亿韩元; 换算百万美元 = 值×1e9/1350(USDKRW) ≈ ×0.7407; 官方intl美元表可交叉验证(10亿韩元×1e9/1350≈intl US$M, 汇率微差)
- **单位验证方法**: chart.bars与table同日对比(如05-Aug GLD=932.6两处一致)确认chart=10亿韩元同table——拿到新API先做同日对比, 勿假设单位
- **历史**: chart仅~201天(2025-11-03起), 无参数可扩(period/range/from/days全被忽略)
- **数据质量**: GLD/GLDM/SGOL完整; **IAU/IAUM部分日期为0**(数据源缺失); 日期格式 `%d-%b-%Y`与`%d-%b-%y`混合(parse两种); chart.x偶有重复日期(入库按trade_date去重)
- **⚠️ 数据失真日(必须清洗)**: GoldKimp有单日异常值(2026-03-04/06-22/07-06, 如6/22 Total=255309十亿韩元≈1900亿美元/日, 真实单日最大~40-60亿美元)——**清洗规则: 任一日|Total|>3000(十亿韩元≈22亿美元)的ETF列置0**(generate_us_gold_etf_monitor.py ANOM=3000)
- **验证**: 8/24 GLD+2189(10亿韩元)≈16.2亿美元, 与WGC周度(8/21周北美+43.7亿)量级吻合
- 页面JS里有`data-api`属性可确认端点; 脚本已做日期去重幂等

## 美国黄金ETF监测图 (generate_us_gold_etf_monitor.py, 2026-08-26 v8最终版)
- **⚠️ 用户纠正: 必须用日变动率口径, 不是净流入绝对值**(用户原话\"应该关注的是日变动率\")——v1/v2用Total绝对值做百分位信号(ma5/ma10=Total的5/10日均值)被否, 与国内gold_etf_monitor的daily_pct口径不一致。**v3信号计算与国内完全同构**: daily_pct = 净流入(百万美元)/总资产×100, ma5/ma10 = daily_pct的5/10日均值, pct5/pct10 = 全量百分位, 双确认=pct5&pct10≥90买/≤10卖
- **总资产反推法(历史无AUM数据时的通用解法)**: 当前总资产 = GLD用SSGA实际AUM(us_gold_etf_gld.csv最新aum_usd_m, 155,526M)+其他4只规模估算(18000+45000+3000+3000百万美元)≈2245亿; **历史总资产(t) = 当前总资产 × 金价(t)/金价(T)**——金价驱动黄金ETF资产主体, 10个月窗口误差可控。无资产数据就不能算比例口径时用此法, 勿放弃比例化
- **v4→v8用户逐轮视觉指令演进(每轮vision验证)**:
  - v4/v5: Panel5堆叠柱→**带状图**(fill_between堆叠面积; 流入=5色堆叠上带, 流出=**统一绿色下带**——流出分色叠加后偏蓝紫被vision指出, 统一#2ecc71)
  - v6: Panel3/4单色线→**红绿渐变色点**(`LinearSegmentedColormap.from_list(['#1b5e20','#66bb6a','#fdd835','#fb8c00','#e53935','#b71c1c'])`, scatter c=百分位值)
  - v7: 加**逐段渐变连线**(LineCollection, 每段颜色=两端百分位均值, zorder=2点在线上层)——用户原话\"那些点加上连线\"
  - v8: 用户发现Panel2 IAU/IAUM曲线走平→统计确认**GoldKimp IAU/IAUM数据缺失严重**(IAU仅37%/IAUM仅25%天数非零, 最近8天全0, 韩国站实际只稳定接GLD/GLDM/SGOL)→用户决定\"**那就只看gld吧**\"——所有指标改用GLD单只(`df['Total']=df['GLD']`), Panel2单线/Panel5单带(红=流入/绿=流出), 各面板标题标注GLD
- **6面板结构**: Panel1 金价(LBMA subH)+净流入买卖信号(圆大小=GLD净流入USD, 红买绿卖, 深=双确认) / Panel2 GLD累计净流入+信号竖线(标题=最新日变动率%) / Panel3 5日均变动率百分位红绿渐变点+连线(90/10虚线) / Panel4 10日均变动率百分位同款 / Panel5 GLD日净流入带状(红上带/绿下带)+日变动率%蓝线(twinx右轴) / Panel6 金价5日涨跌%柱+百分位橙虚线
- **⚠️ 气泡与遮罩防溢出**: 圆点面积必须cap(`min(flow*FLOW_TO_SIZE, 180)`双确认/80单确认)——无cap时失真日大值让气泡炸图; 背景axvspan只画**双确认**信号(单确认只画点), 否则百分位连续越线形成大面积色带盖住价格线(vision首轮验证抓到)
- **⚠️ 异常清洗在画图脚本内**(ANOM=3000十亿韩元, 失真日3/4、6/22、7/6置0)——**先清洗再算ma/percentile**, 否则失真日污染百分位和气泡
- **输出**: us_gold_etf_monitor.png; 数据CSV: us_gold_etf_daily.csv(trade_date/GLD/GLDM/IAU/SGOL/IAUM/Total/gold_price/unit)
- **⚠️ 已纳入每日推送(b61e55ba1377, 2026-08-26)**: prompt第三部分加`fetch_us_gold_etf_goldkimp.py && generate_us_gold_etf_monitor.py`, 第四部分16→17张图(加us_gold_etf_monitor.png), 第五部分文字总结加读us_gold_etf_daily.csv最新行报告净流入+日变动率%+5/10日百分位信号; 任务名改\"9指数39策略+6组ETF\"。推送08:30先fetch再画图(独立GoldKimp cron在08:35, 重复跑幂等无害)

## WGC fsapi API — 权威历史(周/月), 反爬对策已破解
- **端点**: `https://fsapi.gold.org/api/v11/charts/etfv2/revised/{flows-chart2,holdings-chart2,archive-tablegroup/all}?break-cache=25Aug26`
- **⚠️ 绕WAF要点(实测)**: 必须带 **Chrome完整UA**(`Mozilla/5.0 ... Chrome/126.0 Safari/537.36`)+ **Referer=数据页URL**(china.gold.org或gold.org的goldhub数据页); 普通UA(如'Mozilla/5.0')→403/429; 无headers→429
- **数据**: 每端点返回周/月/季/年聚合, 5个series(North America/Europe/Asia/Other/Gold Price rhs); 北美区=美国市场; USD(原始单位美元, /1e6→百万) + tonnes双口径
- **历史**: Weekly 2018-01起(451条), Monthly 2003起(282条); asOfDate=最近周五
- **⚠️ 无每日数据**: WGC公开图表API只有周/月/季/年; 官网持仓图虽每日更新但数据不在这些端点
- **⚠️ WGC日频xlsx被彻底封死(勿再试)**: `/download/file/NNNN/ETF_Flows_*.xlsx` 主站/中文站均403"拒绝访问"; 带cookie(含__cf_bm)+Referer仍403; **curl_cffi(impersonate='chrome')也403**——Cloudflare+登录session双保护, 免费路径拿不到每日按基金明细

## SSGA GLD官方(每日, 一手)
- URL: `ssga.com/us/en/intermediary/etfs/funds/spdr-gold-shares-gld`
- **解析要点**: `<th class="label">`+`<td class="data">`表格对; **NAV字段="NAV Per Basket"=10万份NAV, 每股须÷100000**; `Shares Outstanding`(M)/`Assets Under Management`($M)/`LBMA Gold Price PM`(金价); 数值strip `$`/`,`/`M`
- 净流入 = Δ份额×NAV → 百万美元; 只给当前值无历史, 靠每日抓取自积累
- GLD AUM $1555亿(2026-08-25)占美国黄金ETF市场~60%; 单只方向性够用

## 已确认无效的路径(勿重复探测)
- **tushare**: `us_fund_share`/`fund_us`/`etf_us` 是getattr假象, 调用报"请指定正确的接口名"——**tushare无美股ETF份额**
- **GitHub**: 无现成GLD/IAU份额历史数据集; 仅yieldcurvemonkey/ETF_Fund_Flows(etf.com抓取脚本, 2023-24未更新, etf.com现已403反爬)
- **ETF.com**: 403 Cloudflare; **Nasdaq api**: /api/quote/GLD/info通但flow接口全404; **Yahoo**: 403无flow
- **stockanalysis.com**: 直连通但无结构化flow(shares在JS渲染, /api/symbol/e/gld/* 全404)
- **Glassnode**: 403需注册付费(主业加密); **AlphaVantage**: 只有价格+成交量, 无ETF流量
- **GoldKimp页面echarts数据**: 不内嵌(异步加载), 直接调API才是正解
- **MacroMicro**: CSV导出需免费注册登录, 数据本质=持仓变化推算(与自算同源)

## 结论
免费可自动化的天花板 = **GoldKimp每日(多ETF, 10个月) + WGC周/月(2003至今权威) + GLD每日自积累**。清单式数据源(GoldKimp/MacroMicro/Glassnode等)本质都是"份额×NAV自算", 不是独立数据源。日频3-5年历史无免费源(需付费API或破解CF)。后续增强: 破解iShares cookie接IAU官方(需先过Cloudflare)。