Hyperliquid 账户价值历史 接口： "portfolio"

接口详情

• Endpoint：POST https://api.hyperliquid.xyz/info （主网；测试网用 https://api.hyperliquid-testnet.xyz/info）
  • type：固定为 "portfolio"
  • user：要查询的账户地址（0x 开头的 hex 字符串，支持主账户或子账户）
• 响应内容（简化示例，实际包含更多字段）：
  响应是一个数组，按时间粒度分组（如 "day"、"week"、"month" 等），每个分组内包含：
  • 这些历史数据对应平台 Portfolio 页面显示的 24h/7d/30d 图表所用数据点。
  • 额外字段通常包括当前 accountValue、pnlHistory 等。

accountValueHistory：账户价值历史记录，格式为 [[时间戳毫秒, 价值字符串], ...]，例如：

[
  [
    "day",
    {
      "accountValueHistory": [
        [1741886630493, "0.0"],
        [1741895270493, "0.0"],
        // ... 更多时间点
      ],
      "pnlHistory": [
        [1741886630493, "0.0"],
        // ... PnL 历史
      ],
      "vlm": "0.0"  // 可能为 volume 或其他指标
    }
  ],
  [
    "week",
    { /* 类似结构，周级别历史 */ }
  ],
  // ... 可能还有 month 等
]

请求格式（JSON body）：

{
  "type": "portfolio",
  "user": "0x你的钱包地址"
}

说明与限制

• 该接口返回的是采样数据（通常每 15 分钟采样一次 + 存款/取款时采样），用于绘制账户价值和 PnL 图表。
• 不是 连续的 tick-by-tick 历史，而是采样点。如果需要精确的逐笔计算，需要结合 userFills、userFillsByTime（交易历史）或 clearinghouseState（当前状态）自行重建。
• clearinghouseState 类型（body: {"type": "clearinghouseState", "user": "0x..."}）返回当前 marginSummary.accountValue 等实时账户价值，但不含历史。
• 没有独立的专用 "account value history" 接口；"portfolio" 是最直接提供 accountValueHistory 的方式。
• 速率限制：Info endpoint 有权重限制，具体见官方文档。
• 官方文档：https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint （查看 "Query a user's portfolio" 部分，包含示例响应片段）。

示例使用（Python requests）

import requests

