Token Price API 使用说明

本文档面向接入方开发者，介绍如何使用 Token Price API 查询多链代币价格、资产信息与 DEX 流动性池数据。

1. 快速开始

1.1 服务简介

Token Price API 是一个多链代币价格聚合查询服务。它提供以下核心能力：

查询系统支持的区块链列表与链基础信息
按代币 ID 或合约地址批量查询实时报价
查询代币资产信息（包括跨链平台分布）
查询法币列表与汇率
搜索 DEX 流动性池数据（数据来源 CoinGecko Onchain API）

所有对外接口均挂载在 /api/v1 路径前缀下，使用 HTTP/JSON 协议通信。当前对外服务不提供 WebSocket、SSE 或订阅推送接口。对外接口请求必须携带 X-API-Key，用于接口鉴权和计费。

1.2 Base URL

所有接口请求均以以下生产环境地址为根路径：

https://api.gelabs.org

示例：

https://api.gelabs.org/api/v1/chains

1.3 统一响应结构

接口统一使用 { code, msg, data } 响应体。业务成功时 code 固定为 0；常见参数校验失败通常仍返回 HTTP 200 并通过业务错误码区分。上游服务或内部异常可能返回 HTTP 503/500。

响应体结构固定为：

{
  "code": 0,
  "msg": "success",
  "data": {}
}

字段	类型	说明
`code`	integer	业务状态码。成功固定为 `0`，失败为对应错误码
`msg`	string	响应消息。成功时通常为 `success`
`data`	object / string	业务数据主体。失败时通常为空字符串 `""`

成功响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 1,
    "items": [...]
  }
}

失败响应示例：

{
  "code": 20001,
  "msg": "ids is required",
  "data": ""
}

注意： 请同时关注 HTTP 状态码和响应体 code。业务成功以 code: 0 为准；参数错误多为 HTTP 200 + 业务错误码；上游或内部失败可能是 HTTP 503/500。

1.4 业务错误码

错误码	含义	常见触发场景
`0`	成功	正常响应
`20001`	非法查询参数	必填的 query 参数缺失或格式不合法
`20002`	非法路径参数	路径参数格式不合法或资源未找到
`20003`	非法请求体	JSON 格式错误，或请求体中必填字段缺失/为空
`30001`	服务端错误	上游数据源请求失败或服务内部异常

1.5 公共请求头

所有对外服务接口请求均需要携带以下请求头：

请求头	必填	说明
`X-API-Key`	是	API Key，用于接口鉴权和计费。

部分接口还会返回缓存控制响应头，具体见各接口说明。

2. 链信息查询

本模块提供系统支持的区块链基础信息查询能力，适用于：

展示平台支持的链列表
根据链名称或 ID 获取链配置（图标、浏览器链接等）

2.1 获取链列表

返回系统当前支持的所有区块链基础信息。

请求

GET /api/v1/chains

请求参数

无。

curl 示例

curl -H "X-API-Key: $API_KEY" https://api.gelabs.org/api/v1/chains

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 2,
    "items": [
      {
        "id": 1,
        "name": "Ethereum",
        "short_name": "eth",
        "chain_id": 1,
        "chain_type": "evm",
        "chain_icon_url": "https://example.com/icons/eth.png",
        "explorer_url": "https://etherscan.io"
      },
      {
        "id": 2,
        "name": "Solana",
        "short_name": "sol",
        "chain_type": "svm",
        "chain_icon_url": "https://example.com/icons/sol.png",
        "explorer_url": "https://explorer.solana.com"
      }
    ]
  }
}

响应字段说明（data.items 单条）

字段	类型	必返回	说明
`id`	integer	是	链在系统内部的主键 ID
`name`	string	是	链名称，如 `Ethereum`
`short_name`	string	是	链简称，如 `eth`
`chain_id`	integer	否	链协议层 chain ID（EVM 链通常有此字段）
`chain_type`	string	否	链类型，如 `evm`、`svm`、`tvm`、`utxo`、`cosmos`、`move`
`chain_icon_url`	string	否	链图标 URL
`explorer_url`	string	否	链区块浏览器地址

2.2 按 ID 或名称查询链

根据链的数字 ID 或名称返回单条链信息。

请求

GET /api/v1/chains/{id_or_name}

路径参数

参数	类型	必填	说明
`id_or_name`	string	是	链的数字 ID（如 `1`）或链名称（如 `Ethereum`）

curl 示例

# 按数字 ID 查询
curl -H "X-API-Key: $API_KEY" https://api.gelabs.org/api/v1/chains/1

