dsh-hyperliquid 0.0.1 → 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+- insert:
+    - id: hyperliquid
+      name: dsh-hyperliquid
+      config:
+        dataDir: '~/.dsh-hyperliquid'
+        network: mainnet
+        tradingMode: live

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200">
+  <!-- Official Hyperliquid mark (brand kit "Hyperliquid SVG format.zip",
+       Hyperliquid_Blob_Green.svg) on the official brand-dark plate.
+       Source: https://hyperliquid.gitbook.io/hyperliquid-docs/brand-kit -->
+  <rect width="200" height="200" rx="44" fill="#011916"/>
+  <path d="M175.11589,99.27891c0,49.46366-30.3687,65.33789-46.47302,51.30413-13.11357-11.5031-17.02471-35.88989-36.81018-38.42055-25.07698-2.99085-27.37764,30.36839-43.94216,30.36839-19.3254,0-23.00642-27.83773-23.00642-42.33179,0-14.72405,4.14115-34.73961,20.47565-34.73961,19.09528,0,20.24566,28.75802,44.17226,27.14754,23.69661-1.61047,24.1567-31.51877,39.80103-44.17224,13.57335-11.27313,45.78283.69019,45.78283,50.84413Z" fill="#97fce4"/>
+</svg>

package/index.js

@@ -0,0 +1,118 @@
+/**
+ * dsh-hyperliquid — host half.
+ *
+ * Publishes the `hyper` Remote namespace (Typert, dsh-bots-anchored), registers
+ * the hyper_* agent tools, and contributes a short system-prompt section so
+ * agents in any session know the trading desk exists and how to drive it.
+ * The client half (client.js) renders the peer-level trading platform.
+ *
+ * @module dsh-hyperliquid
+ */
+
+import { HyperRemote } from './lib/remote.js'
+import { buildToolDefinitions } from './lib/tools.js'
+import { registerHyperSkill } from './lib/skill.js'
+
+export const name = 'dsh-hyperliquid'
+
+/** Optional services only: without `tools` the desk still serves the UI. */
+export const inject = []
+
+let z = null
+try {
+  // Prefer the HOST's schemastery copy (same implementation the loader
+  // validates with) resolved through the dsh-bin anchor; fall back to the
+  // bundled copy. require(esm) — Node ≥ 22.12.
+  const { createRequire } = await import('node:module')
+  const { realpathSync } = await import('node:fs')
+  try {
+    const anchor = realpathSync(process.argv?.[1] ?? '')
+    z = createRequire(anchor)('@deepseek-ai/schemastery')
+    if (!z || typeof z.object !== 'function') z = null
+  } catch { /* anchor unavailable → bundled copy */ }
+  if (!z) z = (await import('@deepseek-ai/schemastery')).default
+} catch (err) {
+  throw new Error(`[dsh-hyperliquid] schemastery 加载失败：${String(err?.message ?? err)}`)
+}
+
+export const Config = z.object({
+  dataDir: z.string().description('插件数据目录（交易会话登记表与 paper 账户落盘处）').default('~/.dsh-hyperliquid'),
+  network: z.union([z.const('mainnet'), z.const('testnet')]).description('Hyperliquid 网络，默认 mainnet；testnet 可在交易台「更多」中切换').default('mainnet'),
+  tradingMode: z.union([z.const('paper'), z.const('live')]).description('交易模式：live 真实签名下单（默认），paper 本地撮合；可在交易台「更多」中切换').default('live'),
+  privateKey: z.string().description('Hyperliquid 钱包私钥（signer=local 时使用；建议用 agent wallet 派生密钥；留空则 live 不可用）。也可用环境变量 HYPERLIQUID_PRIVATE_KEY').default(''),
+  signer: z.union([z.const('local'), z.const('web3')]).description('签名方式：local 插件内私钥签名；web3 交给 dsh-web3 钱包保险库签名（私钥不出保险库，逐笔过签名策略与审批）').default('local'),
+  web3Account: z.string().description('signer=web3 时使用的 dsh-web3 账户 id 或名称').default('main'),
+  tradingAddress: z.string().description('Hyperliquid 主账户地址；使用 dsh-web3 API wallet 签名时必填，账户查询必须用主账户地址').default(''),
+  autonomousLive: z.boolean().description('允许 agent 在硬性限额内自主提交 live 订单；默认关闭，且仅支持 dsh-web3 签名').default(false),
+  allowedCoins: z.string().description('交易限额（paper/live 均生效）：允许新开仓的币对，逗号分隔；减仓不受限').default('BTC,ETH'),
+  maxOrderUsd: z.number().description('交易限额（paper/live 均生效）：单笔名义价值上限 USD').default(100),
+  maxDailyUsd: z.number().description('交易限额（paper/live 均生效）：每 UTC 日累计开仓名义价值上限 USD，paper 与 live 分账').default(500),
+  maxPositionUsd: z.number().description('交易限额（paper/live 均生效）：每币最大仓位名义价值 USD').default(500),
+  maxLeverage: z.number().description('交易限额（paper/live 均生效）：最大杠杆倍数').default(2),
+}).description('Hyperliquid 交易台配置')
+
+/**
+ * @param ctx - the Cordis plugin context.
+ * @param config - validated row config.
+ */
+export function apply(ctx, config = {}) {
+  const remote = new HyperRemote(ctx, config)
+  const disposers = []
+
+  // Live channel lifecycle: stop the upstream WS on teardown.
+  ctx.effect(() => () => remote.stopWs())
+
+  // Agent tools (optional service — degrade gracefully).
+  const tools = typeof ctx?.get === 'function' ? ctx.get('tools') : undefined
+  if (tools && typeof tools.register === 'function') {
+    for (const def of buildToolDefinitions(remote)) {
+      const remove = tools.register(def)
+      disposers.push(remove)
+      ctx.effect(() => () => { try { remove() } catch { /* already gone */ } })
+    }
+  } else {
+    ctx.logger?.warn?.('[dsh-hyperliquid] tools 服务不可用，仅提供 UI 远端')
+  }
+
+  const skillRemove = registerHyperSkill(typeof ctx?.get === 'function' ? ctx.get('skills') : null)
+  if (skillRemove) {
+    disposers.push(skillRemove)
+    ctx.effect(() => () => { try { skillRemove() } catch { /* already gone */ } })
+  }
+
+  // System-prompt section: make the desk discoverable to every agent, with
+  // LIVE desk context (what the user is looking at right now) evaluated per
+  // prompt — the desk and the conversation stay in lockstep both ways.
+  const systemPrompt = typeof ctx?.get === 'function' ? ctx.get('systemPrompt') : undefined
+  if (systemPrompt && typeof systemPrompt.section === 'function') {
+    const remove = systemPrompt.section({
+      name: 'hyperliquid-desk',
+      order: 500,
+      text: () => {
+        const mode = remote.cfg.tradingMode
+        const net = remote.cfg.network
+        const lines = [
+          '## Hyperliquid 交易台（dsh-hyperliquid）',
+          `本 Harness 装有 Hyperliquid 交易台（mode=${mode}，network=${net}）。用户可在面板看行情并填写交易票据；票据只把意图送入当前会话，所有实际下单只能由你调用工具完成。`,
+          '可用工具：hyper_context（会话交易上下文）、hyper_market（详细行情）、hyper_chart（在行情图上画支撑/阻力与趋势线）、hyper_account（账户）、hyper_decide（交易决策预检并返回一次性 decisionId）、hyper_order（执行/撤单/杠杆）、hyper_session（会话视角）。',
+          '用户说"当前/界面上这个币"时，先 hyper_context 或 hyper_session status；需要技术判断时用 hyper_market indicators 验证趋势、动量、波动和支撑阻力，可用 hyper_chart 将依据画给用户看。交易前核对行情与账户，说明方向、数量、依据及风险。paper 模式用 hyper_order 执行；live 模式先用 hyper_decide 预检，并用返回的一次性 decisionId 执行 hyper_order。是否可自主执行由宿主配置和钱包策略决定。',
+        ]
+        if (skillRemove) lines.push('复杂的 Hyperliquid 分析、交易或异常对账，请先加载 hyperliquid-trading skill。')
+        // Live desk focus: what coin/interval the desk shows right now.
+        try {
+          const desk = remote.desk ?? {}
+          if (desk.coin) lines.push(`当前交易台焦点：${desk.coin} · K线 ${desk.interval ?? '15m'}。用户消息里说"这个币/当前价格/图上"时指的就是它。`)
+        } catch { /* desk context is best-effort */ }
+        return lines.join('\n')
+      },
+    })
+    disposers.push(remove)
+  }
+
+  return () => {
+    for (const d of disposers) {
+      try { d() } catch { /* best effort */ }
+    }
+    remote.stopWs()
+  }
+}

