通过 DeFi API 查询用户投资品维度的持仓列表：完整指南与实战示例

关键词：DeFi API、持仓列表、Web3 钱包、投资品维度、数字资产、链上数据、接口文档

如果你正在开发一款多链钱包、链上资产分析平台，或多链理财看板，那么精准地查询用户投资品维度的持仓列表就是核心功能之一。借助 DeFi API，你只需要调用一个 POST 接口，即可把用户在不同公链、不同投资品里的仓位信息——无论是流动性池、质押收益还是机枪池奖励——一次拉齐，呈现成高可读性的资产详情。

下面，我们按“使用场景 → 调用方法 → 返回意义 → 实战案例 → 常见疑问”这条思路，带你一步步吃透接口。

1. 核心使用场景：谁需要接口？

为谁服务	典型需求
多链钱包 App / Web 端	让用户一键查看“我到底在哪些矿池里有仓位”
数据看板与资产分析平台	追踪用户总头寸、计算收益率、绘制资产分层饼图
DeFi Portfolio Manager	自动识别哪些仓位已挖矿但尚未领取奖励；一键赎回并复利
自动化做市机器人 / 保险协议	实时自检 LPToken、质押 LP 的位置和数量，触发再投资或对冲脚本
Tax & Accounting 工具	精准确认每日、每币、每价产生的数字资产成本 & 收入，以便报税

2. 调用接口：从准备到发送

请求 URL（POST）：
https://web3.okx.com/api/v5/defi/user/investment/asset-detail
核心参数（必须掌握 3 类）

身份定位：address（用户钱包地址，必传）
投资品定位：investmentId 与 poolId 不可同时为空
- investmentId：绝大部分协议使用
- poolId：仅在 BRC-20 投资品场景出现
辅助定位：farmInvestmentId（仅 Uni V3 类挖矿仓位可选）

GET or POST？

为了保证地址长度与参数安全，统一使用 POST，所有字段放 请求体，而非 URL query。

👉 想知道所有可用的 investmentId 都在哪些协议？点击查看协议浏览器 →

3. 参数示例速查

{
  "address": "0x1aD124...123",
  "chainId": "1",               // ETH 主网
  "investmentId": "lido_eth_2"
}

或者 BRC-20：

{
  "address": "bc1p...xyz",
  "poolId": "ordi_rune_pool_1",
  "investmentId": ""
}

4. 返回字段解码：如何读数据

关键字段	价值	程序员如何处理
`investmentName`	展示	用在前端 Card 标题
`investType`	逻辑	存币/质押/流动性map 到不同颜色、图标
`totalValue`	总计	资产排行榜排序与市值差异计算
`assetsTokenList`	明细	各类资产的 `tokenAddress`、`coinAmount`
`rewardDefiTokenInfo`	奖励	判断是否有待领取收益，按钮显示 “Claim”

rewardType：
1=公共奖励，2=可赎回，3=空投，4=奖励金。
区分这四类可以帮助前端自动分类及提示税务。

5. 完整示例：Python 3 请求脚本

import requests, json, os

url = "https://web3.okx.com/api/v5/defi/user/investment/asset-detail"
headers = {'Content-Type': 'application/json'}

payload = {
    "address": os.getenv("WALLET"),
    "investmentId": "compound_usdc"
}

resp = requests.post(url, headers=headers, data=json.dumps(payload))
if resp.status_code != 200:
    raise RuntimeError(resp.text)

data = resp.json()
print("总资产 USD：", data['data'][0]['totalValue'])
print("奖励列表：", data['data'][0]['rewardDefiTokenInfo'])

如果你想要批量查询 100 位用户，可把地址数组化并用asyncio并发 10 次，同步秒级完成。

6. 长尾场景示例：三种 API 组合打法

横向扫描：
先用 /v5/defi/user/investment/simple-list 枚举地址下所有 investmentId，再轮询本接口拉详情，3 秒内完成全网仓位发现。
纵向聚合：
取 totalValue 做首页资产饼图；点击区块后，再展示 assetsTokenList 的次维度。
实时告警：
如果 rewardType==2 && currencyAmount>100 美元，触发 TG Bot 提醒用户领取，提升平台留存率 15% 以上。

👉 5 分钟运行可视化 DeFi 投资组合案例源码，可 1 折开发私钥分离沙盒 →

7. 常见问题 FAQ

Q1：investmentId 怎么获得？
A：调用 /v5/defi/protocol/list，返回值列表中就包含每个协议的 investmentId，可直接映射。

Q2：同一条公链有多个同名的 staking pool 怎么办？
A：协议级别的 investmentId 带有唯一后缀（如 stETH_lido_eth_v2），不会冲突，前端直接按 ID 累加仓位即可。

Q3：测试环境只能用极小金额，会不会报错？
A：不会。API 基于链上真实数据拉取，与值大小无关；若找不到仓位，数组为空，但仍返回 totalValue":"0"。

Q4：能否在返回中增加代币单价？
A：现价已在 currencyAmount/coinAmount 隐含，如需单独价格，可二次调用市场 API。

Q5：多久更新一次数据？
A：追踪 RPC 节点高度，约 15 秒一个区块，节点同步完成后即实时刷新。

Q6：如果用户隐私要求不暴露地址，怎么办？
A：平台侧可采用匿名哈希 ID + ZK 证明方式聚合统计，再脱敏后展示，目前仅企业级服务支持。

8. 最佳实践速记

一套 SDK，全局缓存 30 秒，大多数钱包场景足够。
针对 NFT-Bound Pool（LP作为 ERC-721），要把 tokenId 与 tokenAddress 同时记录，避免拆分后再查失败。
同步监听 Transfer & Sync 事件，结合接口“轮询 + 流”双重保险，实时性达毫秒级。

通过本文，你已掌握如何：

用 POST 发起请求，0 遗漏地抓取用户所有投资品维度的仓位；
解析回报，完成前端卡面与聚合计算；
用代码示例把 15 分钟逻辑开发压缩到 5 分钟落地。

将以上步骤嵌入你的 Web3 项目，轻松打造“一站式资产管家”。