Token 市场数据接口文档

重要调整：此接口需要传入 Token（X）地址（coinType 参数），传入要查询的 Token 的 Coin Type 地址。

接口概述

注意：这里计划跟 tokenlist 的接口拆分开，tokenlist 只返回价格即可，方便前端组件化调用拆分

本文档提供 Token 市场数据接口规范，用于 Token 详情页的数据展示。前期版本使用 HTTP 轮询方式获取数据，通过定期调用接口来更新数据。该接口主要用于以下组件：

token-header.tsx - Token 头部信息展示
coin-info-sidebar.tsx - Token 信息侧边栏
timeframe-trading-activity.tsx - 时间段交易活动

Token 市场数据接口

接口信息

接口路径: /api/token/market
请求方法: GET
接口描述: 获取指定 Token 的实时市场数据，包含价格、交易统计、供应量等信息。通过 HTTP 轮询此接口实现数据更新

请求参数

Query 参数

参数名	类型	必填	说明
coinType	string	是	Token 的 Coin Type（传入 Token 地址），如 "0x83556891f4a0f233ce7b05cfe7f957d4020492a34f5405b2cb9377d060bef4bf::spring_sui::SPRING_SUI"

请求示例

bash

GET /api/token/market?coinType=0x83556891f4a0f233ce7b05cfe7f957d4020492a34f5405b2cb9377d060bef4bf::spring_sui::SPRING_SUI

响应数据结构

响应格式

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "price": "1.7543546763043825",
    "marketData": {
      "m30": {
        "priceChange": 0.02,
        "volume": "161382.06658884676",
        "buyVolume": "80699.55189173302",
        "sellVolume": "80682.51469711376",
        "txnCount": 9,
        "buyTxnCount": 5,
        "sellTxnCount": 4,
        "makerCount": 4,
        "buyerCount": 4,
        "sellerCount": 3
      },
      "hour1": {
        "priceChange": 0.12,
        "volume": "280531.1027627877",
        "buyVolume": "140465.03062535284",
        "sellVolume": "140066.07213743488",
        "txnCount": 15,
        "buyTxnCount": 8,
        "sellTxnCount": 7,
        "makerCount": 6,
        "buyerCount": 5,
        "sellerCount": 4
      },
      "hour4": {
        "priceChange": 0.37,
        "volume": "761994.7879818098",
        "buyVolume": "381224.7571676368",
        "sellVolume": "380770.03081417293",
        "txnCount": 42,
        "buyTxnCount": 22,
        "sellTxnCount": 20,
        "makerCount": 12,
        "buyerCount": 10,
        "sellerCount": 9
      },
      "hour24": {
        "priceChange": -2.43,
        "volume": "1265960.1598681442",
        "buyVolume": "632981.8793852952",
        "sellVolume": "632978.2804828491",
        "txnCount": 2770,
        "buyTxnCount": 1290,
        "sellTxnCount": 1480,
        "makerCount": 332,
        "buyerCount": 273,
        "sellerCount": 292
      }
    },
    "marketCap": "14551259.339768803",
    "fdv": "152690783.64233437",
    "liquidity": "104820.57694631077",
    "totalSupply": "1270000",
    "circSupply": "1270000"
  }
}

响应字段说明

data 对象字段

字段名	类型	必填	说明
price	string	是	当前公允价格（USD），字符串格式的数字
marketData	object	是	时间段市场数据对象，包含 m30、hour1、hour4、hour24 四个时间段
marketCap	string	否	市值（USD），字符串格式的数字
fdv	string	否	完全稀释估值（USD），字符串格式的数字
liquidity	string	否	流动性（USD），字符串格式的数字
totalSupply	string	否	总供应量，字符串格式的数字
circSupply	string	否	流通供应量，字符串格式的数字

marketData 时间段对象字段（m30/hour1/hour4/hour24）

字段名	类型	必填	说明
priceChange	number	是	价格变化百分比，正数表示上涨，负数表示下跌
volume	string	是	总交易量（USD），字符串格式的数字
buyVolume	string	是	买入交易量（USD），字符串格式的数字
sellVolume	string	是	卖出交易量（USD），字符串格式的数字
txnCount	number	是	总交易数
buyTxnCount	number	是	买入交易数
sellTxnCount	number	是	卖出交易数
makerCount	number	是	总交易者数（去重后的唯一地址数）
buyerCount	number	是	买入交易者数（去重后的唯一地址数）
sellerCount	number	是	卖出交易者数（去重后的唯一地址数）