package/lib/hl.js

@@ -0,0 +1,372 @@
+// lib/hl.js — Hyperliquid market-data layer, SDK-backed.
+//
+// Data plane (info + WS) runs on the community-standard TypeScript SDK
+// `@nktkas/hyperliquid` (MIT): HttpTransport for /info requests and
+// WebSocketTransport + SubscriptionClient for live channels. The SDK brings
+// schema-validated requests, automatic reconnection and automatic
+// re-subscription after reconnect — the three things the previous hand-rolled
+// wire layer lacked.
+//
+// The execution plane (/exchange) stays on our own EIP-712 signing
+// implementation (lib/signing.js), which is byte-for-byte validated against
+// the official hyperliquid-python-sdk (see test/signing.test.mjs).
+//
+// Public surface (consumed by lib/remote.js): HyperliquidClient, keys, sigFigs.
+// Snapshot keys and payload shapes are unchanged, so the remote layer and the
+// web desk are source-compatible.
+
+import { canonicalAction, signL1Action } from './signing.js'
+
+const MAINNET = 'https://api.hyperliquid.xyz'
+const TESTNET = 'https://api.hyperliquid-testnet.xyz'
+const WS_MAINNET = 'wss://api.hyperliquid.xyz/ws'
+const WS_TESTNET = 'wss://api.hyperliquid-testnet.xyz/ws'
+
+function quietUnsubscribe(channel) {
+  try { Promise.resolve(channel?.unsubscribe()).catch(() => {}) }
+  catch { /* transport already closing */ }
+}
+
+/** Round to `maxDecimals` with at most `n` significant figures. */
+export function sigFigs(value, n, maxDecimals) {
+  const num = Number(value)
+  if (!Number.isFinite(num) || num === 0) return '0'
+  const abs = Math.abs(num)
+  const digits = Math.floor(Math.log10(abs)) + 1
+  const decimals = Math.max(0, Math.min(maxDecimals, n - digits))
+  return num.toFixed(decimals)
+}
+
+async function postJson(url, body, timeoutMs = 10_000) {
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(new Error('timeout')), timeoutMs)
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: ac.signal,
+    })
+    const data = await res.json().catch(() => null)
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${JSON.stringify(data)?.slice(0, 300)}`)
+    return data
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * One Hyperliquid endpoint pair (REST + WS) with snapshot caches.
+ * The trading desk instantiates exactly one; clients poll snapshots from it.
+ *
+ * Live channels are ref-counted: remote.js calls subscribe(key)/unsubscribe(key)
+ * as coins gain/lose focus; every callback just refreshes the snapshot map.
+ */
+export class HyperliquidClient {
+  /**
+   * @param {{network?: 'mainnet'|'testnet', privateKey?: string}} opts
+   */
+  constructor(opts = {}) {
+    this.network = opts.network === 'mainnet' ? 'mainnet' : 'testnet'
+    this.restBase = this.network === 'mainnet' ? MAINNET : TESTNET
+    this.wsBase = this.network === 'mainnet' ? WS_MAINNET : WS_TESTNET
+    this.privateKey = opts.privateKey ?? ''
+    // A signer must never reuse a nonce, including concurrent order/cancel calls.
+    this.lastNonce = 0
+
+    // ── SDK transports (lazy: nothing connects until first use) ──
+    this._sdk = null // { HttpTransport, WebSocketTransport, SubscriptionClient, info: {...fns} }
+    this._http = null
+    this._wsTransport = null
+    this._subsClient = null
+    this._liveSubs = new Map() // snapshot key -> ISubscription
+
+    this.ws = null // legacy compat field (unused by the SDK path)
+    this.wsState = 'closed' // closed | idle | connecting | open
+    this.subs = new Map() // key -> {args, listeners:number}
+    this.snapshots = new Map() // key -> latest payload
+    this.snapshotTimes = new Map() // key -> last exchange message received on host
+    this.seqs = new Map() // key -> monotonically increasing revision
+    this.throws = 0
+    this.lastWsError = null
+    this.pingTimer = null // legacy compat (SDK keep-alive handles ping)
+    this.retryTimers = new Map() // failed channel key -> retry timer
+  }
+
+  // ── SDK bootstrap ────────────────────────────────────────────────────
+  _sdkOnce() {
+    if (this._sdk) return this._sdk
+    // Plain dynamic imports keep the SDK optional at parse time and let the
+    // desk degrade to REST-only polling if the package is unavailable.
+    const root = '@nktkas/hyperliquid'
+    const infoApi = `${root}/api/info`
+    const subApi = `${root}/api/subscription`
+    // Deliberately not awaited: transports are created eagerly-ish but callers
+    // await the individual request methods, which await their modules.
+    this._sdk = Promise.all([import(root), import(infoApi), import(subApi)]).then(([r, i, s]) => {
+      this._http = new r.HttpTransport({ isTestnet: this.network !== 'mainnet' })
+      const cfg = { transport: this._http }
+      this._sdkInfo = {
+        meta: () => i.meta(cfg),
+        metaAndAssetCtxs: () => i.metaAndAssetCtxs(cfg),
+        allMids: () => i.allMids(cfg),
+        l2Book: (coin, grouping = null) => i.l2Book(cfg, { coin, ...(grouping ?? {}) }),
+        candleSnapshot: (coin, interval, startTime, endTime) => i.candleSnapshot(cfg, { coin, interval, startTime, endTime }),
+        clearinghouseState: (user) => i.clearinghouseState(cfg, { user }),
+        spotClearinghouseState: (user) => i.spotClearinghouseState(cfg, { user }),
+        userAbstraction: (user) => i.userAbstraction(cfg, { user }),
+        activeAssetData: (user, coin) => i.activeAssetData(cfg, { user, coin }),
+        openOrders: (user) => i.openOrders(cfg, { user }),
+        frontendOpenOrders: (user) => i.frontendOpenOrders(cfg, { user }),
+        userFills: (user) => i.userFills(cfg, { user }),
+        historicalOrders: (user) => i.historicalOrders(cfg, { user }),
+        portfolio: (user) => i.portfolio(cfg, { user }),
+      }
+      this._wsTransport = new r.WebSocketTransport({ url: this.wsBase })
+      this._subsClient = new r.SubscriptionClient({ transport: this._wsTransport })
+      // Connection bookkeeping: the transport's event target carries the
+      // system events; ready() resolves once the socket is up.
+      const hlEvents = this._wsTransport._hlEvents
+      hlEvents?.addEventListener?.('error', (ev) => {
+        this.lastWsError = ev?.detail ?? 'ws error'
+        this.wsState = 'connecting'
+      })
+      hlEvents?.addEventListener?.('subscriptionResponse', () => {
+        // Unsubscribe acks arrive here too; with no channels left we are idle.
+        if (this.wsState !== 'closed') this.wsState = this.subs.size ? 'open' : 'idle'
+      })
+      // The SDK socket reconnects and resubscribes on its own; mirror that so
+      // a dropped upstream reads as "connecting" rather than a silent "open".
+      const socket = this._wsTransport.socket
+      socket?.addEventListener?.('close', () => { if (this.wsState !== 'closed') this.wsState = 'connecting' })
+      socket?.addEventListener?.('open', () => { if (this.wsState === 'connecting') this.wsState = this.subs.size ? 'open' : 'idle' })
+      Promise.resolve(this._wsTransport.ready?.()).then(() => {
+        this.wsState = 'open'
+      }).catch((err) => {
+        this.lastWsError = String(err?.message ?? err)
+      })
+      return this._sdkInfo
+    })
+    return this._sdk
+  }
+
+  _infoFns() {
+    return this._sdkOnce().then((fns) => {
+      if (!fns) throw new Error('SDK 初始化失败（@nktkas/hyperliquid 不可用）')
+      return fns
+    })
+  }
+
+  // ── /info ────────────────────────────────────────────────────────────
+  /** Generic /info passthrough with a timeout. `type` values per docs. */
+  info(type, extra = {}, timeoutMs = 10_000) {
+    return postJson(`${this.restBase}/info`, { type, ...extra }, timeoutMs)
+  }
+
+  async meta() { return (await this._infoFns()).meta() }
+  async metaAndAssetCtxs() { return (await this._infoFns()).metaAndAssetCtxs() }
+  async allMids() { return (await this._infoFns()).allMids() }
+  async l2Book(coin, grouping = null) { return (await this._infoFns()).l2Book(coin, grouping) }
+  recentTrades(coin) { return this.info('recentTrades', { coin }) }
+  async candleSnapshot(coin, interval, startTime, endTime) {
+    return (await this._infoFns()).candleSnapshot(coin, interval, startTime, endTime)
+  }
+  async clearinghouseState(user) { return (await this._infoFns()).clearinghouseState(user) }
+  async spotClearinghouseState(user) { return (await this._infoFns()).spotClearinghouseState(user) }
+  async userAbstraction(user) { return (await this._infoFns()).userAbstraction(user) }
+  async activeAssetData(user, coin) { return (await this._infoFns()).activeAssetData(user, coin) }
+  async openOrders(user) { return (await this._infoFns()).openOrders(user) }
+  async frontendOpenOrders(user) { return (await this._infoFns()).frontendOpenOrders(user) }
+  async userFills(user) { return (await this._infoFns()).userFills(user) }
+  async historicalOrders(user) { return (await this._infoFns()).historicalOrders(user) }
+  async portfolio(user) { return (await this._infoFns()).portfolio(user) }
+
+  // ── /exchange ────────────────────────────────────────────────────────
+  /**
+   * Send a signed exchange action. Paper mode never reaches here.
+   * Execution stays on our validated EIP-712 path (lib/signing.js).
+   * @param {object} action L1 action body, e.g. {type:'order', orders:[…], grouping:'na'}
+   */
+  async exchange(action) {
+    if (!this.privateKey) throw new Error('未配置钱包私钥（插件 config.privateKey）；paper 模式下单不经过 /exchange')
+    const nonce = this.nextNonce()
+    const canonical = canonicalAction(action)
+    const signature = await signL1Action(this.privateKey, canonical, null, nonce, this.network === 'mainnet')
+    return postJson(`${this.restBase}/exchange`, { action: canonical, nonce, signature }, 15_000)
+  }
+
+  nextNonce() {
+    this.lastNonce = Math.max(Date.now(), this.lastNonce + 1)
+    return this.lastNonce
+  }
+
+  /**
+   * Send an exchange action with an EXTERNALLY produced signature — the
+   * dsh-web3 path: the private key never leaves the wallet vault, this
+   * client only transports the already-signed envelope.
+   * @param {object} action L1 action body
+   * @param {{r: string, s: string, v: number}} signature wire-form signature
+   * @param {number} nonce the nonce that was hashed into the signature
+   */
+  exchangeSigned(action, signature, nonce) {
+    if (!signature?.r || !signature?.s || !signature?.v) throw new Error('exchangeSigned 需要完整的 {r,s,v} 签名')
+    return postJson(`${this.restBase}/exchange`, { action: canonicalAction(action), nonce, signature }, 15_000)
+  }
+
+  // ── WebSocket upstream (SDK SubscriptionClient) ──────────────────────
+  /** Map a snapshot key to a SubscriptionClient channel; resolve its ISubscription. */
+  async _openChannel(key, args) {
+    await this._infoFns()
+    this.wsState = 'connecting'
+    const sc = this._subsClient
+    const feed = (payload) => {
+      this.snapshots.set(key, payload)
+      this.snapshotTimes.set(key, Date.now())
+      this.seqs.set(key, (this.seqs.get(key) ?? 0) + 1)
+      this.wsState = 'open'
+    }
+    switch (args?.type) {
+      case 'allMids':
+        return sc.allMids((ev) => feed(ev?.detail ?? ev))
+      case 'allDexsAssetCtxs':
+        return sc.allDexsAssetCtxs((ev) => feed(ev?.detail ?? ev))
+      case 'allDexsClearinghouseState':
+        return sc.allDexsClearinghouseState({ user: args.user }, (ev) => feed(ev?.detail ?? ev))
+      case 'l2Book':
+        return sc.l2Book({ coin: args.coin, ...(args.nSigFigs ? { nSigFigs: args.nSigFigs, ...(args.mantissa ? { mantissa: args.mantissa } : {}) } : {}) }, (ev) => feed(ev?.detail ?? ev))
+      case 'trades':
+        return sc.trades({ coin: args.coin }, (ev) => feed(ev?.detail ?? ev))
+      case 'candle':
+        return sc.candle({ coin: args.coin, interval: args.interval }, (ev) => feed(ev?.detail ?? ev))
+      case 'userFills':
+        return sc.userFills({ user: args.user }, (ev) => feed(ev?.detail ?? ev))
+      case 'userEvents':
+        return sc.userEvents({ user: args.user }, (ev) => feed(ev?.detail ?? ev))
+      default:
+        throw new Error(`unknown subscription type: ${args?.type}`)
+    }
+  }
+
+  /**
+   * Register interest in a WS channel; ref-counted. Returns the snapshot key.
+   * Supported: allMids | allDexsAssetCtxs | {allDexsClearinghouseState, user} | {l2Book, coin} | {trades, coin} | {candle, coin, interval}
+   *            | {userFills, user} | {userEvents, user}
+   */
+  subscribe(key, args) {
+    const row = this.subs.get(key) ?? { args, listeners: 0, channel: null, opening: false }
+    row.listeners += 1
+    this.subs.set(key, row)
+    if (!row.channel && !row.opening) {
+      row.opening = true
+      this._openChannel(key, args)
+        .then((sub) => {
+          row.channel = sub
+          row.opening = false
+          this.wsState = 'open'
+          if (row.listeners <= 0) {
+            // Interest went away while the channel was opening.
+            quietUnsubscribe(sub)
+            row.channel = null
+            this.subs.delete(key)
+            this.snapshots.delete(key)
+            this.snapshotTimes.delete(key)
+          }
+        })
+        .catch((err) => {
+          row.opening = false
+          this.lastWsError = String(err?.message ?? err)
+          if (row.listeners > 0) this._retryChannel(key)
+        })
+    }
+    return key
+  }
+
+  _retryChannel(key) {
+    if (this.retryTimers.has(key)) return
+    const timer = setTimeout(() => {
+      this.retryTimers.delete(key)
+      const row = this.subs.get(key)
+      if (row && row.listeners > 0 && !row.channel && !row.opening) {
+        row.opening = true
+        this._openChannel(key, row.args)
+          .then((sub) => {
+            row.opening = false
+            if (row.listeners <= 0) { quietUnsubscribe(sub); this.subs.delete(key); return }
+            row.channel = sub
+            this.wsState = 'open'
+          })
+          .catch((err) => {
+            row.opening = false
+            this.lastWsError = String(err?.message ?? err)
+            if (row.listeners > 0) this._retryChannel(key)
+          })
+      }
+    }, 3_000)
+    this.retryTimers.set(key, timer)
+  }
+
+  unsubscribe(key) {
+    const row = this.subs.get(key)
+    if (!row) return
+    row.listeners -= 1
+    if (row.listeners <= 0) {
+      if (row.channel) {
+        quietUnsubscribe(row.channel)
+        row.channel = null
+      }
+      this.subs.delete(key)
+      this.snapshots.delete(key)
+      this.snapshotTimes.delete(key)
+      const timer = this.retryTimers.get(key)
+      if (timer) clearTimeout(timer)
+      this.retryTimers.delete(key)
+      // The upstream socket stays connected (SDK keep-alive); only channels went away.
+      if (this.subs.size === 0 && this.wsState !== 'closed') this.wsState = 'idle'
+    }
+  }
+
+  snapshot(key) {
+    const snap = this.snapshots.get(key)
+    const seq = this.seqs.get(key) ?? 0
+    return snap === undefined ? null : { seq, at: this.snapshotTimes.get(key) ?? 0, data: snap }
+  }
+
+  wsStatus() {
+    const lastDataAt = Math.max(0, ...this.snapshotTimes.values())
+    const state = this.wsState === 'open' && lastDataAt > 0 && Date.now() - lastDataAt > 15_000
+      ? 'stale' : this.wsState
+    return { state, lastDataAt, subs: [...this.subs.keys()], lastError: this.lastWsError }
+  }
+
+  close() {
+    for (const timer of this.retryTimers.values()) clearTimeout(timer)
+    this.retryTimers.clear()
+    for (const [key, row] of this.subs) {
+      if (row.channel) {
+        quietUnsubscribe(row.channel)
+        row.channel = null
+      }
+      row.listeners = 0
+    }
+    this.subs.clear()
+    this.snapshots.clear()
+    this.snapshotTimes.clear()
+    try { this._wsTransport?.close?.() } catch { /* already closed */ }
+    this.wsState = 'closed'
+    this.ws = null
+  }
+}
+
+/** Canonical snapshot key builders shared with the remote layer. */
+export const keys = {
+  allMids: () => 'allMids',
+  allDexsAssetCtxs: () => 'allDexsAssetCtxs',
+  allDexsClearinghouseState: (user) => `allDexsClearinghouseState:${user.toLowerCase()}`,
+  l2Book: (coin, grouping = null) => grouping
+    ? `l2BookGrouped:${encodeURIComponent(coin)}:${grouping.nSigFigs}:${grouping.mantissa ?? 0}`
+    : `l2Book:${coin}`,
+  trades: (coin) => `trades:${coin}`,
+  candle: (coin, interval) => `candle:${coin}:${interval}`,
+  userEvents: () => 'userEvents',
+  userFills: (user) => `userFills:${user}`,
+}

package/lib/indicators.js

@@ -0,0 +1,88 @@
+/** Deterministic indicators over exchange candles; no price prediction. */
+
+function sma(values, period) {
+  if (values.length < period) return null
+  return values.slice(-period).reduce((sum, value) => sum + value, 0) / period
+}
+
+function emaSeries(values, period) {
+  if (values.length < period) return []
+  const alpha = 2 / (period + 1)
+  let value = values.slice(0, period).reduce((sum, point) => sum + point, 0) / period
+  const result = [value]
+  for (const point of values.slice(period)) {
+    value = point * alpha + value * (1 - alpha)
+    result.push(value)
+  }
+  return result
+}
+
+function wilder(values, period) {
+  if (values.length < period) return null
+  let result = values.slice(0, period).reduce((sum, value) => sum + value, 0) / period
+  for (const value of values.slice(period)) result = (result * (period - 1) + value) / period
+  return result
+}
+
+function swings(rows, kind) {
+  const picks = []
+  for (let i = 2; i < rows.length - 2; i += 1) {
+    const field = kind === 'low' ? 'l' : 'h'
+    const value = rows[i][field]
+    const neighbors = [rows[i - 2][field], rows[i - 1][field], rows[i + 1][field], rows[i + 2][field]]
+    if (neighbors.every((point) => kind === 'low' ? value <= point : value >= point)) picks.push({ price: value, time: rows[i].t })
+  }
+  return picks
+}
+
+function closeTime(row, interval) {
+  if (Number.isFinite(Number(row.T)) && Number(row.T) >= row.t) return Number(row.T)
+  if (interval === '1M') {
+    const opened = new Date(row.t)
+    return Date.UTC(opened.getUTCFullYear(), opened.getUTCMonth() + 1, 1) - 1
+  }
+  const minutes = { '1m': 1, '3m': 3, '5m': 5, '15m': 15, '30m': 30, '1h': 60, '2h': 120,
+    '4h': 240, '8h': 480, '12h': 720, '1d': 1440, '3d': 4320, '1w': 10080 }[interval]
+  return minutes ? row.t + minutes * 60_000 - 1 : row.t
+}
+
+export function computeIndicators(candles, { now = Date.now(), interval } = {}) {
+  const valid = (candles ?? []).map((c) => ({ t: Number(c.t), T: c.T, o: Number(c.o), h: Number(c.h), l: Number(c.l), c: Number(c.c), v: Number(c.v) }))
+    .filter((c) => [c.t, c.o, c.h, c.l, c.c, c.v].every(Number.isFinite) && c.t > 0 && c.h >= c.l && c.c > 0)
+    .sort((a, b) => a.t - b.t)
+  const unique = [...new Map(valid.map((row) => [row.t, row])).values()]
+  const rows = unique.filter((row) => closeTime(row, interval) < now)
+  const excludedOpen = unique.length - rows.length
+  if (rows.length < 50) return { ready: false, candlesUsed: rows.length, excludedOpen, reason: '至少需要 50 根已收盘的有效 K 线' }
+  const close = rows.map((c) => c.c)
+  const volume = rows.map((c) => c.v)
+  const ema12 = emaSeries(close, 12)
+  const ema26 = emaSeries(close, 26)
+  const macdLine = ema12.slice(14).map((value, i) => value - ema26[i])
+  const signal = emaSeries(macdLine, 9)
+  const deltas = close.slice(1).map((value, i) => value - close[i])
+  const avgGain = wilder(deltas.map((value) => Math.max(value, 0)), 14)
+  const avgLoss = wilder(deltas.map((value) => Math.max(-value, 0)), 14)
+  const rsi = avgLoss === 0 ? (avgGain === 0 ? 50 : 100) : 100 - 100 / (1 + avgGain / avgLoss)
+  const trueRanges = rows.slice(1).map((c, i) => Math.max(c.h - c.l, Math.abs(c.h - rows[i].c), Math.abs(c.l - rows[i].c)))
+  const atr14 = wilder(trueRanges, 14)
+  const close20 = close.slice(-20)
+  const mean20 = sma(close, 20)
+  const deviation = Math.sqrt(close20.reduce((sum, value) => sum + (value - mean20) ** 2, 0) / 20)
+  const latest = rows.at(-1)
+  const recent = rows.slice(-100)
+  const supportFallback = rows.slice(-20).reduce((best, row) => row.l < best.l ? row : best)
+  const resistanceFallback = rows.slice(-20).reduce((best, row) => row.h > best.h ? row : best)
+  const support = swings(recent, 'low').filter((point) => point.price < latest.c).sort((a, b) => b.price - a.price)[0]
+    ?? { price: supportFallback.l, time: supportFallback.t }
+  const resistance = swings(recent, 'high').filter((point) => point.price > latest.c).sort((a, b) => a.price - b.price)[0]
+    ?? { price: resistanceFallback.h, time: resistanceFallback.t }
+  return {
+    ready: true, candlesUsed: rows.length, excludedOpen, observedAt: closeTime(latest, interval), candleOpenedAt: latest.t, close: latest.c,
+    sma20: mean20, ema20: emaSeries(close, 20).at(-1), ema50: emaSeries(close, 50).at(-1),
+    rsi14: rsi, macd: { line: macdLine.at(-1), signal: signal.at(-1), histogram: macdLine.at(-1) - signal.at(-1) },
+    bollinger20: { lower: mean20 - 2 * deviation, middle: mean20, upper: mean20 + 2 * deviation },
+    atr14, volumeRatio20: latest.v / (sma(volume.slice(0, -1), 20) || 1),
+    support, resistance,
+  }
+}

package/lib/market-symbol.js

@@ -0,0 +1,5 @@
+/** Known legacy/display names that are not valid Hyperliquid API coin names. */
+export function canonicalMarketCoin(value) {
+  const coin = String(value ?? '').trim()
+  return coin === 'xyz:100' || coin === 'XYZ100' ? 'xyz:XYZ100' : coin
+}