# 按链名称查询
curl -H "X-API-Key: $API_KEY" https://api.gelabs.org/api/v1/chains/Ethereum

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 1,
    "items": [
      {
        "id": 1,
        "name": "Ethereum",
        "short_name": "eth",
        "chain_id": 1,
        "chain_type": "evm",
        "chain_icon_url": "https://example.com/icons/eth.png",
        "explorer_url": "https://etherscan.io"
      }
    ]
  }
}

未找到时的响应

注意： 链未找到时，HTTP 状态码仍为 200，通过业务码 20002 标识失败。

{
  "code": 20002,
  "msg": "chain not found",
  "data": ""
}

3. 代币报价查询

本模块提供代币实时报价能力，支持两种查询方式：

按代币 ID 查询：适合已知系统内部代币 ID 的场景，返回带完整市场行情的报价数据
按合约地址查询：适合已知链和合约地址的场景，返回精确到链级别的价格数据

3.1 批量获取最新报价

根据代币 ID 列表批量获取最新报价，支持指定目标法币。

请求

GET /api/v1/quotes/latest

查询参数

参数	类型	必填	默认值	说明
`ids`	string	是	—	代币 ID 列表，多个值用英文逗号分隔，如 `1,1027,825`
`fiat`	string	否	`USD`	目标法币代码，如 `USD`、`CNY`。不传时默认使用 `USD`

curl 示例

# 查询 BTC（id=1）和 ETH（id=1027）的 USD 报价
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/quotes/latest?ids=1,1027"

# 指定法币为 CNY
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/quotes/latest?ids=1,1027&fiat=CNY"

缓存说明

本接口成功响应时会附带以下缓存头，客户端和 CDN 可据此缓存 3 秒：

Cache-Control: public, max-age=3, s-maxage=3

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "token_id": 1,
        "name": "Bitcoin",
        "symbol": "BTC",
        "fiat_id": 1,
        "fiat_code": "USD",
        "price": "65000.12345678",
        "market_cap": "1280000000000",
        "volume_24h": "38000000000",
        "volume_change_24h": "0",
        "percent_change_1h": "0.12",
        "percent_change_24h": "2.35",
        "percent_change_7d": "-1.08",
        "percent_change_30d": "15.20",
        "fully_diluted_valuation": "1365000000000",
        "circulating_supply": "19700000",
        "total_supply": "19700000",
        "max_supply": "21000000"
      }
    ]
  }
}

响应字段说明（data.items 单条）

字段	类型	说明
`token_id`	integer	代币系统内部 ID
`name`	string	代币名称
`symbol`	string	代币符号
`fiat_id`	integer	报价法币系统内部 ID
`fiat_code`	string	报价法币代码，如 `USD`
`price`	string	当前价格（字符串格式）
`market_cap`	string	市值（字符串格式）
`volume_24h`	string	24 小时成交量（字符串格式）
`volume_change_24h`	string	24 小时成交量变化值（字符串格式）
`percent_change_1h`	string	1 小时涨跌幅（字符串格式）
`percent_change_24h`	string	24 小时涨跌幅（字符串格式）
`percent_change_7d`	string	7 天涨跌幅（字符串格式）
`percent_change_30d`	string	30 天涨跌幅（字符串格式）
`fully_diluted_valuation`	string	完全稀释估值（字符串格式）
`circulating_supply`	string	流通供应量（字符串格式）
`total_supply`	string	总供应量（字符串格式）
`max_supply`	string	最大供应量（字符串格式）

注意： 本接口所有价格、市值、供应量等数值字段均为字符串类型，使用时请自行解析为数字。

缺少 ids 参数时的错误响应

{
  "code": 20001,
  "msg": "ids is required",
  "data": ""
}

3.2 按合约地址批量查询价格

根据链类型、链 ID 和代币合约地址批量返回代币价格信息。适合已知链上地址、需要精确定位代币价格的场景。

请求

POST /api/v1/quotes/batch
Content-Type: application/json

请求体结构

