Aicoin Hyperliquid

#!/usr/bin/env node
// AiCoin API client with HMAC signing - shared lib
import { createHmac, randomBytes } from 'node:crypto';
import { readFileSync, existsSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, resolve } from 'node:path';

// Auto-load .env files (OpenClaw exec may not inject env vars into child processes)
function loadEnv() {
  const candidates = [
    resolve(process.cwd(), '.env'),                           // workspace root
    resolve(process.env.HOME || '', '.openclaw', 'workspace', '.env'), // OpenClaw workspace
    resolve(process.env.HOME || '', '.openclaw', '.env'),     // OpenClaw global
  ];
  for (const file of candidates) {
    if (!existsSync(file)) continue;
    try {
      const lines = readFileSync(file, 'utf-8').split('\n');
      for (const line of lines) {
        const trimmed = line.trim();
        if (!trimmed || trimmed.startsWith('#')) continue;
        const eq = trimmed.indexOf('=');
        if (eq < 1) continue;
        const key = trimmed.slice(0, eq).trim();
        let val = trimmed.slice(eq + 1).trim();
        // Strip surrounding quotes
        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
          val = val.slice(1, -1);
        }
        // Only set if not already defined (env vars take precedence)
        if (!process.env[key]) process.env[key] = val;
      }
    } catch { /* ignore unreadable files */ }
  }
}
loadEnv();

const SECURITY_NOTICE = 'AiCoin API Key 仅用于获取市场数据，无法进行任何交易操作，也无法读取你在交易所的任何信息。交易所 API Key 需单独到交易所申请。所有密钥仅保存在你的本地设备 .env 文件中，不会上传到任何服务器。';

const __dirname = dirname(fileURLToPath(import.meta.url));
const defaults = JSON.parse(readFileSync(resolve(__dirname, 'defaults.json'), 'utf-8'));

const BASE = process.env.AICOIN_BASE_URL || 'https://open.aicoin.com';
const KEY = process.env.AICOIN_ACCESS_KEY_ID || defaults.accessKeyId;
const SECRET = process.env.AICOIN_ACCESS_SECRET || defaults.accessSecret;

function sign() {
  const nonce = randomBytes(4).toString('hex');
  const ts = Math.floor(Date.now() / 1000).toString();
  const str = `AccessKeyId=${KEY}&SignatureNonce=${nonce}&Timestamp=${ts}`;
  const hex = createHmac('sha1', SECRET).update(str).digest('hex');
  const sig = Buffer.from(hex, 'binary').toString('base64');
  return { AccessKeyId: KEY, SignatureNonce: nonce, Timestamp: ts, Signature: sig };
}

// 标记后端 / 网关上游故障，给 agent 明确文本提示去引导用户联系客服，
// 避免 agent 把临时上游故障描述为"你的参数错"。
function upstreamFaultHint(status, path) {
  if (status >= 500 && status < 600) {
    if (status === 502 || status === 503 || status === 504) {
      return `\n【AiCoin 网关临时故障 HTTP ${status}】端点 ${path}。建议: 等 1-2 分钟后重试；如仍失败，请告知用户"AiCoin 接口暂时不可用，请联系 AiCoin 客服 (service@aicoin.com / 官网在线客服) 反馈，并附上请求时间和端点"。不要把该错误描述为用户参数问题。`;
    }
    return `\n【AiCoin 后端异常 HTTP ${status}】端点 ${path}。该接口当前不可用，**不是用户参数错**。请明确告诉用户："这是 AiCoin 后端接口故障，agent 无法解决；请联系 AiCoin 客服 (service@aicoin.com) 反馈，附上请求时间和端点名"。不要重试同一参数。`;
  }
  return '';
}