url = "https://api.hyperliquid.xyz/info"
payload = {
    "type": "portfolio",
    "user": "0x你的地址"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
print(response.json())  # 会看到 accountValueHistory 等

如果需要更细粒度或完整交易历史来推导价值变化，可补充查询 "userFillsByTime"（带 startTime/endTime）。官方 Python SDK（https://github.com/hyperliquid-dex/hyperliquid-python-sdk）也可简化调用。

这个数据是 Hyperliquid API 的 /info endpoint 中 type: "portfolio" 请求返回的典型响应结构。它是一个列表（array），每个元素是一个二元组：[时间周期标识字符串, 对应周期的对象]。

响应整体代表用户在不同时间跨度（time horizons）下的账户表现采样数据，主要用于前端 Portfolio 页面绘制账户价值（Account Value）和盈亏（PnL）曲线图。数据是采样点（通常每 15 分钟左右采样一次 + 关键事件如存款/取款/大额交易时强制采样），不是连续的逐秒或逐笔记录。

顶级结构解读

响应是一个列表，包含以下 8 个固定周期（period）：

• day：过去 24 小时（≈1 天）的数据
• week：过去 7 天的数据
• month：过去 30 天的数据
• allTime：账户创建至今的全部历史数据（从最早有记录开始）
• perpDay：过去 24 小时，仅永续合约（Perps）相关的表现（排除现货部分）
• perpWeek：过去 7 天，仅永续合约部分
• perpMonth：过去 30 天，仅永续合约部分
• perpAllTime：全部历史，仅永续合约部分

Hyperliquid 是以永续合约为主的平台，所以 perpXXX 系列通常与普通系列数值非常接近或完全相同（除非用户有显著的现货持仓）。在这个示例数据中，普通 和 perp 系列的数值完全一致，说明该账户几乎全部活动都在永续合约。

每个周期的对象结构完全相同，包含三个主要字段：

1. accountValueHistory
   类型：数组 of [时间戳毫秒 (number), 账户价值字符串 (string)]
   含义：该时间周期内账户总价值的历史采样点。
   • 账户价值（Account Value） = 账户总权益 ≈ 钱包余额（USDC 等） + 未实现盈亏（Unrealized PnL） + 已实现盈亏累计影响
   • 时间戳是 Unix 毫秒时间戳（UTC）。
   • 价值用字符串表示（避免 JS 精度问题），单位通常是 USDC（或等值美元）。
   • 示例中第一个点往往是周期起始时的值（常为 "0.0"，表示刚开始监控或无持仓），然后逐步变化。
   • 在你的数据中：
     • day/week/perpDay/perpWeek/allTime/perpAllTime 的采样点最密集（约每几分钟到十几分钟一个点）。
     • month/perpMonth 采样点较稀疏（可能每天或每几天一个点）。
2. pnlHistory
   类型：数组 of [时间戳毫秒 (number), PnL 值字符串 (string)]
   含义：该时间周期内**累计盈亏（Cumulative PnL）**的历史采样点，与 accountValueHistory 的时间戳一一对应。
   • PnL = 已实现盈亏（Realized PnL） + 未实现盈亏（Unrealized PnL）
   • 它是相对于周期起始点的累计变化（不是每个采样点的增量）。
   • 正数 = 盈利，负数 = 亏损。
   • 示例解读：
     • 从 "0.00101" → "-2.773613" → "-0.082902" → ... → "-0.274001"
       表示账户一度浮亏约 2.77 USDC，后来回撤到浮亏 0.274 USDC。
   • 与 accountValueHistory 高度相关：当前 accountValue ≈ 周期起始价值 + 当前 pnlHistory 值（简化模型，实际还受存款/取款影响）。
3. vlm
   类型：字符串
   含义：Volume（交易量），该时间周期内的总交易名义成交量（notional volume）。
   • 单位通常是 USDC（或币的本位价值 × 价格）。
   • 在 Hyperliquid 中常指所有方向（open + close + increase + reduce）的名义成交总额。
   • 示例中统一为 "670.55"，说明这个用户在所有周期内累计交易名义量都是 670.55 USDC（因为数据时间很短，整个活动就发生在这几天内）。

时间戳示例（基于当前时间 2026-02-04）

• 最新点 1770183182927 ≈ 2026-02-04 05:33:02 UTC
• 前一点 1770177240011 ≈ 几分钟前
• day 起始 ≈ 1770096782927 ≈ 2026-02-03 05:33:02 UTC（正好 24 小时前）
• week 起始 ≈ 1769578382927 ≈ 2026-01-28 左右
• month 起始 ≈ 1767591182927 ≈ 2026-01-05 左右
• allTime 起始 ≈ 1770148507059 ≈ 稍早于 day 起始

这个具体数据的整体故事（快速解读）

• 账户很新（allTime 数据只从 ≈2026-02-03 开始）。
• 起始价值 0.0 → 突然跳到 101.00101（可能是存款 ≈101 USDC）。
• 然后价格波动导致价值降到 98.226 → 回升到 100.917 → 小幅回落 → 稳定在 100.726。
• 累计 PnL 从 +0.001 → -2.77（最大浮亏）→ 回撤到 -0.274（小亏）。
• 总交易量 670.55 USDC（杠杆交易，名义量远大于实际权益）。
• month 数据点少，因为大部分历史都在最近几天。

总结表格（字段含义一览）

如果需要更精确计算（如扣除存款后的真实交易 PnL），建议结合 userFills 或 userFillsByTime 接口获取逐笔交易记录自行重建。官方文档对这些字段的描述较简略，以上基于实际响应结构和平台逻辑推导。