{
  "token_addrs": [
    {
      "chain_type": "evm",
      "chain_id": 1,
      "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    }
  ],
  "fiat": "USD"
}

请求体字段说明

字段	类型	必填	说明
`token_addrs`	array	是	待查询的代币地址数组，不能为空
`token_addrs[].chain_type`	string	是	链类型，标准值为 `evm`、`svm`、`tvm`、`utxo`、`cosmos`、`move`；也支持 `ethereum`、`solana`、`tron` 等别名自动归一化
`token_addrs[].chain_id`	integer	否	链协议 ID，EVM 链需传入（如以太坊主网为 `1`），其他链可为 `null`
`token_addrs[].token_address`	string	是	代币合约地址或链上标识
`fiat`	string	否	目标法币代码，默认为 `USD`（当前底层主要基于 USD 价格处理）

curl 示例

curl -X POST "https://api.gelabs.org/api/v1/quotes/batch" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token_addrs": [
      {
        "chain_type": "evm",
        "chain_id": 1,
        "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      },
      {
        "chain_type": "svm",
        "chain_id": null,
        "token_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      }
    ],
    "fiat": "USD"
  }'

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "token_id": 3408,
        "name": "USD Coin",
        "symbol": "USDC",
        "chain_type": "evm",
        "chain_id": 1,
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "external_id": "usd-coin",
        "price_usd": 0.9998,
        "market_cap_usd": 43000000000,
        "volume_24h_usd": 8500000000,
        "percent_change_1h": 0.01,
        "percent_change_24h": -0.02,
        "percent_change_7d": 0.05,
        "percent_change_30d": -0.01,
        "last_updated": "2026-04-21T08:00:00Z",
        "market_cap": 43000000000,
        "fully_diluted_valuation": 43000000000,
        "total_volume": 8500000000,
        "circulating_supply": 43000000000,
        "total_supply": 43000000000,
        "max_supply": null
      }
    ]
  }
}

响应字段说明（data.items 单条）

字段	类型	说明
`token_id`	integer	代币系统内部 ID
`name`	string	代币名称
`symbol`	string	代币符号
`chain_type`	string	链类型
`chain_id`	integer	链协议 ID
`address`	string	代币地址
`external_id`	string	外部数据源（如 CoinGecko）中的代币唯一标识
`price_usd`	number	USD 价格（数字类型）
`market_cap_usd`	number	USD 市值（数字类型）
`volume_24h_usd`	number	USD 口径的 24 小时成交量（数字类型）
`percent_change_1h`	number	1 小时涨跌幅（数字类型）
`percent_change_24h`	number	24 小时涨跌幅（数字类型）
`percent_change_7d`	number	7 天涨跌幅（数字类型）
`percent_change_30d`	number	30 天涨跌幅（数字类型）
`last_updated`	string	最后更新时间，ISO 8601 格式
`market_cap`	number	市值（数字类型）
`fully_diluted_valuation`	number	完全稀释估值（数字类型）
`total_volume`	number	总成交量（数字类型）
`circulating_supply`	number	流通供应量（数字类型）
`total_supply`	number	总供应量（数字类型）
`max_supply`	number	最大供应量（数字类型）

与 /api/v1/quotes/latest 的区别： 本接口返回的价格、市值等数值字段均为数字类型（number），而 /api/v1/quotes/latest 返回的是字符串类型。

常见错误响应

// token_addrs 为空数组
{
  "code": 20003,
  "msg": "token_addrs is required",
  "data": ""
}

// 请求体 JSON 格式错误
{
  "code": 20003,
  "msg": "invalid JSON body",
  "data": ""
}

4. 资产信息查询

本模块提供代币与法币的基础资产信息查询能力，适用于：

构建代币选择器、搜索框
展示代币跨链平台分布
获取法币列表及实时汇率

4.1 获取代币列表

查询系统内的代币信息，支持三种查询模式。全量列表支持分页，单次最多返回 1000 条。

请求

GET /api/v1/tokens

查询参数

参数	类型	必填	默认值	说明
`chain_id`	string	否	—	链的系统内部 ID，用于限定查询范围
`address`	string	否	—	代币合约地址，通常需与 `chain_id` 组合使用
`page`	integer	否	`1`	页码，从 `1` 开始。仅在不传 `chain_id` 和 `address` 时生效
`limit`	integer	否	`100`	每页条数，最大 `1000`。仅在不传 `chain_id` 和 `address` 时生效

查询模式说明

传参组合	行为
不传任何参数	返回分页的活跃代币列表，受 `page`、`limit` 控制
仅传 `chain_id`	尝试返回该链的原生币（不分页）
同时传 `chain_id` 和 `address`	按链 ID 与合约地址精确匹配单个代币（不分页）

curl 示例

# 获取第 1 页代币列表（默认每页 100 条）
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/tokens"

# 分页查询：第 2 页，每页 200 条
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/tokens?page=2&limit=200"

# 获取以太坊（chain_id=1）的原生币 ETH
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/tokens?chain_id=1"