export async function apiGet(path, params = {}) {
  const qs = new URLSearchParams({ ...params, ...sign() });
  const res = await fetch(`${BASE}${path}?${qs}`, { signal: AbortSignal.timeout(30000) });
  if (!res.ok) {
    const text = await res.text();
    let hint = '';
    if (res.status === 403) {
      hint = '\n【付费功能】请勿重试。请告知用户：此功能需要付费订阅。升级链接：https://www.aicoin.com/opendata ，套餐：基础版 $29/月起。配置方法：将 AICOIN_ACCESS_KEY_ID 和 AICOIN_ACCESS_SECRET 添加到 .env 文件。安全提示：AiCoin API Key 仅用于获取市场数据，无法交易，密钥仅保存在本地。';
    } else if (res.status === 400) {
      if (text.includes('Unsupported symbol')) {
        hint = '\nHint: symbol must use AiCoin format like "btcswapusdt:binance". Short names (BTC, ETH, SOL) are auto-resolved by coin.mjs.';
      } else if (text.includes('invalid parameters')) {
        hint = '\nHint: Check SKILL.md for the correct parameter format and required fields.';
      }
    } else if (res.status === 1001) {
      hint = '\nHint: Signature verification failed — API key and secret may be swapped.';
    } else if (res.status >= 500) {
      hint = upstreamFaultHint(res.status, path);
    }
    throw new Error(`API ${res.status}: ${text}${hint}`);
  }
  const json = await res.json();
  // AiCoin reuses errorCode 304 for both "paid feature required" and parameter
  // errors like "无效的交易对". Only attach the upgrade prompt when the error
  // text actually looks like a permission gate — otherwise wrong symbols get
  // misreported to the user as a tier issue and the model wastes tokens
  // recommending an upgrade the user doesn't need.
  if (json.success === false && (json.errorCode === 304 || json.errorCode === 403)) {
    const errText = String(json.error || json.message || '');
    const isParamError = /无效|不存在|不支持|参数|invalid|unsupported|missing/i.test(errText);
    if (!isParamError) {
      json.付费功能提示 = '此功能需要付费订阅，请勿重试。请告知用户：升级地址 https://www.aicoin.com/opendata ，套餐从基础版 $29/月起。必须在回复中包含此链接。';
      json.升级指南 = {
        说明: '此数据需要 AiCoin 付费会员才能访问',
        升级链接: 'https://www.aicoin.com/opendata',
        步骤: [
          '1. 打开 https://www.aicoin.com/opendata 注册/登录',
          '2. 选择合适的套餐（基础版 $29/月 起）',
          '3. 创建 API Key，获取 Key ID 和 Secret',
          '4. 添加到 .env 文件：AICOIN_ACCESS_KEY_ID=xxx 和 AICOIN_ACCESS_SECRET=xxx',
          '5. 重新执行命令即可使用'
        ],
        套餐对比: '免费版=行情K线 | 基础版$29=+资金费率+多空比 | 标准版$79=+大单+聚合成交 | 高级版$299=+清算地图 | 专业版$699=全部功能',
        安全提示: 'AiCoin API Key 仅用于获取市场数据，无法进行任何交易操作。所有密钥仅保存在本地设备，不会上传到任何服务器。'
      };
    } else {
      json.参数错误提示 = `调用失败：${errText}。请检查 symbol / 参数格式（例如 "btcswapusdt:binance"），不要重试同一个错误参数，也不要将其当作付费功能问题向用户报错。`;
    }
  }
  return json;
}

// Validate a key pair by making a test API call
export async function validateKey(keyId, secret) {
  const nonce = randomBytes(4).toString('hex');
  const ts = Math.floor(Date.now() / 1000).toString();
  const str = `AccessKeyId=${keyId}&SignatureNonce=${nonce}&Timestamp=${ts}`;
  const hex = createHmac('sha1', secret).update(str).digest('hex');
  const sig = Buffer.from(hex, 'binary').toString('base64');
  const qs = new URLSearchParams({ coin_list: 'bitcoin', AccessKeyId: keyId, SignatureNonce: nonce, Timestamp: ts, Signature: sig });
  try {
    const res = await fetch(`${BASE}/api/v2/coin/ticker?${qs}`, { signal: AbortSignal.timeout(10000) });
    if (!res.ok) return { valid: false, error: `HTTP ${res.status}` };
    const json = await res.json();
    return (json.code === '0' || json.success !== false) ? { valid: true } : { valid: false, error: json.msg || 'invalid key' };
  } catch (e) { return { valid: false, error: e.message }; }
}