响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "price": "1.7543546763043825",
    "marketData": {
      "hour24": {
        "priceChange": -2.43,
        "volume": "1265960.1598681442",
        "buyVolume": "632981.8793852952",
        "sellVolume": "632978.2804828491",
        "txnCount": 2770,
        "buyTxnCount": 1290,
        "sellTxnCount": 1480,
        "makerCount": 332,
        "buyerCount": 273,
        "sellerCount": 292
      }
    },
    "marketCap": "14551259.339768803",
    "fdv": "152690783.64233437",
    "liquidity": "104820.57694631077",
    "totalSupply": "1270000",
    "circSupply": "1270000"
  }
}

轮询说明

实现方式：前端通过定时器定期调用此接口获取最新数据，实现数据更新。

轮询频率建议：每 5-10 秒轮询一次
接口应支持缓存，避免频繁查询数据库
建议对接口进行限流，防止过度请求

前端渲染说明

token-header.tsx 组件渲染

显示内容	数据来源	说明
Price	`data.price`	直接使用 `price` 字段，前端格式化显示
24h Change	`data.marketData.hour24.priceChange`	直接使用，前端格式化百分比（如 `-2.43` → `-2.43%`）
24h Volume	`data.marketData.hour24.volume`	直接使用 `volume` 字段，前端格式化（如 `1265960.16` → `$1.27M`）

显示内容	数据来源	说明
Price USD	`data.price`	直接使用 `price` 字段
Liquidity	`data.liquidity`	直接使用 `liquidity` 字段，前端格式化（如 `104820.57` → `$104.82K`）
FDV	`data.fdv`	直接使用 `fdv` 字段，前端格式化
Market Cap	`data.marketCap`	直接使用 `marketCap` 字段，前端格式化
Total Supply	`data.totalSupply`	直接使用 `totalSupply` 字段，前端格式化（如 `1270000` → `1.27K`）
Circ. Supply	`data.circSupply`	直接使用 `circSupply` 字段，前端格式化

timeframe-trading-activity.tsx 组件渲染

显示内容	数据来源	说明
30M/1H/4H/24H 价格变化	`data.marketData.{m30\|hour1\|hour4\|hour24}.priceChange`	直接使用，前端格式化百分比并添加正负号（如 `-0.71` → `-0.71%`，`1.64` → `+1.64%`）
Txns（交易数）	`data.marketData.{timeframe}.txnCount`	直接使用，前端格式化（如 `2770` → `2.77K`）
Buys（买入数）	`data.marketData.{timeframe}.buyTxnCount`	直接使用，前端格式化
Sells（卖出数）	`data.marketData.{timeframe}.sellTxnCount`	直接使用，前端格式化
Volume（交易量）	`data.marketData.{timeframe}.volume`	直接使用，前端格式化（如 `1265960.16` → `$1.27M`）
Buy VOL（买入量）	`data.marketData.{timeframe}.buyVolume`	直接使用，前端格式化
Sell VOL（卖出量）	`data.marketData.{timeframe}.sellVolume`	直接使用，前端格式化
Makers（交易者数）	`data.marketData.{timeframe}.makerCount`	直接使用
Buyers（买入者数）	`data.marketData.{timeframe}.buyerCount`	直接使用
Sellers（卖出者数）	`data.marketData.{timeframe}.sellerCount`	直接使用
买入百分比（进度条）	`buyTxnCount / txnCount * 100` 或 `buyVolume / volume * 100`	前端计算，根据显示场景选择使用交易数或交易量计算

注意事项

coinType 参数为必填项，需要传入完整的 Token Coin Type
所有价格和金额字段使用字符串格式，避免 JavaScript 数字精度问题
priceChange 为数值类型，正数表示上涨，负数表示下跌
txnCount、buyTxnCount、sellTxnCount 为数值类型，表示交易笔数
makerCount、buyerCount、sellerCount 为去重后的唯一地址数，不是交易笔数
volume、buyVolume、sellVolume 为 USD 计价
时间段数据可能不完整，前端需要做兼容处理（如某个时间段数据不存在）
响应格式遵循标准：code 为 0 表示成功，msg 为状态消息
前端通过轮询此接口实现数据更新，建议轮询频率为每 5-10 秒一次

Token 市场数据接口文档 ​

接口概述 ​

Token 市场数据接口 ​

接口信息 ​

请求参数 ​

Query 参数 ​

请求示例 ​

响应数据结构 ​

响应格式 ​

响应字段说明 ​

data 对象字段 ​

marketData 时间段对象字段（m30/hour1/hour4/hour24） ​

响应示例 ​

轮询说明 ​

前端渲染说明 ​

token-header.tsx 组件渲染 ​

coin-info-sidebar.tsx 组件渲染 ​

timeframe-trading-activity.tsx 组件渲染 ​

注意事项 ​