# 按链和合约地址精确查询 USDC
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/tokens?chain_id=1&address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

成功响应示例（全量分页）

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 5432,
    "page": 1,
    "limit": 100,
    "items": [
      {
        "id": 1001,
        "name": "Ether",
        "symbol": "ETH",
        "decimals": 18,
        "logo_url": "https://example.com/eth.png",
        "chain_id": 1,
        "chain_name": "Ethereum",
        "is_native": true
      },
      {
        "id": 1002,
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "logo_url": "https://example.com/usdc.png",
        "chain_id": 1,
        "chain_name": "Ethereum",
        "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "is_native": false
      }
    ]
  }
}

顶层响应字段说明（data）

字段	类型	说明
`total`	integer	符合条件的代币总条数
`page`	integer	当前页码（精确查询模式下固定为 `1`）
`limit`	integer	本次请求的每页条数（精确查询模式下等于实际返回条数）
`items`	array	当前页的代币列表

响应字段说明（data.items 单条）

字段	类型	必返回	说明
`id`	integer	是	代币系统内部 ID
`name`	string	是	代币名称
`symbol`	string	是	代币符号
`decimals`	integer	是	代币精度（小数位数）
`logo_url`	string	否	代币图标 URL
`chain_id`	integer	是	所属链的系统内部 ID
`chain_name`	string	是	所属链名称
`contract_address`	string	否	代币合约地址；原生币不返回此字段
`is_native`	boolean	是	是否为链原生币（如 ETH、SOL）

分页遍历示例： 若需拉取全量数据，可通过 total 与 limit 计算总页数，然后依次请求各页：
total_pages = Math.ceil(total / limit)，再循环请求 page=1 至 page=total_pages。

4.2 搜索代币平台记录

根据代币合约地址、名称或符号，搜索该代币在多个链上的平台记录。

请求

GET /api/v1/tokens/platforms/{keyword}

路径参数

参数	类型	必填	说明
`keyword`	string	是	代币合约地址、名称或符号（精确匹配，不区分大小写）

匹配优先级

首先尝试将 keyword 作为合约地址进行精确匹配（不区分大小写）
若无结果，再按代币名称或符号进行精确匹配（不区分大小写）

curl 示例

# 按符号搜索 USDC 在各链上的平台分布
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/tokens/platforms/USDC"

# 按合约地址搜索
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/tokens/platforms/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 3,
    "items": [
      {
        "id": 1002,
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "chain_id": 1,
        "chain_name": "Ethereum",
        "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "is_native": false
      },
      {
        "id": 1003,
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "chain_id": 2,
        "chain_name": "BNB Smart Chain",
        "contract_address": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
        "is_native": false
      }
    ]
  }
}

响应字段含义与 4.1 获取代币列表中的 TokenItem 相同。

4.3 获取法币列表

返回系统支持的法币信息列表。

请求

GET /api/v1/fiats

请求参数

无。

curl 示例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/fiats"

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 3,
    "items": [
      {
        "id": 1,
        "code": "USD",
        "name": "US Dollar",
        "symbol": "$",
        "icon_url": "https://example.com/usd.png",
        "precision": 2
      },
      {
        "id": 2,
        "code": "CNY",
        "name": "Chinese Yuan",
        "symbol": "¥",
        "icon_url": "https://example.com/cny.png",
        "precision": 2
      }
    ]
  }
}

响应字段说明（data.items 单条）

字段	类型	必返回	说明
`id`	integer	是	法币系统内部 ID
`code`	string	是	法币代码，如 `USD`、`CNY`
`name`	string	是	法币名称
`symbol`	string	是	法币符号，如 `$`、`¥`；未配置时返回空字符串
`icon_url`	string	否	法币图标 URL
`precision`	integer	是	显示精度（小数位数），未配置时默认返回 `2`

4.4 获取法币汇率

根据基础法币代码，返回其与其他法币之间的汇率列表。

请求

GET /api/v1/fiats/rates/{base}

路径参数

参数	类型	必填	说明
`base`	string	是	基础法币代码，如 `USD`、`CNY`

注意： base 参数大小写不敏感，服务端会自动转为大写处理。

curl 示例

# 获取以 USD 为基准的所有法币汇率
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/fiats/rates/USD"

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 2,
    "items": [
      {
        "target_fiat_id": 2,
        "target_fiat_code": "CNY",
        "rate": "7.24000000"
      },
      {
        "target_fiat_id": 3,
        "target_fiat_code": "EUR",
        "rate": "0.92000000"
      }
    ]
  }
}

