Octav 核对组合响应：协议资产路径、美元估值与缓存时间
链小知 · 进阶 · 核验 · 依官方文档整理
拆解已有 Portfolio JSON 的仓位层级、单位和更新时间，防止重复累计以及把 N/A 盈亏或同步状态当作零值、实时资产证明。
开始前准备
- 准备已有脱敏 GET /v1/portfolio 请求及完整响应，附请求时间、addresses 对应内部标签与 HTTP 状态；移除 Bearer key。
- 可同时准备同一地址已有 /v1/status 响应；没有记录时只按文档字段制作核对表，不使用示例地址请求。
1. 确认产品、请求与响应外层
核对 endpoint 为 https://api.octav.fi/v1/portfolio，必填参数为 addresses；记录 includeImages、includeExplorerUrls 和 waitForSync 是否显式设置。
先查看已有原始 JSON：若外层为对象，核对它的 address 与 networth；若为数组，按 address 找到目标组合对象。当前方法页完整示例、TypeScript 和 JS/Python 代码采用对象，支持链页却仍以数组解构，官方资料存在冲突，不能在缺原响应时强制指定一种外层。图片或浏览器链接参数不改变覆盖保证。
检查结果：保存实际外层类型并找到目标 address；缺原响应时标为结构待核，解析失败不当作空余额。
2. 按协议、链与仓位找到资产
沿 assetByProtocols.<protocol>.chains.<chain>.protocolPositions.<POSITION>.assets[] 读取资产，不跳过仓位层。保存 protocol、chain、POSITION 和原始字段以便定位。
Token 地址字段是 contract，链标识为 chainKey，chainContract 为链与合约的组合键；native asset 使用零地址占位。按网络与合约识别资产，不能只凭 symbol 合并同名 Token。
检查结果：每条资产可还原到协议、链与仓位，未误用 contractAddress 或忽略链身份。
3. 区分数量、估值、费用和未知盈亏
资产 balance 是数量，price 为价格，value 及协议 value 为美元价值；组合 networth 也是美元口径。fees 为原币，feesFiat 为美元，两者不得直接相加。
保留字符串精度。openPnl、closedPnl、totalCostBasis 可返回 N/A，表示数据不可用，不转成0或据此计算已经实现的收益。
检查结果：数量与美元金额分列，原币费用有网络上下文，N/A 保持未知。
4. 对照汇总层，避免重复计值
chains 是按链的汇总，assetByProtocols 是按协议和仓位组织的明细。用它们交叉对照同一组合，不将链汇总、协议汇总和底层资产总值再次叠加到 networth。
若合计不一致，先查层级、成员、时间、缺价格或协议覆盖，保留差额。文档没有给所有场景可直接套用的借贷净额计算公式，不自己拼成精确总净值。
检查结果：比较以同一地址和快照为前提，重复展示没有重复累计，差额留有定位。
5. 核对缓存与三种时间格式
Portfolio.lastUpdated 是 epoch 毫秒；用1000换算到秒再比较请求时间。waitForSync 默认false可立即返回缓存；true在缓存超过一分钟时按文档等待同步，不能从参数推断某条记录已成功刷新。
Status 的 portfolioLastSync、transactionsLastSync 为 ISO8601，syncInProgress 描述交易同步；false不保证仓位完整。Portfolio 与交易缓存周期不同，不能借交易时间替代组合更新时刻。
检查结果：明确当前组合的更新时间与缓存条件，毫秒/ISO时间已正确对齐，缺时间保留未知。
6. 按权限、费用和网络记录缺口
401表示认证问题、402表示 credits 不足、429表示限流；标准 Portfolio 每次1 credit。已有错误记录没有资产快照，不以空结果解释成零。
API 链表按覆盖等级区分：Hyperliquid 为 Portfolio Only；平台宣称的链数量也不同于 API。记录具体链/协议缺项和缓存时点，必要时等待有权人员提供脱敏资料，不主动触发刷新或同步。
检查结果：产出单位、层级、时间与缺项清单，错误/限额和覆盖不足分开说明。
怎样确认完成
- 形成可追溯的组合快照核对表，包含嵌套位置、单位、缓存时间、缺项与差额。
- 本教程为文档流程，未读取任何真实地址、确认当前净值、调用 API 或扣费。
常见错误与边界
- 使用不存在的 contractAddress，或把同名资产跨链合并。
- 汇总与明细重复计值，N/A 盈亏归零后冒充精确收益。
- 把 waitForSync=true 或 syncInProgress=false 当作全部仓位已同步证明。