# Octav 核对组合响应：协议资产路径、美元估值与缓存时间

整理：链小知（AI 辅助）
资料核对日期：2026-10-12
引用地址：https://lianxiaozhi.com/tools/guides/octav-portfolio-value-cache-records
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

拆解已有 Portfolio JSON 的仓位层级、单位和更新时间，防止重复累计以及把 N/A 盈亏或同步状态当作零值、实时资产证明。

## 使用工具
- [Octav Portfolio API](https://lianxiaozhi.com/tools/octav) · [官方入口](https://docs.octav.fi/api/endpoints/portfolio)

## 前置条件
- 准备已有脱敏 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；缺原响应时标为结构待核，解析失败不当作空余额。
依据：[Octav：Portfolio 字段与缓存](https://docs.octav.fi/api/endpoints/portfolio.md)
依据：[Octav：API 链覆盖等级](https://docs.octav.fi/api/reference/supported-chains.md)

## 2. 按协议、链与仓位找到资产

沿 assetByProtocols.<protocol>.chains.<chain>.protocolPositions.<POSITION>.assets[] 读取资产，不跳过仓位层。保存 protocol、chain、POSITION 和原始字段以便定位。

Token 地址字段是 contract，链标识为 chainKey，chainContract 为链与合约的组合键；native asset 使用零地址占位。按网络与合约识别资产，不能只凭 symbol 合并同名 Token。

核对结果：每条资产可还原到协议、链与仓位，未误用 contractAddress 或忽略链身份。
依据：[Octav：Portfolio 字段与缓存](https://docs.octav.fi/api/endpoints/portfolio.md)

## 3. 区分数量、估值、费用和未知盈亏

资产 balance 是数量，price 为价格，value 及协议 value 为美元价值；组合 networth 也是美元口径。fees 为原币，feesFiat 为美元，两者不得直接相加。

保留字符串精度。openPnl、closedPnl、totalCostBasis 可返回 N/A，表示数据不可用，不转成0或据此计算已经实现的收益。

核对结果：数量与美元金额分列，原币费用有网络上下文，N/A 保持未知。
依据：[Octav：Portfolio 字段与缓存](https://docs.octav.fi/api/endpoints/portfolio.md)

## 4. 对照汇总层，避免重复计值

chains 是按链的汇总，assetByProtocols 是按协议和仓位组织的明细。用它们交叉对照同一组合，不将链汇总、协议汇总和底层资产总值再次叠加到 networth。

若合计不一致，先查层级、成员、时间、缺价格或协议覆盖，保留差额。文档没有给所有场景可直接套用的借贷净额计算公式，不自己拼成精确总净值。

核对结果：比较以同一地址和快照为前提，重复展示没有重复累计，差额留有定位。
依据：[Octav：Portfolio 字段与缓存](https://docs.octav.fi/api/endpoints/portfolio.md)
依据：[Octav：API 链覆盖等级](https://docs.octav.fi/api/reference/supported-chains.md)

## 5. 核对缓存与三种时间格式

Portfolio.lastUpdated 是 epoch 毫秒；用1000换算到秒再比较请求时间。waitForSync 默认false可立即返回缓存；true在缓存超过一分钟时按文档等待同步，不能从参数推断某条记录已成功刷新。

Status 的 portfolioLastSync、transactionsLastSync 为 ISO8601，syncInProgress 描述交易同步；false不保证仓位完整。Portfolio 与交易缓存周期不同，不能借交易时间替代组合更新时刻。

核对结果：明确当前组合的更新时间与缓存条件，毫秒/ISO时间已正确对齐，缺时间保留未知。
依据：[Octav：Portfolio 字段与缓存](https://docs.octav.fi/api/endpoints/portfolio.md)
依据：[Octav：同步状态与免费额度边界](https://docs.octav.fi/api/endpoints/status.md)

## 6. 按权限、费用和网络记录缺口

401表示认证问题、402表示 credits 不足、429表示限流；标准 Portfolio 每次1 credit。已有错误记录没有资产快照，不以空结果解释成零。

API 链表按覆盖等级区分：Hyperliquid 为 Portfolio Only；平台宣称的链数量也不同于 API。记录具体链/协议缺项和缓存时点，必要时等待有权人员提供脱敏资料，不主动触发刷新或同步。

核对结果：产出单位、层级、时间与缺项清单，错误/限额和覆盖不足分开说明。
依据：[Octav：Portfolio 字段与缓存](https://docs.octav.fi/api/endpoints/portfolio.md)
依据：[Octav：API Bearer 与速率](https://docs.octav.fi/api/authentication.md)
依据：[Octav：标准 API credits 费用](https://docs.octav.fi/api/pricing.md)
依据：[Octav：API 链覆盖等级](https://docs.octav.fi/api/reference/supported-chains.md)

## 常见错误
- 使用不存在的 contractAddress，或把同名资产跨链合并。
- 汇总与明细重复计值，N/A 盈亏归零后冒充精确收益。
- 把 waitForSync=true 或 syncInProgress=false 当作全部仓位已同步证明。

## 完成检查
- 形成可追溯的组合快照核对表，包含嵌套位置、单位、缓存时间、缺项与差额。
- 本教程为文档流程，未读取任何真实地址、确认当前净值、调用 API 或扣费。

## 相关知识
- [如何核对 Meme 币？先确认链、合约地址和交易池](https://lianxiaozhi.com/learn/meme-token-identity)
- [链上指标历史数值为什么会变？](https://lianxiaozhi.com/learn/point-in-time-metrics)
- [原始、解码和整理后的链上数据有什么区别？](https://lianxiaozhi.com/learn/raw-decoded-curated-data)

## 官方依据
- [Octav：Portfolio 字段与缓存](https://docs.octav.fi/api/endpoints/portfolio.md)
- [Octav：同步状态与免费额度边界](https://docs.octav.fi/api/endpoints/status.md)
- [Octav：API Bearer 与速率](https://docs.octav.fi/api/authentication.md)
- [Octav：标准 API credits 费用](https://docs.octav.fi/api/pricing.md)
- [Octav：API 链覆盖等级](https://docs.octav.fi/api/reference/supported-chains.md)