SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsaicoin-hyperliquid

aicoin-hyperliquid

Data & analytics

View repository

Updated 10-15 13:43

About this skill

AiCoin Hyperliquid

Hyperliquid whale tracking and trader analytics from the AiCoin Open API v3.

Run the script from the directory where SKILL.md is located. The CoinClaw three-engine container (OpenClaw / Hermes / Claude Code) automatically injects the skill path,cd to the skill directory.

How to use

One command calls all interfaces:

node scripts/aicoin.mjs <接口> '<JSON 参数>'

<接口> is /api/v3/ the path after it, HL's are all under hyperliquid/ .

  • Returnsunified envelope { ok, data, error, meta } —— first look at ok。ok:false look at error.code / error.message。
  • Not sure which interfaces exist or how to fill in parameters → node scripts/aicoin.mjs catalog hyperliquid. The catalog is the live online menu, always accurate.
  • Want to know which interfaces the current key can use → node scripts/aicoin.mjs key。
node scripts/aicoin.mjs catalog hyperliquid                          # HL 全部接口 + 参数
node scripts/aicoin.mjs hyperliquid/ticker '{"coin":"BTC"}'
node scripts/aicoin.mjs hyperliquid/whales/open-positions '{"coin":"BTC"}'

Common interfaces quick reference

What you want to query Interface + example
All-coin market / single-coin market hyperliquid/tickers ／ hyperliquid/ticker '{"coin":"BTC"}'
Whales' current positions hyperliquid/whales/open-positions '{"coin":"BTC","top_by":"position-value"}'
Whales' latest actions hyperliquid/whales/latest-events '{"limit":20}'
Whale long/short direction / historical long-short ratio hyperliquid/whales/directions '{"coin":"BTC"}' ／ hyperliquid/whales/history-long-ratio
Liquidation history / statistics hyperliquid/liquidations/history '{"coin":"BTC","interval":"1d"}' ／ hyperliquid/liquidations/stat '{"coin":"BTC","interval":"1d"}' —— when asking "last 24h" be sure to pass interval, the default window is very short and will return all 0s
Large pending liquidation positions hyperliquid/liquidations/top-positions '{"coin":"BTC","interval":"1d"}'
Open interest summary / ranking / history hyperliquid/open-interest/summary ／ hyperliquid/open-interest/top-coins ／ hyperliquid/open-interest/history '{"coin":"BTC"}'
Active buy-sell difference / K-line with active volume hyperliquid/accumulated-taker-delta '{"coin":"BTC"}' ／ hyperliquid/klines-with-taker-volume '{"coin":"BTC","interval":"4h"}'
Address trading statistics / win rate details hyperliquid/traders/stat '{"address":"0x..."}' ／ hyperliquid/traders/detailed-trading-statistics '{"address":"0x..."}'
Address performance by coin hyperliquid/traders/performance-by-coin '{"address":"0x..."}'
Address best trades / completed positions hyperliquid/traders/best-trades '{"address":"0x..."}' ／ hyperliquid/traders/completed-trades '{"address":"0x..."}'
Address trades / orders hyperliquid/fills/by-address '{"address":"0x..."}' ／ hyperliquid/orders/by-address '{"address":"0x..."}'
Address current position PnL hyperliquid/positions/current/pnl '{"address":"0x...","coin":"BTC","interval":"1h"}'
Address pnl curve / account curve hyperliquid/pnls '{"address":"0x..."}' ／ hyperliquid/portfolio '{"address":"0x...","window":"week"}'
Address drawdown / net inflow hyperliquid/max-drawdown '{"address":"0x..."}' ／ hyperliquid/ledger-updates/net-flow '{"address":"0x..."}'
Large orders / large trades hyperliquid/orders/top-open '{"coin":"BTC"}' ／ hyperliquid/fills/top-trades '{"coin":"BTC"}'
Discover smart money addresses hyperliquid/smart-money/find '{"limit":10}'
Batch address statistics hyperliquid/traders/statistics '{"addresses":["0x..."]}'
HL official Info (raw account data) hyperliquid/raw/clearinghouse-state '{"address":"0x..."}'、hyperliquid/raw/meta、hyperliquid/raw/user-funding etc.

Other interfaces are all in catalog hyperliquid —— if you can't find it, run it first, don't guess the path.