响应字段说明（data.items 单条）

字段	类型	说明
`target_fiat_id`	integer	目标法币系统内部 ID
`target_fiat_code`	string	目标法币代码
`rate`	string	汇率值，精度为 8 位小数的字符串格式

说明： 当查询的基础法币没有汇率数据时，接口仍返回成功结构，但 items 为空数组，total 为 0。

5. DEX 流动性池查询

本模块提供 DEX 流动性池的精确查询能力，数据透传自 CoinGecko Onchain API，适用于：

根据链信息和 pool 合约地址查询单条流动性池详情
查看池子的价格、交易量与流动性深度
监控链上实时交易活跃度

5.1 查询流动性池

根据链类型、链 ID 和 pool 合约地址查询单条 DEX 流动性池详情。服务内部会自动通过数据库查找对应链的 CoinGecko network 标识，再透传至 CoinGecko Onchain API。

请求

GET /api/v1/pools

查询参数

参数	类型	必填	说明
`chain_type`	string	是	链类型。标准值：`evm`、`svm`、`tvm`、`utxo`、`cosmos`、`move`。支持别名：`ethereum`→`evm`、`solana`→`svm`、`tron`→`tvm`、`bitcoin`/`litecoin`/`dogecoin`/`bitcoin cash`→`utxo`、`sui`/`aptos`→`move`
`chain_id`	string	是	链协议 ID，对应 `blockchains` 表中的 `chain_id` 字段，如 `1`（Ethereum 主网）
`pool_address`	string	是	Pool 合约地址

curl 示例

# 查询以太坊主网上指定 pool
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/pools?chain_type=evm&chain_id=1&pool_address=0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"

# chain_type 使用别名（ethereum 会自动归一化为 evm）
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/pools?chain_type=ethereum&chain_id=1&pool_address=0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"

# 查询 Solana 上的 pool（chain_id 使用对应值）
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/pools?chain_type=svm&chain_id=900&pool_address=<pool_address>"

缓存说明

本接口结果缓存 1 小时。缓存 key 由 chain_type、chain_id、pool_address 三个维度共同决定。

成功响应示例（找到数据）

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": "eth_0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
    "name": "WETH / USDC 0.05%",
    "address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
    "network": "eth",
    "dex": "uniswap_v3",
    "pool_created_at": "2021-12-29T12:35:14Z",
    "base_token": {
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "name": "Wrapped Ether",
      "symbol": "WETH",
      "image_url": "https://assets.coingecko.com/coins/images/2518/small/weth.png"
    },
    "quote_token": {
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "name": "USD Coin",
      "symbol": "USDC",
      "image_url": "https://assets.coingecko.com/coins/images/6319/small/usdc.png"
    },
    "base_token_price_usd": "3653.12",
    "quote_token_price_usd": "0.9983",
    "fdv_usd": "11007041041",
    "market_cap_usd": null,
    "price_change_percentage": {
      "m5": "0",
      "h1": "0.51",
      "h6": "1.23",
      "h24": "7.71"
    },
    "volume_usd": {
      "h1": "16798158.01",
      "h24": "536545444.90"
    },
    "reserve_in_usd": "163988541.38",
    "transactions": {
      "h24": {
        "buys": 2966,
        "sells": 3847,
        "buyers": 1625,
        "sellers": 2399
      }
    }
  }
}

成功响应示例（未找到数据）

链或 pool 不存在时，HTTP 状态码仍为 200，data 返回 null。

{
  "code": 0,
  "msg": "success",
  "data": null
}

响应字段说明（data 非 null 时）

字段	类型	说明
`id`	string	CoinGecko Pool 唯一标识，格式为 `{network}_{pool_address}`
`name`	string	Pool 名称，如 `WETH / USDC 0.05%`
`address`	string	Pool 合约地址
`network`	string	所在网络的 CoinGecko network ID
`dex`	string	所在 DEX 的标识，如 `uniswap_v3`
`pool_created_at`	string	Pool 创建时间，ISO 8601 格式
`base_token`	object	Base token 信息（见下方）
`quote_token`	object	Quote token 信息（见下方）
`base_token_price_usd`	string	Base token 的 USD 价格（字符串格式）
`quote_token_price_usd`	string	Quote token 的 USD 价格（字符串格式）
`fdv_usd`	string / null	完全稀释估值（USD），无数据时为 `null`
`market_cap_usd`	string / null	市值（USD），无数据时为 `null`
`price_change_percentage`	object	多时间维度涨跌幅，key 为 `m5`、`m15`、`m30`、`h1`、`h6`、`h24`
`volume_usd`	object	多时间维度 USD 交易量，key 同上
`reserve_in_usd`	string	池子 USD 总流动性（字符串格式）
`transactions`	object	多时间维度交易统计，key 同上（见下方）

