Token Price API · 介面詳情

鏈資訊查詢

本模組提供系統支援的區塊鏈基礎資訊查詢能力，適用於：

• 展示平台支援的鏈列表
• 根據鏈名稱或 ID 取得鏈配置（圖示、瀏覽器連結等）

---

取得鏈列表

返回系統目前支援的所有區塊鏈基礎資訊。

請求

GET /price/api/v1/chains

請求參數

無。

curl 範例

curl -H "X-API-Key: $API_KEY" https://api.gelabs.org/price/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	否	鏈區塊瀏覽器地址

---

按 ID 或名稱查詢鏈

根據鏈的數字 ID 或名稱返回單筆鏈資訊。

請求

GET /price/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/price/api/v1/chains/1

# 按鏈名稱查詢
curl -H "X-API-Key: $API_KEY" https://api.gelabs.org/price/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": ""
}

---

代幣報價查詢

本模組提供代幣即時報價能力，支援兩種查詢方式：

• 按代幣 ID 查詢：適合已知系統內部代幣 ID 的場景，返回帶完整市場行情的報價資料
• 按合約地址查詢：適合已知鏈和合約地址的場景，返回精確到鏈級別的價格資料

---

批量取得最新報價

根據代幣 ID 列表批量取得最新報價，支援指定目標法幣。

請求

GET /price/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/price/api/v1/quotes/latest?ids=1,1027"

# 指定法幣為 CNY
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/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": ""
}

---

按合約地址批量查詢價格

根據鏈類型、鏈 ID 和代幣合約地址批量返回代幣價格資訊。適合已知鏈上地址、需要精確定位代幣價格的場景。

請求

POST /price/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/price/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	代幣擴充標識
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	最大供應量（數字類型）

與 /price/api/v1/quotes/latest 的區別： 本介面返回的價格、市值等數值欄位均為數字類型（number），而 /price/api/v1/quotes/latest 返回的是字串類型。

常見錯誤回應

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

// 請求體 JSON 格式錯誤
{
  "code": 20003,
  "msg": "invalid JSON body",
  "data": ""
}

---

資產資訊查詢

本模組提供代幣與法幣的基礎資產資訊查詢能力，適用於：

• 建構代幣選擇器、搜尋框
• 展示代幣跨鏈平台分布
• 取得法幣列表及即時匯率

---

取得代幣列表

查詢系統內的代幣資訊，支援三種查詢模式。全量列表支援分頁，單次最多返回 1000 筆。

請求

GET /price/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/price/api/v1/tokens"

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

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

# 按鏈和合約地址精確查詢 USDC
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/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。

---

批量查詢代幣詳情

根據 token 表內部 ID 集合批量查詢代幣詳情，適合已知內部 ID、需要展示基礎資料和外部資料來源標識的場景。

請求

POST /price/api/v1/tokens/details
Content-Type: application/json

請求體結構

{
  "ids": [1, 2, 3]
}

請求體欄位說明

欄位	類型	必填	說明
ids	array	是	token 表內部 ID 陣列，不能為空，最多 100 個

curl 範例

curl -X POST "https://api.gelabs.org/price/api/v1/tokens/details" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [1, 2] }'

成功回應範例

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 2,
    "items": [
      {
        "id": 1,
        "name": "Ethereum",
        "symbol": "ETH",
        "decimals": 18,
        "logo_url": "https://example.com/eth.png",
        "chain_id": 1,
        "chain_name": "Ethereum",
        "is_native": true,
        "external_ids": [
          {
            "source": "coingecko",
            "external_id": "ethereum"
          }
        ]
      },
      {
        "id": 2,
        "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,
        "circulating_supply": "43000000000",
        "total_supply": "43000000000",
        "external_ids": [
          {
            "source": "coingecko",
            "external_id": "usd-coin"
          }
        ]
      }
    ]
  }
}

回應欄位說明（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	是	是否為鏈原生幣
max_supply	string	否	最大供應量，字串格式
circulating_supply	string	否	流通供應量，字串格式
total_supply	string	否	總供應量，字串格式
external_ids	array	是	外部資料來源標識列表，元素包含 source 和 external_id

說明： 回應按請求 ID 去重後的順序返回；未找到或非活躍代幣不會出現在 items 中。

常見錯誤回應

// ids 为空数组或缺失
{
  "code": 20003,
  "msg": "ids is required",
  "data": ""
}

// ids 包含非法值
{
  "code": 20003,
  "msg": "ids must be positive integers",
  "data": ""
}

---

搜尋代幣平台記錄

根據代幣合約地址、名稱或符號，搜尋該代幣在多個鏈上的平台記錄。

請求

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

路徑參數

參數	類型	必填	說明
keyword	string	是	代幣合約地址、名稱或符號（精確匹配，不區分大小寫）

匹配優先級

1. 首先嘗試將 keyword 作為合約地址進行精確匹配（不區分大小寫）
2. 若無結果，再按代幣名稱或符號進行精確匹配（不區分大小寫）

curl 範例

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

# 按合約地址搜尋
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/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
      }
    ]
  }
}

回應欄位含義與 取得代幣列表 中的 TokenItem 相同。

---

取得法幣列表

返回系統支援的法幣資訊列表。

請求

GET /price/api/v1/fiats

請求參數

無。

curl 範例

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/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

---

取得法幣匯率

根據基礎法幣代碼，返回其與其他法幣之間的匯率列表。

請求

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

路徑參數

參數	類型	必填	說明
base	string	是	基礎法幣代碼，如 USD、CNY

注意： base 參數大小寫不敏感，服務端會自動轉為大寫處理。

curl 範例

# 取得以 USD 為基準的所有法幣匯率
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/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。

---

DEX 流動性池查詢

本模組提供 DEX 流動性池的精確查詢能力，適用於：

• 根據鏈資訊和 pool 合約地址查詢單筆流動性池詳情
• 查看池子的價格、交易量與流動性深度
• 監控鏈上即時交易活躍度

---

查詢流動性池

根據鏈類型、鏈 ID 和 pool 合約地址查詢單筆 DEX 流動性池詳情。

請求

GET /price/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/price/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/price/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/price/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://example.com/weth.png"
    },
    "quote_token": {
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "name": "USD Coin",
      "symbol": "USDC",
      "image_url": "https://example.com/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	Pool 唯一標識，格式為 {network}_{pool_address}
name	string	Pool 名稱，如 WETH / USDC 0.05%
address	string	Pool 合約地址
network	string	所在網路標識
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": ""
}

// 服務內部查詢失敗（HTTP 503）
{
  "code": 30001,
  "msg": "Failed to fetch pool data",
  "data": ""
}

---

即時協定與 WebSocket

目前版本僅提供 HTTP/JSON API，不提供 WebSocket、SSE 或其他長連線即時協定。

項目	目前支援情況	說明
WebSocket 升級路徑	不支援	無 ws:// / wss:// 入口，無 HTTP Upgrade 處理
協定常量	無	無訂閱、取消訂閱、頻道、事件類型等常量
客戶端傳送訊息結構	無	不存在 WS 請求幀、訂閱幀或心跳幀
服務端推送訊息結構	無	不存在 WS 回應幀、錯誤幀或行情推送幀
心跳與重連	無	請使用 HTTP 介面按需輪詢

如需取得近即時價格，推薦輪詢 GET /price/api/v1/quotes/latest。該介面成功回應帶有 Cache-Control: public, max-age=3, s-maxage=3，客戶端可按業務需求結合快取頭控制輪詢頻率。

---

文件版本：v1.2.0 | 最後更新：2026-04-28