持币地址
接口描述
获取指定代币在链上的持仓地址列表及地址的基础信息数据，同时支持指定地址的基础信息查询。
使用场景：
- 适用于鲸鱼、项目方、交易所等在链上的相关信息追踪与分析
- 适用于识别大户持仓行为和地址归属分析
- 适用于链上持仓分布和筹码集中度研究
数据更新频率：实时更新
请求URL
- 方法：
POST - 路径：
/open/v1/chain/trade/token/holdPage
积分消耗
- 消耗积分：
2
前置条件
获取 vsTokenId
| 条件 | 说明 | 获取方式 |
|---|---|---|
| 已有 vsTokenId | 直接使用缓存的 vsTokenId，无需重复查询 | 上下文自动提取 |
| 未有 vsTokenId | 调用 POST /vs-token/list 接口获取 | 前置接口调用 |
获取 coinKey
| 条件 | 说明 | 获取方式 |
|---|---|---|
| 已有 coinKey | 直接使用缓存的 coinKey，无需重复查询 | 上下文自动提取 |
| 未有 coinKey | 调用 POST /vs-token/detail 接口获取该代币在不同链上的 coinKey | 前置接口调用 |
请求参数
参数通过请求体（Body）以 JSON 格式传递。
| 参数名 | 类型 | 必需 | 描述 |
|---|---|---|---|
| vsTokenId | long | 是 | 代币 ID |
| page | integer | 是 | 当前页，默认1 |
| pageSize | integer | 是 | 当前页数据数量，默认10, 最多查询10000条数据 |
| coinKey | string | 是 | 代币的 coinkey 信息（链+合约地址信息），通过代币详情获取 |
| address | string | 否 | 地址 |
响应字段
仅展示 data 数组内每个对象的字段结构：
| 字段 | 类型 | 实际返回类型 | 描述 |
|---|---|---|---|
| vsTokenId | long | string | 代币 ID |
| symbol | string | string | 代币符号 |
| name | string | string | 代币名称 |
| coinKey | string | string | 代币键 |
| address | string | string | 地址 |
| label | object | object | 地址标签 |
| labelName | string | string | 标签名 |
| iconUrl | string | string | 图标 URL |
| isContract | boolean | boolean | 是否是合约地址 |
| exchangeSymbol | string | string | 交易所名称 |
| labelType | string | string | 类型 |
| reliability | integer | integer | 可信度 |
| balance | number | string | 余额 |
| price | number | string | 价格 |
| profit | number | string | 盈利 |
| cost | number | string | 持仓成本 |
| preCost | number | string | 前一次持仓成本 |
| chainName | string | string | 链名 |
字段业务含义
| 字段 | 业务含义 | 使用建议 |
|---|---|---|
| label | 地址标签 | 标识地址归属（如交易所、合约等），帮助识别大户身份 |
| profit | 持仓盈利 | 基于当前价格和持仓成本计算的浮动盈亏 |
| cost | 持仓成本 | 该地址买入代币的平均成本价 |
请求示例
json
{
"vsTokenId": 1, // 代币 id
"page": 1, // 当前页，默认1
"pageSize": 10, // 当前页数据数量，默认10, 最多查询10000条数据
"coinKey": "BTC_BTC" // 代币的 coinkey 信息（链+合约地址信息），通过代币详情获取
}cURL 示例（Linux/macOS）
bash
curl --location --request POST 'http://${host}/api/open/v1/chain/trade/token/holdPage' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: xxxxx' \
--header 'X-TIMESTAMP: xxxxx' \
--header 'X-SIGN: xxxxx' \
--header 'Accept: */*' \
--data-raw '{
"vsTokenId": 1,
"page": 1,
"pageSize": 10,
"coinKey": "BTC_BTC"
}'cURL 示例（Windows CMD）
cmd
curl --location --request POST "http://${host}/api/open/v1/chain/trade/token/holdPage" ^
--header "Content-Type: application/json" ^
--header "X-API-KEY: xxxxx" ^
--header "X-TIMESTAMP: xxxxx" ^
--header "X-SIGN: xxxxx" ^
--header "Accept: */*" ^
--data-raw "{ \"vsTokenId\": 1, \"page\": 1, \"pageSize\": 10, \"coinKey\": \"BTC_BTC\"}"成功响应示例
json
{
"code": 200,
"message": "success",
"data": [
{
"vsTokenId": "1", // 代币 ID
"symbol": "BTC", // 代币符号
"name": "Bitcoin", // 代币名称
"coinKey": "BTC_BTC", // 代币键
"address": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo", // 地址
"label": { // 地址标签
"labelName": "Binance Cold Wallet", // 标签名
"iconUrl": "/icon/label/Binance.png", // 图标 URL
"isContract": false, // 是否是合约地址
"exchangeSymbol": "", // 交易所名称
"labelType": "Exchange", // 类型
"reliability": "" // 可信度
},
"balance": "248597.58214169", // 余额
"price": "70624.85790154382", // 价格
"profit": "7913271920.4341697967652188545", // 盈利
"cost": "38828.441617175034708941", // 持仓成本
"preCost": "38828.441617175034708941", // 前一次持仓成本
"chainName": "BTC" // 链名
},
{
"vsTokenId": "1",
"symbol": "BTC",
"name": "Bitcoin",
"coinKey": "BTC_BTC",
"address": "3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6",
"label": {
"labelName": "Binance Cold Wallet",
"iconUrl": "/icon/label/Binance.png",
"isContract": false,
"exchangeSymbol": "",
"labelType": "Exchange",
"reliability": ""
},
"balance": "156026.54705644",
"price": "70624.85790154382",
"profit": "1804396311.20359371149441240088",
"cost": "59095.423712405135733623",
"preCost": "59095.423712405135733623",
"chainName": "BTC"
},
{
"vsTokenId": "1",
"symbol": "BTC",
"name": "Bitcoin",
"coinKey": "BTC_BTC",
"address": "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2",
"label": {
"labelName": "Robinhood Cold",
"iconUrl": "/icon/default.png",
"isContract": false,
"exchangeSymbol": "",
"labelType": "",
"reliability": ""
},
"balance": "140574.82614005",
"price": "70624.85790154382",
"profit": "5416163383.0562816957331038294",
"cost": "32131.412397458211476123",
"preCost": "32131.412397458211476123",
"chainName": "BTC"
}
// ... 更多数据省略
],
"requestId": "xxx-xxx-xxx"
}