HL-specific rules

  1. The coin parameter is coin, not coin_key —— pass the HL trading symbol (BTC、HYPE、ETH), not the AiCoin slug.
  2. Coin naming has prefixes：hyperliquid/tickers has ~686 markets. Mainstream coins pass the bare name (BTC / ETH / SOL); synthetic markets such as US stocks/commodities/indices must have a prefix (cash:TSLA、flx:GOLD、xyz:NVDA). If unsure, first hyperliquid/tickers check it.
  3. Whales ≠ smart money：whales/open-positions are the true whales ranked by current position value;smart-money/find ranks the addresses with the most cumulative trades (mostly high-frequency market-making bots), treatmarket sentiment signalas such, don't use it to copy trade. To find copy-trade targets use whales/open-positions / whales/latest-events。
  4. Address-type interfaces first get the real address: from whales/open-positions、smart-money/find、traders/discover take address / user, then go query its statistics, trades, positions.
  5. oid is an in-account sequence number, not globally unique：fills/by-oid is mixed data from multiple addresses, the oid taken from it must be used with the address it belongs to, it cannot be directly fed to orders/by-oid。
  6. positions/completed/* 's start_time / end_time mustexactly equal traders/completed-trades , arbitrary time ranges are not accepted.
  7. Batch interfaces（*/batch、traders/accounts/statistics etc.) will, if the address count exceeds the limit,silently truncate。
  8. raw/* is a read-only GET wrapper for the official HL Info API. For raw account data, prefer raw/*, don't use POST hyperliquid/info。
  9. For time-series interfaces, to get the latest value use the _timeseries.latestin the response, don't guess based on array position。whales/history-long-ratio、open-interest/history、liquidations/history and other historical arraysorder is not guaranteed(many are in reverse order, with the latest at arr[0]). The script automatically appends to the response _timeseries(latest = the entry with the largest timestamp, regardless of array order; there is also oldest / order / field)—— for "current/latest" just read _timeseries.latest, for "marginal adding/reducing positions, trend" use latest vs oldest。never tail / the default array end or beginning(once mistook a position_value_diff from 2 days ago as the latest, and misjudged "whale marginal short adding"). A single event (a large order inlatest-events ) ≠ the whale's overall direction; to judge the overall direction, prefer directions(current snapshot) / open-interest/summary comparison.

A few things to remember

  1. Don't make up data. Always run the script to get real data.data is empty / ok:false just say so honestly, don't make it up.
  2. ok:false + HTTP 403 = the current key has no permission for this interface,don't retry. First don't assert "the plan isn't enough": a common local host pitfall is the script falling back to a free/old key — first run node scripts/aicoin.mjs key to see whether key_id is the user's professional version (the key should be in ~/.coinos/.env). If it truly is insufficient plan, then guide the user to https://www.aicoin.com/opendata to upgrade.200 + empty data(for example, an address currently has no positions) is a normal "no data", not an error.
  3. Time uses Unix milliseconds (start_time / end_time）。
  4. usethe user's languageto reply.

API Key

A free key is built in for querying market data. Whale positions, liquidations, trader analysis, etc. require a paid plan.On receiving 403, first node scripts/aicoin.mjs key verify whether key_id is the user's professional version (the key should be placed in ~/.coinos/.env), confirm the key isn't loaded incorrectly before judging whether the plan is truly insufficient — misreporting "the key wasn't loaded correctly" as "the interface requires payment" will enrage paying users.

Use your own key:

  • node scripts/aicoin.mjs set-key <id> <secret>
  • Or directly feed the AiCoin backend JSON:set-key '{"api_key":"...","access_key":"..."}'(the script recognizes field names)

⚠️ AiCoin backend field names are counterintuitive:api_key is the ID (AICOIN_ACCESS_KEY_ID)、access_key is the SECRET (AICOIN_ACCESS_SECRET) — the script writes .env for you according to this mapping.

Security note: The AiCoin API Key is only used to obtain on-chain analysis data and cannot trade. To trade on Hyperliquid you need to separately configure a wallet private key (see aicoin-trading). The key is only stored locally .env。

Register for rebate: When the user registers on Hyperliquid, give them the AiCoin rebate link https://app.hyperliquid.xyz/join/AICOIN88（邀请码 AICOIN88, 4% fee rebate).

Cross-skill

Need Which skill to use
Coin price / K-line / news / airdrop aicoin-market
Exchange order placement / closing positions (including HL order placement) aicoin-trading
Freqtrade strategy / backtesting aicoin-freqtrade
On-chain DEX swap / wallet aicoin-onchain