base_token / quote_token 字段

字段	类型	说明
`address`	string	Token 合约地址
`name`	string	Token 名称
`symbol`	string	Token 符号
`image_url`	string	Token 图标 URL

transactions 各时间维度字段

字段	类型	说明
`buys`	integer	买入笔数
`sells`	integer	卖出笔数
`buyers`	integer	买入独立地址数
`sellers`	integer	卖出独立地址数

常见错误响应

// 缺少 chain_type 参数
{
  "code": 20001,
  "msg": "chain_type is required",
  "data": ""
}

// 缺少 chain_id 参数
{
  "code": 20001,
  "msg": "chain_id is required",
  "data": ""
}

// 缺少 pool_address 参数
{
  "code": 20001,
  "msg": "pool_address is required",
  "data": ""
}

// 上游 CoinGecko API 或内部查询服务请求失败（HTTP 503）
{
  "code": 30001,
  "msg": "Failed to fetch pool data",
  "data": ""
}

6. 实时协议与 WebSocket

当前版本仅提供 HTTP/JSON API，不提供 WebSocket、SSE 或其他长连接实时协议。

项目	当前支持情况	说明
WebSocket 升级路径	不支持	无 `ws://` / `wss://` 入口，无 HTTP `Upgrade` 处理
协议常量	无	无订阅、取消订阅、频道、事件类型等常量
客户端发送消息结构	无	不存在 WS 请求帧、订阅帧或心跳帧
服务端推送消息结构	无	不存在 WS 响应帧、错误帧或行情推送帧
心跳与重连	无	请使用 HTTP 接口按需轮询

如需获取近实时价格，推荐轮询 GET /api/v1/quotes/latest。该接口成功响应带有 Cache-Control: public, max-age=3, s-maxage=3，客户端可按业务需求结合缓存头控制轮询频率。

7. 健康检查（附录）

本模块提供三个探针接口，供运维监控系统和容器编排平台（如 Kubernetes）进行服务状态探测，不涉及业务数据。

接口	用途	适用场景
`GET /api/v1/health`	综合健康检查，反映服务整体状态	外部监控系统的主探针
`GET /api/v1/ready`	就绪检查，反映服务是否可接收请求	容器编排的 Readiness Probe
`GET /api/v1/live`	存活检查，反映进程是否存活	容器编排的 Liveness Probe

7.1 健康检查

请求

GET /api/v1/health

curl 示例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/health"

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "ok"
  }
}

7.2 就绪检查

请求

GET /api/v1/ready

curl 示例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/ready"

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "ready"
  }
}

7.3 存活检查

请求

GET /api/v1/live

curl 示例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/api/v1/live"

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "alive"
  }
}

文档版本：v1.2.0 | 最后更新：2026-04-28

目录​

1. 快速开始​

1.1 服务简介​

1.2 Base URL​

1.3 统一响应结构​

1.4 业务错误码​

1.5 公共请求头​

2. 链信息查询​

2.1 获取链列表​

2.2 按 ID 或名称查询链​

3. 代币报价查询​

3.1 批量获取最新报价​

3.2 按合约地址批量查询价格​

4. 资产信息查询​

4.1 获取代币列表​

4.2 搜索代币平台记录​

4.3 获取法币列表​

4.4 获取法币汇率​

5. DEX 流动性池查询​

5.1 查询流动性池​

6. 实时协议与 WebSocket​

7. 健康检查（附录）​

7.1 健康检查​

7.2 就绪检查​

7.3 存活检查​

目录

1. 快速开始

1.1 服务简介

1.2 Base URL

1.3 统一响应结构

1.4 业务错误码

1.5 公共请求头

2. 链信息查询

2.1 获取链列表

2.2 按 ID 或名称查询链

3. 代币报价查询

3.1 批量获取最新报价

3.2 按合约地址批量查询价格

4. 资产信息查询

4.1 获取代币列表

4.2 搜索代币平台记录

4.3 获取法币列表

4.4 获取法币汇率

5. DEX 流动性池查询

5.1 查询流动性池

6. 实时协议与 WebSocket

7. 健康检查（附录）

7.1 健康检查

7.2 就绪检查

7.3 存活检查