基于协议的链上资产查询：DeFi API 实战指南

在日常的 DeFi API 调用、钱包数据分析或 Web3 项目开发中，快速拉取某一「协议」下用户的多链资产列表，是极为常见的需求。本文将围绕 https://web3.okx.com/api/v5/defi/user/asset/platform/detail 接口，给出完整的 用法范例、参数拆解、调试技巧及常见问答，帮助开发者 10 分钟内完成接入。

1. 接口定位与适用场景

关键词：DeFi、协议、用户资产、多链、持仓
解决问题：
1. 精确识别用户在指定协议（如 Aave、Uniswap）上的 净资产数量、价格折美元 及 不同网络分布；
2. 以 程序化方式 动态更新仪表板或钱包 App 的资产页；
3. 为审计、做市、风控提供 实时链上快照。

👉 一步到位：点击即可跳转到专业 API 调试环境，马上开始实战！

2. 请求结构（无表格说明）

2.1 请求地址

POST https://web3.okx.com/api/v5/defi/user/asset/platform/detail

2.2 必须字段

analysisPlatformId（协议 ID）
walletAddressList（用户地址数组，可为多条链的多个地址）

2.2.1 单链单地址范例

{
  "analysisPlatformId": "aave_v3",
  "walletAddressList": [
    {
      "chainId": "1",
      "walletAddress": "0x123...abcd"
    }
  ]
}

2.2.2 多链多地址范例

{
  "analysisPlatformId": "uniswap_v3",
  "walletAddressList": [
    {"chainId": "1", "walletAddress": "0xabc..."},
    {"chainId": "56", "walletAddress": "0xdef..."},
    {"chainId": "137", "walletAddress": "0xghi..."}
  ]
}

2.3 Header 建议

Content-Type: application/json
x-api-key: <你的 Key>

3. 响应数据深潜

接口返回的是 networkHoldVoList 数组，每一项代表一条网络上的完整资产概览，结构如下：

基础信息
- network：主网名称
- chainId：链 ID（1=Ethereum、56=BSC、137=Polygon 等）
投资类型 investType
1. Save（储蓄）
2. Pool（流动性池）
3. Farm（收益农场）
4. Vaults（机枪池）
5. Stake（质押）
单资产详情 investTokenBalanceVoList
- tokenSymbol：代币简称
- coinAmount：原币数量
- currencyAmount：折美元价值
- tokenAddress：合约地址
- tokenPrecision：小数位
汇总字段
- totalValue：该网络该协议下全部持仓价值（USD）

3.1 JSON 片段示例

"networkHoldVoList": [{
  "network": "ethereum",
  "chainId": "1",
  "investTokenBalanceVoList": [
    {
      "investType": "3",          // Farm
      "tokenSymbol": "USDC",
      "coinAmount": "1234.56",
      "currencyAmount": "1234.56",
      "tokenAddress": "0x...USDC"
    }
  ],
  "totalValue": "2340.15",
  "platformName": "Uniswap V3"
}]

4. 开发实操三步曲

Step 1：生成授权

先到控制台获取 DeFi API Key，配置 IP 白名单与 100 req/sec 限流。

Step 2：代码抄作业

以下采用 CURL、Python 双示例。

CURL

curl -X POST 'https://web3.okx.com/api/v5/defi/user/asset/platform/detail' \
-H 'Content-Type: application/json' \
-H 'x-api-key: 你的Key' \
-d '{
  "analysisPlatformId": "compound_v3",
  "walletAddressList": [
    {
      "chainId": "1",
      "walletAddress": "0xABCD..."
    }
  ]
}'

Python（requests）

import requests, json

url = "https://web3.okx.com/api/v5/defi/user/asset/platform/detail"
payload = {
    "analysisPlatformId": "compound_v3",
    "walletAddressList": [
        {"chainId": "1", "walletAddress": "0xABCD..."}
    ]
}
headers = {
    "Content-Type": "application/json",
    "x-api-key": "你的Key"
}
resp = requests.post(url, data=json.dumps(payload), headers=headers)
print(resp.json())

Step 3：错误码速查

状态码	含义	常见场景
400	Parameter Invalid	地址/链 ID 填写错误
401	Unauthorized	API Key 未授权访问 DeFi 模块
429	Rate Limit	请求频率超限，开启指数回退

5. FAQ：高频疑惑 6 连问

Q1：能否将「协议 ID」改为链上合约地址？
A1：目前必须选用官方 analysisPlatformId（短字符串形式）；合约地址需提前映射为 ID。

Q2：返回的 logo 和 URL 能商用吗？
A2：logo 与 protocolUrl 仅供展示，若向终端用户嵌入，请事先确认第三方协议的品牌授权。

Q3：tokenPrecision 为什么有时为空？
A3：合约未在主流数据源注册，可回退到 decimals() 调用。

Q4：是否支持分页？
A4：暂不支持，单协议单链返回条目一般不超过 200 条。

Q5：如何刷新缓存？
A5：该接口为实时节点查询，无缓存；如需读秒级数据，建议自建缓存层 + 触发更新。

Q6：在哪里可以查看可选的「analysisPlatformId」列表？
A6：前往 👉 获取完整协议 ID 字典文档，再也不用一行行试错！，官方每 24h 更新一次最新映射。

6. 与生俱来的应用灵感

聚合收益 App：把查询结果缓存到 Redis，按 30s 轮询，顶部转出美元总值。
审计工具：用 totalValue 做污点追踪，对闪电贷攻击场景重组仓位流。
Telegram Bot：当用户持仓价值 >1,000 USD 时主动推送「今日收益 +/-」通知。

只需一次轻量 POST，就能让 协议、持仓、资金去向 一目了然。快来体验吧！