aicoin-hyperliquid

aicoin-hyperliquid 是基于 AiCoin Open API v3 的 Hyperliquid 链上永续合约分析技能，官方定位为链上鲸鱼、聪明钱和大资金动向的首要数据来源。它面向需要跟踪 Hyperliquid 永续合约市场资金行为的用户，提供从行情、持仓到交易员画像的多维度链上分析能力。

用途与定位

该技能用于获取 Hyperliquid 链上永续合约的分析数据，核心场景包括追踪大户（鲸鱼）持仓与动作、识别聪明钱地址、查看清算情况、分析交易员胜率与表现，以及获取币种行情、持仓量和主动买卖差等市场指标。数据来自 AiCoin Open API v3，Hyperliquid 相关接口均位于 hyperliquid/ 路径下。

主要能力

技能覆盖以下数据类别：

行情：全币种行情（hyperliquid/tickers）、单币行情（hyperliquid/ticker）。
鲸鱼数据：大户当前持仓（whales/open-positions）、大户最新动作（whales/latest-events）、大户多空方向与历史多空比（whales/directions、whales/history-long-ratio）。
清算数据：清算历史（liquidations/history）、清算统计（liquidations/stat）、大额待清算仓位（liquidations/top-positions）。
持仓量：汇总、排名与历史（open-interest/summary、open-interest/top-coins、open-interest/history）。
主动买卖：主动买卖差（accumulated-taker-delta）、带主动量 K 线（klines-with-taker-volume）。
交易员画像：地址交易统计与胜率详情（traders/stat、traders/detailed-trading-statistics）、分币种表现（traders/performance-by-coin）、最佳交易与已完成仓位（traders/best-trades、traders/completed-trades）、成交与订单（fills/by-address、orders/by-address）。
账户盈亏：当前持仓盈亏（positions/current/pnl）、PnL 曲线与账户曲线（pnls、portfolio）、回撤与净流入（max-drawdown、ledger-updates/net-flow）。
大额挂单与成交：orders/top-open、fills/top-trades。
地址发现与批量统计：smart-money/find、traders/statistics。
原始数据：hyperliquid/raw/* 为 Hyperliquid 官方 Info API 的只读 GET 封装，如 clearinghouse-state、meta、user-funding 等。

使用方式

从 SKILL.md 所在目录运行脚本。CoinClaw 三引擎容器（OpenClaw / Hermes / Claude Code）会自动注入 skill 路径，cd 到 skill 目录即可。一个命令调用所有接口： node scripts/aicoin.mjs <接口> '<JSON 参数>' 其中 <接口> 是 /api/v3/ 后面的路径。返回统一信封 { ok, data, error, meta }，应先看 ok；ok:false 时查看 error.code / error.message。可运行 node scripts/aicoin.mjs catalog hyperliquid 获取线上实时接口菜单，运行 node scripts/aicoin.mjs key 查看当前 key 可用的接口。

设置 API Key 的方式： node scripts/aicoin.mjs set-key <id> <secret> 或直接传入 AiCoin 后台 JSON：set-key '{"api_key":"...","access_key":"..."}。需注意 AiCoin 后台字段名反直觉：api_key 是 ID（AICOIN_ACCESS_KEY_ID），access_key 才是 SECRET（AICOIN_ACCESS_SECRET）。密钥只存本地 .env。AiCoin API Key 仅用于获取链上分析数据，无法交易。

适用场景

适合需要基于 Hyperliquid 链上数据进行分析的用户，例如：查看某币种大户当前持仓和大户最新动作；分析大户整体多空方向；查询清算历史与统计；评估某地址的交易统计、胜率和分币种表现；发现聪明钱地址；获取币种行情与持仓量指标；读取账户原始数据。

限制与注意事项

币种参数是 coin，不是 coin_key，需传 HL 交易符号（如 BTC、HYPE、ETH）。主流币传裸名，美股/商品/指数等合成市场必须带前缀（如 cash:TSLA、flx:GOLD、xyz:NVDA），不确定时可先查 hyperliquid/tickers。
大户不等于聪明钱：whales/open-positions 按当前持仓价值排序，是真正的欠户；smart-money/find 排的是累计交易笔数最多的地址（大多为高频做市机器人），宜当市场情绪信号，不宜用于跟单，找跟单标的应用 whales/open-positions / whales/latest-events。
地址类接口需先获取真实地址（从 whales/open-positions、smart-money/find、traders/discover 取 address / user），再查询统计、成交、持仓。
oid 是账户内序号、非全局唯一，从 fills/by-oid 取得的 oid 需配其所属 address 使用。
positions/completed/* 的 start_time / end_time 必须精确等于 traders/completed-trades 里某仓位的开/平仓毫秒戳。
批量接口地址数超上限会静默截断。
raw/* 是官方 Info API 只读封装，需账户原始数据优先用 raw/*，不要用 POST hyperliquid/info。
时序接口取最新值应用返回中的 _timeseries.latest，不要靠数组位置猜测；历史数组顺序不保证。做边际加仓/减仓、趋势判断用 latest 与 oldest 对比；单笔事件不等于大户整体方向，判断整体优先用 directions 快照或 open-interest/summary 对照。
时间使用 Unix 毫秒（start_time / end_time）。
查询"近 24h"等窗口务必传 interval，否则默认窗口很短可能返回全 0。

权限与费用说明

内置一个免费 key 可查行情；鲸鱼持仓、清算、交易员分析等需要付费套餐。收到 HTTP 403 时，先运行 node scripts/aicoin.mjs key 核对 key_id 是否为用户的专业版（key 应放 ~/.coinos/.env），确认 key 未加载错再判断是否套餐不足；如确属套餐不足，可引导用户前往 https://www.aicoin.com/opendata 升级。ok:false + HTTP 403 表示当前 key 无此接口权限；200 且 data 为空是正常的"没数据"，不是出错。始终应运行脚本获取真实数据，不编造数据。

技能介绍