DeFi API 介绍

Copy page

DeFi API 提供链上 DeFi 数据服务与交易构建能力，包括用户持仓查询、带分页的协议与投资品发现，以及存入、赎回、流动性和领取操作的 calldata 构建。本期支持 10 条 EVM 链——BNB Smart Chain、Ethereum、Base、Arbitrum One、Polygon、Optimism、Avalanche C-Chain、Robinhood、Katana、ARC——后续将支持更多链与协议。

功能概览

DeFi Data

功能	接口	方法	说明
持仓查询	/api/v1/defi/data/position/list	POST	查询一个或多个钱包地址在全部支持链上的 DeFi 持仓
协议列表	/api/v1/defi/data/protocol/list	POST	分页获取支持的 DeFi 协议，支持过滤
协议详情	/api/v1/defi/data/protocol/detail	POST	获取指定 DeFi 协议的详情
投资品列表	/api/v1/defi/data/investment/list	POST	获取可用的 DeFi 投资品
投资品详情	/api/v1/defi/data/investment/detail	POST	获取指定投资品的详情

DeFi Transaction

交易接口构建未签名的 DeFi calldata —— 不托管私钥。每个响应返回有序 dataList（需要时 ERC-20 APPROVE 在前、主交易在后），由钱包按序签名广播。在五个交易构建接口（/deposit、/redeem、/lp-add、/lp-remove、/claim）上设 simulate=true 可在广播前同时返回 preview（预估余额变动、预估 gas、借贷 health-factor 变化）。端到端构建 → 签名 → 广播 → 轮询流程见集成流程。

功能	接口	方法	说明
构建存入	/api/v1/defi/transaction/deposit	POST	构建存入 / 质押交易 calldata
构建赎回	/api/v1/defi/transaction/redeem	POST	构建赎回 / 解押交易 calldata
添加流动性	/api/v1/defi/transaction/lp-add	POST	构建添加流动性交易 calldata
计算 LP 数量	/api/v1/defi/transaction/lp-add/calculate	POST	添加流动性前计算配对 token 数量
移除流动性	/api/v1/defi/transaction/lp-remove	POST	构建移除流动性交易 calldata
领取奖励	/api/v1/defi/transaction/claim	POST	构建领取奖励或赎回本金 calldata

路径分层

数据查询接口位于 /api/v1/defi/data/*；交易构建接口位于 /api/v1/defi/transaction/*。

覆盖范围

支持范围按接口区分：

• 持仓查询覆盖全部支持链上更广的协议集合。不在交易 / 投资品清单内的协议持仓仅用于展示（无 investmentIds、不能发起交易）。
• 协议 / 投资品数据查询与交易构建仅对交易 / 投资品清单内的协议开放（按链区分——见支持的链与协议）。

两份清单及差异见支持的链与协议。

持仓数据结构

POST /api/v1/defi/data/position/list 返回五层嵌套结构：

Code
totalValue                        — 所有查询地址的持仓总值
└─ addressList[]                  — 每个查询地址一个条目
   ├─ address, addressTotalValue  — 地址及其持仓总值
   └─ protocolList[]              — 该地址在各协议下的持仓
      ├─ binanceChainId, defiProtocolId, protocolTotalValue
      └─ poolList[]               — 该协议下有持仓的池
         ├─ bnPoolId, poolCa, poolType
         └─ positionCollectionList[]  — 池下的仓位分组
            ├─ positionCollectionId, positionCollectionTotalValue
            └─ positionList[]     — 具体仓位
               ├─ positionId, underlyingAssetName, investmentIds
               └─ tokenList       — 按角色分组的代币明细（supply/borrow/reward/farming_reward）

仓位集合（position collection）是什么：一个池按底层资产对仓位分组。单资产池（如 Venus USDT 供给）通常每个资产一个集合；多资产池（如 Uniswap V3 池）可能有多个集合。拿不准时按集合层聚合——positionCollectionTotalValue 就是该集合下所有仓位的现成合计。

数据格式约定

除特别说明外，DeFi Data 接口遵循以下格式规则：

字段类型	约定
APY	两个派生字段：apyBps（整数，基点——1 bps = 0.01%，如 9963 = 99.63%）用于排序 / 比较 / 筛选，apyDisplay（预格式化字符串，如 "99.63%"）用于展示——直接原样引用，禁止二次计算。不返回裸小数 apy。
TVL	小数字符串，美元，保留数据源原始精度（如 "1250000.5"）
价值	持仓类价值（totalValue、addressTotalValue、protocolTotalValue）为小数字符串，美元，保留数据源原始精度
数量	人类可读的小数字符串（如 "1000.5"），非代币最小单位
时间戳	所有接口统一 Unix 秒（如池 expiry、仓位 unlockTime）
主链币	地址 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee（40 个 e）代表链原生币
链 ID	binanceChainId 对 EVM 链使用纯数字字符串（如 "56" = BNB Smart Chain、"1" = Ethereum），与 Trading / Transaction API 记法一致。完整清单见支持的链与协议。

频率限制

DeFi API 请求按四个独立维度限频：per-IP 1200 次 / 60s、per-API-Key 1200 次 / 60s、per-user 6000 次 / 60s、单端点默认 5 RPS。超限时网关返回 HTTP 429（业务码 42900，带 Retry-After 响应头），请按 Retry-After 退避后重试。