DeFi API 指南：一步调取用户协议维度持仓数据

·

API 概览

本接口 POST /api/v5/defi/user/asset/platform/detail 专为开发者设计，一键拉取「协议维度」的资产持仓列表，帮助钱包或资产管理应用在最短时间内展示用户在不同 DeFi 协议中的实时仓位与价值。

核心关键词：DeFi 资产、协议维度 API、持仓明细、区块链钱包、用户协议、链上数据、Web3 接口、数字资产仓位

接口 URL 与调用方法

POST https://web3.okx.com/api/v5/defi/user/asset/platform/detail
Content-Type: application/json

请求参数说明

只需提交 3 个必传字段，即可锁定用户与协议。

  1. analysisPlatformId string
    协议唯一标识，例如：aave_v3_polygon 或 uniswap_v3_ethereum。

  2. walletAddressList Array
    每个对象包含：

    • chainId string 区块链编号，如 1（Ethereum）或 137（Polygon）。
    • walletAddress string 用户实际持有的钱包地址。

    示例请求：

    {
  "analysisPlatformId": "compound_v2_eth",
  "walletAddressList": [
    {
      "chainId": "1",
      "walletAddress": "0xabcd...1234"
    },
    {
      "chainId": "137",
      "walletAddress": "0xefgh...5678"
    }
  ]
}

    响应结构拆解

    返回体遵循嵌套式设计，层层解包即可拿到最细颗粒度的持仓字段。

    • code / msg 状态码与信息
    • data 顶层 Object，下设 networkHoldVoList 数组

    networkHoldVoList 内部属性

    字段类型含义
    platformNamestring显示在 UI 的协议简称，如 Aave V3
    analysisPlatformIdstring后端排重所用 ID
    platformLogostringCDN 图标 URL，demo 可直接使用
    platformUrlstring协议官方站点，用于跳转
    totalValuestring该协议总 USD 价值
    investTokenBalanceVoListArray多仓位详情列表
    → investTypestring1-存币 2-流动性池 3-挖矿 4-机枪池 5-质押
    → coinAmountstring原始 Token 数量
    → currencyAmountstring美元计价金额

    有了这些字段，前端可在 “资产管理 → 协议详情页” 直接渲染三层嵌套卡片：协议 → 网络 → 仓位。

    典型响应示例

    {
  "code": 0,
  "msg": "",
  "data": {
    "networkHoldVoList": [
      {
        "network": "Ethereum",
        "chainId": "1",
        "platformName": "Aave V3",
        "analysisPlatformId": "aave_v3_ethereum",
        "platformLogo": "https://cdn.xx/aave32.png",
        "platformUrl": "https://aave.com",
        "totalValue": "12345.67",
        "investTokenBalanceVoList": [
          {
            "investType": "1",
            "tokenSymbol": "USDC",
            "tokenLogo": ".../usdc.png",
            "coinAmount": "10000.00",
            "currencyAmount": "10010.00",
            "tokenPrecision": "6",
            "tokenAddress": "0xA0b86a33E644...",
            "network": "Ethereum"
          }
        ]
      }
    ]
  }
}

    实战场景：快速集成钱包首页

    步骤 1：聚合多协议

    在钱包端循环 analysisPlatformId 列表，并行调用接口，一次性拿到所有 DeFi 资产。

    步骤 2：排序与去重

    利用 totalValue 进行从大到小排序，并合并相同 walletAddress 的多条结果。

    步骤 3：实时刷新

    通过前端轮询或 Websocket 回调 实现每 30 秒更新一次数字资产仓位，满足用户随时查看涨跌的需求。

    开发技巧与错误排查

    • 429 Too Many Requests
      调整 QPS 限制：在批量地址时，可用并发队列池一次发送不超过 10 条请求。
    • 合规字段长度限制
      walletAddressList 数量控制 ≤100，防止大数据导致网络阻塞。
    • 链 ID 输入校验
      若误填 chainId “56” 但传了以太坊地址，返回为空数组而非 error，需要前端手动提示。

    常见问题（FAQ）

    Q1：为什么返回空数组？
    A：最常见原因：① walletAddress 写错；② chainId 与链不匹配；③ 用户在该协议无仓位。

    Q2：能否一次查多个协议？
    A：当前接口仅支持 单个 protocolId 批量多地址。多协议请并行请求。

    Q3：数据多久更新一次？
    A：链上事件监听后 5–15 秒内同步至 API，基本属于 实时数据。

    Q4：是否支持测试网？
    A：支持。chainId 可填 5（Goerli）或 80001（Mumbai）体验 测试场景。

    Q5：如何获取协议 Logo 高分辨率版本？
    A：在 platformLogo 末尾追加 _256.png 即可拿到 256x256 像素高清图标。

    进阶技巧：锁仓收益可视化

    配合本接口返回的字段，你可以：

    1. 将 investType 映射为不同颜色 Tag，让存币、挖矿、质押一目了然。
    2. 对比 今日 totalValue 与昨日快照，计算 盈亏百分比。
    3. 在协议卡片右上加 闪电刷新按钮，复用本接口获取最新链上 apr，让 DeFi 资产仪表盘退休用户也能秒懂。

    想立即测试？
    👉 去体验实时接口沙盒并查看用户协议维度持仓完整示例

    最后，别忘记在生产环境设置合理的缓存 TTL：大额用户通常更关注秒级同步，散户可用 60 秒缓存节省 Gas 并减轻后台压力。祝你开发顺利！