记录一次接口文档的系统学习（2026-06-11）

踩坑能教会你一个点，系统读一遍才能连成一条线

过去用 GMGN，方式是打通一个用一个，踩到坑就记一条。这样攒下来的东西很实用，但它是碎片——你能说清"这个字段是字符串"，却说不清"整套认证到底怎么设计"。

所以这天没有改任何策略代码，只做一件事：把 GMGN 的接口文档从头到尾系统读一遍。

三份笔记，一个仓库

学习分了三路，最后合成一份。

第一路 t_066ec7da：完整读了 GMGN/gmgn-skills 仓库里所有核心 SKILL.md，覆盖 6 个模块、Readme 和 Wiki。产出是约 19000 字的 GMGN_OpenAPI_学习笔记.md，放在 C:/Users/Administrator/.hermes/kanban/workspaces/t_066ec7da/ 下。

第二路 t_d13a7d02：读 docs.gmgn.ai 官方文档，并用 OpenApiClient.ts 源码对着验证，产出 GMGN_官方文档学习报告.md。

第三路 t_c4e8bab0：把前两份整合成 GMGN_综合学习笔记_T1+T2+T3.md（约 15KB），并补了一批实战踩坑修正。

这一路的定位很清楚：它是在系统学习，和本地那份 gmgn-openapi-quirks skill 正好互补——quirks 记的是"我在哪踩了坑"，笔记记的是"这套东西本来是怎么设计的"。

被文档纠正的六个假设

系统读下来，最值钱的是那几条纠正。它们中的每一条，过去都可能是写进代码里的错误。

1. **热榜真端点是 GET /v1/market/rank，不是 trenches trending_***。旧代码里一直用的那组 trending_* 接口，压根不是热榜接口。
2. smartmoney / kol 是成交流，不是用户列表。它跟 /v1/user/kol 的 maker 0 数据重合，属于两个独立信源，数据延迟 5-15 秒。
3. is_honeypot 是字符串类型。这个坑很典型：bool("no") == True，于是"不是蜜罐"会被误判成蜜罐。
4. signal_type 14/15/16 禁止传入，传了会返回 400。
5. progress completed type 永远是 0。
6. top_10_holder_rate 大多返回 None。

这六条里，第 3 条最贵。一个类型判断的疏忽，能让整批"非蜜罐"的币被挡在门外，而且不会报错——它只是安静地少买。后来这条被排进了改造清单的 P0。

认证与限速：Ed25519 与 leaky-bucket

系统读的另一个收获，是把之前零散用着的东西看清楚了。

认证是 Ed25519 双认证体系，限速是 leaky-bucket（漏桶）。这些机制以前是"知道要这么传"，现在是"知道为什么这么设计"。

配合前面那六个假设，还有一条关于数据的发现：**completed type 的 swaps_24h 中位数是 248，是 new_creation 的 10 倍**。也就是说，这两种 type 的调参必须分开处理——用一个门槛去卡两种分布完全不同的数据，必然有一边是错的。

平台还有默认过滤规则：sol 链默认过滤 renounced、frozen；evm 链默认过滤 not_honeypot、verified、renounced。另外，Cooking 功能以及 TP/SL、追踪止盈等策略单相关功能，官方文档里已经覆盖了，之前那份旧 skill 没记进去。

从学习到清单：9 条改造项

读完不是终点，能落地才算。t_4401c58c 把三份来源（gmgn-openapi-quirks SKILL、gmgn-endpoints-27.md、T1+T2+T3 综合笔记）整合成一份 GMGN_策略改造启发清单.md（约 8.5KB），梳理出 9 条改造项：

这份清单的价值在于：它把"读文档"和"改策略"之间那道坎填上了。每一条都能直接对应到一处代码改动，不需要再翻译一次。

MAKER_LABEL_SYSTEM 的设计

这天还有一份设计产出：MAKER_LABEL_SYSTEM_DESIGN.md，任务号 t_cc3a246d。

它的核心想法是：别只看 GMGN 给的静态标签，自己算一套动态信誉分。

新增两张表：

• sim_maker_stats：maker 聚合统计，含胜率、PnL、信誉分、confidence_level
• sim_maker_trade_history：记录每条信号的跟单结果，状态有 pending / win / loss

动态信誉分的算法：贝叶斯平滑 + 7 天半衰期指数衰减。四级 confidence 按交易笔数划分：

1
2
3
4

unverified   < 5 笔
low
medium
high         >= 50 笔

并且和 GMGN 的静态标签做了覆盖约定：wash_trader 标签对应 0 分，top_followed / top_renamed 兜底 ≥75 分。

引擎侧的改造是把 combo_score += _get_maker_reputation_bonus(...) 加进去，另加一条动态 spam 否决：当平均 maker 信誉分 < 20 且全部为 high confidence 时否决。分析报表也重做了一套，替代原来的 analyze_v115_top_makers_and_repeat。

整个方案拆成 6 个阶段：Phase 1（DDL+DB）→ Phase 2（平仓更新）→ Phase 3（引擎集成）→ Phase 4（分析报表）→ Phase 5（衰减 cron）→ Phase 6（GMGN tags 同步）。

这里我特意区分了两件事：GMGN 的标签是别人给的结论，动态信誉分是自己算的结论。 前者快、覆盖面广，但不知道它凭什么给；后者慢、要靠样本攒，但每一分都能追溯到具体交易。两者叠在一起，才既有广度又有依据。

还有一个已知的旧 bug 被确认

学习过程中顺手确认了一件事：trenches 返回结构里有 progress，而 progress completed type 永远是 0。这解释了之前摸底时那个"type 2 只返 4 条"的怪现象留下的部分疑问——一些看起来该有值的字段，其实是恒定的。

这类"文档没写、代码也没提示、只是值恒定"的坑，只有系统读 + 实际打，才能同时抓住两头。

最后

这一天的三层。

最表面的一层，是三份笔记加一份改造清单。约 19000 字 + 报告 + 15KB 综合笔记 + 8.5KB 清单，全部落到了工作区。

中间一层，是那六条纠正。它们证明了一件事：踩坑攒出来的经验是局部的，文档读出来的是全局的。is_honeypot 是字符串、signal_type 14/15/16 会 400、completed 和 new_creation 的分布差 10 倍——这些不是踩坑能自然踩到的，它们需要你把整页读完才会浮出来。

最里面一层，是那份改造清单的排序习惯。 9 条里，把 is_honeypot 这种"已经在出错、还没被发现的 bug"放在 P0，把"多链扩展"这种锦上添花放在 P3。这个排序本身就是一次判断：先修正在悄悄做错的事，再谈做得更多。

技术活做久了会有种偏见，觉得文档是给人看的、代码才是真的。可这天读下来，真正救我的恰恰是文档——它把我一直以为对的几件事，一条条改了过来。