export async function apiPost(path, body = {}) {
  const res = await fetch(`${BASE}${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ...body, ...sign() }),
    signal: AbortSignal.timeout(30000),
  });
  if (!res.ok) {
    const text = await res.text();
    const hint = res.status >= 500 ? upstreamFaultHint(res.status, path) : '';
    throw new Error(`API ${res.status}: ${text}${hint}`);
  }
  const json = await res.json();
  // 与 apiGet 对齐：success=false 且 errorCode 304/403 时识别付费 vs 参数错
  if (json.success === false && (json.errorCode === 304 || json.errorCode === 403)) {
    const errText = String(json.error || json.message || '');
    const isParamError = /无效|不存在|不支持|参数|invalid|unsupported|missing/i.test(errText);
    if (!isParamError) {
      json.付费功能提示 = '此功能需要付费订阅，请勿重试。升级地址 https://www.aicoin.com/opendata';
    } else {
      json.参数错误提示 = `调用失败：${errText}。请检查参数格式，不要重试同一个错误参数。`;
    }
  }
  return json;
}

// CLI helper: parse args and run
export function cli(handlers) {
  const [action, ...rest] = process.argv.slice(2);
  if (!action || !handlers[action]) {
    const available = Object.keys(handlers).join(', ');
    console.log(JSON.stringify({
      error: action ? `Unknown action "${action}"` : 'No action specified',
      available_actions: available,
      usage: 'node <script> <action> [json-params]',
    }));
    process.exit(1);
  }
  let params = {};
  if (rest.length) {
    const raw = rest.join(' ');
    try {
      params = JSON.parse(raw);
    } catch {
      console.log(JSON.stringify({
        error: `Invalid JSON parameter: ${raw}`,
        hint: 'Parameters must be a JSON object, e.g.: \'{"symbol":"BTC","interval":"1h"}\'',
        example: `node <script> ${action} '{"key":"value"}'`,
      }));
      process.exit(1);
    }
  }
  handlers[action](params).then(r => console.log(JSON.stringify(r, null, 2))).catch(e => {
    console.error(e.message);
    process.exit(1);
  });
}

{
  "comment": "Public free-tier AiCoin API key. IP rate-limited. Users can replace with their own key via env vars.",
  "accessKeyId": "ronJ8uI0Yj2soAfGVs5H1YALUIINbE22",
  "accessSecret": "CWHZcH2us1CLSE7grroR1TpS0Z1JxTwU"
}

{
  "name": "aicoin-hyperliquid",
  "version": "3.2.4",
  "private": true,
  "type": "module"
}

#!/usr/bin/env node
// Hyperliquid Data CLI - Part 1: ticker, whale, liquidation, OI, taker
import { apiGet, apiPost, cli } from '../lib/aicoin-api.mjs';

cli({
  tickers: () => apiGet('/api/upgrade/v2/hl/tickers'),
  ticker: ({ coin }) => apiGet(`/api/upgrade/v2/hl/tickers/coin/${coin}`),
  whale_positions: ({ coin, dir, npnlSide, frSide, topBy, take } = {}) => {
    const p = {};
    if (coin) p.coin = coin; if (dir) p.dir = dir;
    if (npnlSide) p.npnlSide = npnlSide; if (frSide) p.frSide = frSide;
    if (topBy) p.topBy = topBy; if (take) p.take = take;
    return apiGet('/api/upgrade/v2/hl/whales/open-positions', p);
  },
  whale_events: async ({ coin, limit } = {}) => {
    const p = {}; if (coin) p.coin = coin; if (limit) p.limit = limit;
    const json = await apiGet('/api/upgrade/v2/hl/whales/latest-events', p);
    // 实测: 上游 coin 参数过滤不严, 传 BTC 仍可能混入 SOL/其他币的鲸鱼事件。
    // 本地按 coin 严格过滤一次, 保证 agent 拿到的就是请求的币种。
    if (coin && Array.isArray(json?.data)) {
      const before = json.data.length;
      json.data = json.data.filter(ev => String(ev?.coin || '').toUpperCase() === String(coin).toUpperCase());
      if (json.data.length !== before) {
        json._note = `whale_events 上游 coin 参数过滤不严, 本地已剔除 ${before - json.data.length} 条非 ${coin} 事件 (原返 ${before} 条 → 过滤后 ${json.data.length} 条)。`;
      }
    }
    return json;
  },
  whale_directions: ({ coin } = {}) => {
    const p = {}; if (coin) p.coin = coin;
    return apiGet('/api/upgrade/v2/hl/whales/directions', p);
  },
  whale_history_ratio: ({ interval, limit } = {}) => {
    const p = {}; if (interval) p.interval = interval; if (limit) p.limit = limit;
    return apiGet('/api/upgrade/v2/hl/whales/history-long-ratio', p);
  },
  liq_history: ({ coin, interval, limit } = {}) => {
    const p = {}; if (coin) p.coin = coin; if (interval) p.interval = interval; if (limit) p.limit = limit;
    return apiGet('/api/upgrade/v2/hl/liquidations/history', p);
  },
  liq_stats: ({ coin, interval } = {}) => {
    const p = {}; if (coin) p.coin = coin; if (interval) p.interval = interval;
    return apiGet('/api/upgrade/v2/hl/liquidations/stat', p);
  },
  liq_stats_by_coin: ({ interval } = {}) => {
    const p = {}; if (interval) p.interval = interval;
    return apiGet('/api/upgrade/v2/hl/liquidations/stat-by-coin', p);
  },
  liq_top_positions: ({ coin, interval, limit } = {}) => {
    // 实测: interval 必填, 不传 400。默认 1h (滚动窗口分析最常用粒度)。
    const p = { coin, interval: interval || '1h' }; if (limit) p.limit = limit;
    return apiGet('/api/upgrade/v2/hl/liquidations/top-positions', p);
  },
  oi_summary: () => apiGet('/api/upgrade/v2/hl/open-interest/summary'),
  oi_top_coins: ({ limit, interval } = {}) => {
    const p = {}; if (limit) p.limit = limit; if (interval) p.interval = interval;
    return apiGet('/api/upgrade/v2/hl/open-interest/top-coins', p);
  },
  oi_history: ({ coin, interval }) => {
    const p = {}; if (interval) p.interval = interval;
    return apiGet(`/api/upgrade/v2/hl/open-interest/history/${coin}`, p);
  },
  taker_delta: ({ coin, interval } = {}) => {
    // 实测: interval 必填。默认 1h (跟 taker_klines/liq_top_positions 对齐)。
    const p = { interval: interval || '1h' };
    return apiGet(`/api/upgrade/v2/hl/accumulated-taker-delta/${coin}`, p);
  },
  taker_klines: ({ coin, interval = '4h', startTime, endTime, limit } = {}) => {
    const p = {}; if (startTime) p.startTime = startTime; if (endTime) p.endTime = endTime; if (limit) p.limit = limit;
    return apiGet(`/api/upgrade/v2/hl/klines-with-taker-vol/${coin}/${interval}`, p);
  },
  orderbook_history: ({ coin, interval } = {}) => {
    const p = {}; if (interval) p.interval = interval;
    return apiGet(`/api/upgrade/v2/hl/orderbooks/history-summaries/${coin}`, p);
  },
});

#!/usr/bin/env node
// Hyperliquid Trader Analytics CLI
import { apiGet, apiPost, cli } from '../lib/aicoin-api.mjs';

// portfolio window 实测仅支持这 4 个值,其他 (perpAllTime, allTimePerp 等) 一律 400
const PORTFOLIO_WINDOWS = new Set(['day', 'week', 'month', 'allTime']);

// 单地址必填校验, 避免 URL 拼出 `traders/undefined/...` 然后上游 404
function requireAddress(address) {
  if (!address) {
    return {
      success: false,
      errorCode: 400,
      error: 'address 必填 (HL 钱包地址, 例 0x...)。先用 smart_find 拿聪明钱列表, 或让用户提供。',
    };
  }
  return null;
}

// HL 后端的 completed_* 端点对 "未知 positionId" 是塞到 HTTP 200 的 body
// {code:"400", msg:"position not found"} 里返,不走 throw 分支。统一把这种
// 业务错误包成 实测结论 提示, 引导 agent 改用替代端点。
// fallback 是替代调用建议文字。
function wrapPositionNotFound(json, fallback) {
  if (!json || typeof json !== 'object') return json;
  const code = String(json.code || '');
  const msg = String(json.msg || '');
  // code 非 "0" 或非 0 都视为业务错; 同时 msg 含 position not found 才走包装路径
  if (code !== '0' && code !== '' && /position not found/i.test(msg)) {
    return {
      success: false,
      errorCode: 400,
      error: msg,
      实测结论: `该端点按 positionId 取数, 不接受 address+coin 组合。agent 拿不到 positionId 用不了。${fallback}`,
      _raw: json,
    };
  }
  return json;
}

cli({
  // hl_trader — period 实测必填且没默认, 不传 400。这里给 "30" (30 天) 兜底。
  trader_stats: ({ address, period }) => {
    const err = requireAddress(address); if (err) return Promise.resolve(err);
    const p = { period: period || '30' };
    return apiGet(`/api/upgrade/v2/hl/traders/${address}/addr-stat`, p);
  },
  best_trades: ({ address, period, limit }) => {
    const err = requireAddress(address); if (err) return Promise.resolve(err);
    const p = { period: period || '30' }; if (limit) p.limit = limit;
    return apiGet(`/api/upgrade/v2/hl/traders/${address}/best-trades`, p);
  },
  performance: ({ address, period, limit }) => {
    const err = requireAddress(address); if (err) return Promise.resolve(err);
    const p = { period: period || '30' }; if (limit) p.limit = limit;
    return apiGet(`/api/upgrade/v2/hl/traders/${address}/performance-by-coin`, p);
  },
  completed_trades: async ({ address, coin, limit } = {}) => {
    const err = requireAddress(address); if (err) return err;
    const p = {}; if (coin) p.coin = coin; if (limit) p.limit = limit;
    const json = await apiGet(`/api/upgrade/v2/hl/traders/${address}/completed-trades`, p);
    if (json && Array.isArray(json.data) && json.data.length === 0) {
      json._note = `completed_trades 该地址${coin ? ` ${coin}` : ''} 近期无已平仓交易。换 coin 或不传 coin 看全部历史; 想看活跃币种用 performance (per-coin 业绩)。`;
    }
    return json;
  },
  accounts: async ({ addresses }) => {
    let addrs = addresses;
    if (typeof addrs === 'string') { try { addrs = JSON.parse(addrs); } catch { addrs = [addrs]; } }
    try {
      return await apiPost('/api/upgrade/v2/hl/traders/accounts', { addresses: addrs });
    } catch (e) {
      // 实测: 即使 addresses 格式正确, 后端也偶发 500。statistics 同输入正常。
      if (/^API 5\d\d/.test(e.message)) {
        return {
          success: false,
          errorCode: 500,
          error: e.message,
          实测结论: 'hl/traders/accounts 端点后端不稳, 实测 500 但同样的 addresses 调 statistics 正常。请改用 statistics + batch_clearinghouse_state 拿同样数据, 或告知用户"该接口后端故障, 联系 AiCoin 客服 (service@aicoin.com) 报修"。',
        };
      }
      throw e;
    }
  },
  statistics: ({ addresses }) => {
    let addrs = addresses;
    if (typeof addrs === 'string') { try { addrs = JSON.parse(addrs); } catch { addrs = [addrs]; } }
    return apiPost('/api/upgrade/v2/hl/traders/statistics', { addresses: addrs });
  },
  // hl_fills
  fills: ({ address, coin, limit } = {}) => {
    const err = requireAddress(address); if (err) return Promise.resolve(err);
    const p = {}; if (coin) p.coin = coin; if (limit) p.limit = limit;
    return apiGet(`/api/upgrade/v2/hl/fills/${address}`, p);
  },
  fills_by_oid: ({ oid }) => apiGet(`/api/upgrade/v2/hl/fills/oid/${oid}`),
  fills_by_twapid: ({ twapid }) => apiGet(`/api/upgrade/v2/hl/fills/twapid/${twapid}`),
  top_trades: ({ coin, interval, limit } = {}) => {
    // 实测: interval 必填, 默认 1h
    const p = { coin, interval: interval || '1h' }; if (limit) p.limit = limit;
    return apiGet('/api/upgrade/v2/hl/fills/top-trades', p);
  },
  // hl_orders
  orders_latest: ({ address, coin, limit } = {}) => {
    const err = requireAddress(address); if (err) return Promise.resolve(err);
    const p = {}; if (coin) p.coin = coin; if (limit) p.limit = limit;
    return apiGet(`/api/upgrade/v2/hl/orders/${address}/latest`, p);
  },
  order_by_oid: ({ oid }) => apiGet(`/api/upgrade/v2/hl/orders/oid/${oid}`),
  filled_orders: ({ address, coin, limit } = {}) => {
    const err = requireAddress(address); if (err) return Promise.resolve(err);
    const p = {}; if (coin) p.coin = coin; if (limit) p.limit = limit;
    return apiGet(`/api/upgrade/v2/hl/filled-orders/${address}/latest`, p);
  },
  filled_by_oid: ({ oid }) => apiGet(`/api/upgrade/v2/hl/filled-orders/oid/${oid}`),
  top_open: ({ coin, minVal, min_val, limit }) => {
    const p = {}; if (coin) p.coin = coin; if (minVal || min_val) p.minVal = minVal || min_val; if (limit) p.limit = limit;
    return apiGet('/api/upgrade/v2/hl/orders/top-open-orders', p);
  },
  active_stats: ({ coin, whaleThreshold, whale_threshold }) => {
    const p = {}; if (coin) p.coin = coin; if (whaleThreshold || whale_threshold) p.whaleThreshold = whaleThreshold || whale_threshold;
    return apiGet('/api/upgrade/v2/hl/orders/active-stats', p);
  },
  twap_states: async ({ address, coin, limit } = {}) => {
    const err = requireAddress(address); if (err) return err;
    const p = {}; if (coin) p.coin = coin; if (limit) p.limit = limit;
    const json = await apiGet(`/api/upgrade/v2/hl/twap-states/${address}/latest`, p);
    if (json && Array.isArray(json.data) && json.data.length === 0) {
      json._note = `twap_states 该地址当前无 TWAP 委托 (空属正常 — TWAP 是 HL 的时间加权拆单, 大多数地址不用)。常态返空, 不是接口故障。`;
    }
    return json;
  },
  // hl_position
  current_pos_history: async ({ address, coin } = {}) => {
    const err = requireAddress(address); if (err) return err;
    if (!coin) {
      return {
        success: false, errorCode: 400,
        error: 'current_pos_history 必填 coin (例: BTC / ETH / cash:TSLA)',
        参数提示: '缺 coin 会拼出 /undefined URL 上游返 null 误导, 现已本地拦截。',
      };
    }
    const json = await apiGet(`/api/upgrade/v2/hl/traders/${address}/current-position-history/${coin}`);
    if (json && (json.data === null || (Array.isArray(json.data) && json.data.length === 0))) {
      json._note = `current_pos_history 该地址 ${coin} 当前无持仓 (data 空)。先用 fills (按地址列实际活跃币种) 或 performance 确认地址主攻哪些币。`;
    }
    return json;
  },
  completed_pos_history: async ({ address, coin, startTime, endTime } = {}) => {
    const err = requireAddress(address); if (err) return err;
    if (!startTime && !endTime) {
      return {
        success: false, errorCode: 400,
        error: 'completed_pos_history 必填 startTime 或 endTime 之一 (ms epoch)',
        参数提示: '换用 completed_trades (按地址列已平仓交易无需时间窗)。',
      };
    }
    const p = {}; if (startTime) p.startTime = startTime; if (endTime) p.endTime = endTime;
    const json = await apiGet(`/api/upgrade/v2/hl/traders/${address}/completed-position-history/${coin}`, p);
    return wrapPositionNotFound(json, '改用 completed_trades (按地址列已平仓交易) 或 fills (按地址列所有成交) 拿历史。');
  },
  current_pnl: async ({ address, coin, interval, limit } = {}) => {
    const err = requireAddress(address); if (err) return err;
    if (!coin) {
      return {
        success: false, errorCode: 400,
        error: 'current_pnl 必填 coin (例: BTC / ETH / cash:TSLA)',
        参数提示: '缺 coin 会拼出 /undefined URL 上游返 null 误导, 现已本地拦截。',
      };
    }
    // 实测: interval 必填 (返 missing interval), 默认 1h
    const p = { interval: interval || '1h' }; if (limit) p.limit = limit;
    const json = await apiGet(`/api/upgrade/v2/hl/traders/${address}/current-position-pnl/${coin}`, p);
    if (json && (json.data === null || (Array.isArray(json.data) && json.data.length === 0))) {
      json._note = `current_pnl 该地址 ${coin} 当前无持仓 (data 空)。先用 fills (按地址列实际活跃币种) 或 performance (per-coin 业绩) 确认地址主攻哪些币。`;
    }
    return json;
  },
  completed_pnl: async ({ address, coin, interval, startTime, endTime, limit } = {}) => {
    const err = requireAddress(address); if (err) return err;
    // 实测: 除 interval, 还必须传 startTime 或 endTime 之一 (ms epoch). agent 应该自己算时间窗。
    if (!startTime && !endTime) {
      return {
        success: false,
        errorCode: 400,
        error: 'completed_pnl 必填 startTime 或 endTime 之一 (ms epoch)',
        参数提示: '例: startTime=Date.now()-30*86400*1000 取过去 30 天。或换用 pnls (全地址 PnL 曲线无需时间窗)。',
      };
    }
    const p = { interval: interval || '1h' }; if (startTime) p.startTime = startTime; if (endTime) p.endTime = endTime; if (limit) p.limit = limit;
    const json = await apiGet(`/api/upgrade/v2/hl/traders/${address}/completed-position-pnl/${coin}`, p);
    return wrapPositionNotFound(json, '改用 pnls (整地址 PnL 曲线) 或 best_trades (按地址盈利交易)。');
  },
  current_executions: async ({ address, coin, interval, limit } = {}) => {
    const err = requireAddress(address); if (err) return err;
    if (!coin) {
      return {
        success: false, errorCode: 400,
        error: 'current_executions 必填 coin (例: BTC / ETH / cash:TSLA)',
        参数提示: '缺 coin 会拼出 /undefined URL 上游返 null 误导, 现已本地拦截。',
      };
    }
    const p = { interval: interval || '1h' }; if (limit) p.limit = limit;
    const json = await apiGet(`/api/upgrade/v2/hl/traders/${address}/current-position-executions/${coin}`, p);
    if (json && (json.data === null || (Array.isArray(json.data) && json.data.length === 0))) {
      json._note = `current_executions 该地址 ${coin} 当前无持仓 (data 空)。先用 fills (按地址列实际活跃币种) 或 performance 确认地址主攻哪些币。`;
    }
    return json;
  },
  completed_executions: async ({ address, coin, interval, startTime, endTime, limit } = {}) => {
    const err = requireAddress(address); if (err) return err;
    if (!startTime && !endTime) {
      return {
        success: false, errorCode: 400,
        error: 'completed_executions 必填 startTime 或 endTime 之一 (ms epoch)',
        参数提示: '换用 fills (按地址全量成交无需时间窗)。',
      };
    }
    const p = { interval: interval || '1h' }; if (startTime) p.startTime = startTime; if (endTime) p.endTime = endTime; if (limit) p.limit = limit;
    const json = await apiGet(`/api/upgrade/v2/hl/traders/${address}/completed-position-executions/${coin}`, p);
    return wrapPositionNotFound(json, '改用 fills (按地址列所有成交)。');
  },
  // hl_portfolio — window 仅 day/week/month/allTime, 其他值上游 400。校验后再调。
  portfolio: ({ address, window }) => {
    const err = requireAddress(address); if (err) return Promise.resolve(err);
    const w = window || 'day';
    if (!PORTFOLIO_WINDOWS.has(w)) {
      return Promise.resolve({
        success: false,
        errorCode: 400,
        error: `portfolio window 仅接受 day / week / month / allTime, 收到 "${w}"`,
        参数错误提示: '请改用合法 window 值, 不要尝试 perpAllTime / allTimePerp 这类组合。',
      });
    }
    return apiGet(`/api/upgrade/v2/hl/portfolio/${address}/${w}`);
  },
  pnls: ({ address, period } = {}) => {
    const err = requireAddress(address); if (err) return Promise.resolve(err);
    const p = { period: period || '30' };
    return apiGet(`/api/upgrade/v2/hl/pnls/${address}`, p);
  },
  // max_drawdown / net_flow — days 实测必填, 默认 30
  max_drawdown: ({ address, days, scope = 'perp' } = {}) => {
    const err = requireAddress(address); if (err) return Promise.resolve(err);
    return apiGet(`/api/upgrade/v2/hl/max-drawdown/${address}`, { days: days || '30', scope });
  },
  net_flow: ({ address, days } = {}) => {
    const err = requireAddress(address); if (err) return Promise.resolve(err);
    return apiGet(`/api/upgrade/v2/hl/ledger-updates/net-flow/${address}`, { days: days || '30' });
  },
  // hl_advanced
  info: ({ type, user, extra_params }) => {
    const body = { type }; if (user) body.user = user;
    if (extra_params) {
      try { Object.assign(body, typeof extra_params === 'string' ? JSON.parse(extra_params) : extra_params); } catch {}
    }
    return apiPost('/api/upgrade/v2/hl/info', body);
  },
  smart_find: (params) => apiPost('/api/upgrade/v2/hl/smart/find', params || {}),
  discover: (params) => apiPost('/api/upgrade/v2/hl/traders/discover', params || {}),
  discover_history: (params) => apiPost('/api/upgrade/v2/hl/traders/discover-history', params || {}),
  // batch endpoints
  fills_by_builder: ({ builder, coin, limit, minVal } = {}) => {
    const p = {}; if (coin) p.coin = coin; if (limit) p.limit = limit; if (minVal) p.minVal = minVal;
    return apiGet(`/api/upgrade/v2/hl/fills/builder/${builder}/latest`, p);
  },
  batch_pnls: ({ addresses, period, scope }) => {
    let addrs = addresses;
    if (typeof addrs === 'string') { try { addrs = JSON.parse(addrs); } catch { addrs = [addrs]; } }
    const body = { addresses: addrs }; if (period != null) body.period = period; if (scope) body.scope = scope;
    return apiPost('/api/upgrade/v2/hl/batch-pnls', body);
  },
  batch_addr_stat: ({ addresses, period }) => {
    let addrs = addresses;
    if (typeof addrs === 'string') { try { addrs = JSON.parse(addrs); } catch { addrs = [addrs]; } }
    const body = { addresses: addrs }; if (period != null) body.period = period;
    return apiPost('/api/upgrade/v2/hl/traders/batch-addr-stat', body);
  },
  // 注意: 上游 body 字段是大写 Coin (不是 coin)。 agent 容易传小写, 静默拿到全币种杂烩。
  // 这里兼容两种大小写, 不让 silent wrong 发生。
  completed_trades_by_time: async ({ address, pageNum, pageSize, Coin, coin, endTimeFrom, endTimeTo } = {}) => {
    const err = requireAddress(address); if (err) return err;
    const body = {};
    if (pageNum) body.pageNum = pageNum; if (pageSize) body.pageSize = pageSize;
    const coinValue = Coin || coin;
    if (coinValue) body.Coin = coinValue;
    if (endTimeFrom) body.endTimeFrom = endTimeFrom; if (endTimeTo) body.endTimeTo = endTimeTo;
    const json = await apiPost(`/api/upgrade/v2/hl/traders/${address}/completed-trades/by-time`, body);
    if (json && Array.isArray(json.data) && json.data.length === 0) {
      json._note = `completed_trades_by_time 时间窗 [${endTimeFrom || '?'}, ${endTimeTo || '?'}] 内该地址${coinValue ? ` ${coinValue}` : ''} 无已平仓交易。 扩大时间窗 (ms epoch), 或用 completed_trades 不限时间。`;
    }
    return json;
  },
  batch_clearinghouse_state: ({ addresses, dex }) => {
    let addrs = addresses;
    if (typeof addrs === 'string') { try { addrs = JSON.parse(addrs); } catch { addrs = [addrs]; } }
    const body = { addresses: addrs }; if (dex) body.dex = dex;
    return apiPost('/api/upgrade/v2/hl/traders/clearinghouse-state', body);
  },
  batch_spot_clearinghouse_state: ({ addresses }) => {
    let addrs = addresses;
    if (typeof addrs === 'string') { try { addrs = JSON.parse(addrs); } catch { addrs = [addrs]; } }
    return apiPost('/api/upgrade/v2/hl/traders/spot-clearinghouse-state', { addresses: addrs });
  },
  batch_max_drawdown: ({ addresses, days, scope }) => {
    let addrs = addresses;
    if (typeof addrs === 'string') { try { addrs = JSON.parse(addrs); } catch { addrs = [addrs]; } }
    const body = { addresses: addrs }; if (days != null) body.days = days; if (scope) body.scope = scope;
    return apiPost('/api/upgrade/v2/hl/batch-max-drawdown', body);
  },
  batch_net_flow: ({ addresses, days }) => {
    let addrs = addresses;
    if (typeof addrs === 'string') { try { addrs = JSON.parse(addrs); } catch { addrs = [addrs]; } }
    const body = { addresses: addrs }; if (days != null) body.days = days;
    return apiPost('/api/upgrade/v2/hl/ledger-updates/batch-net-flow', body);
  },
});