### Example API Request URL

Source: https://docs.gelabs.org/docs/token-price/intro

An example of a full request path for querying supported chains.

```text
https://api.gelabs.org/price/api/v1/chains
```

--------------------------------

### Batch Price Query cURL Example

Source: https://docs.gelabs.org/docs/token-price/api-reference

Example of how to perform the batch price query using the cURL command-line tool.

```bash
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"
  }'
```

--------------------------------

### SSE Quote Request Example

Source: https://docs.gelabs.org/docs/any2any/integrator-quote-and-order

A cURL example for requesting quotes via the SSE endpoint.

```bash
curl -N \
  "https://<host>/api/v2/quote/stream?src_token_id=1&dst_token_id=2&amount_in=1000000&slippage=0.01"
```

--------------------------------

### Successful Response Example

Source: https://docs.gelabs.org/docs/token-price/intro

A sample JSON response indicating a successful operation.

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

--------------------------------

### Get Chain List Response

Source: https://docs.gelabs.org/docs/token-price/api-reference

Example JSON response for a successful chain list retrieval.

```json
{
  "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"
      }
    ]
  }
}
```

--------------------------------

### Failed Response Example

Source: https://docs.gelabs.org/docs/token-price/intro

A sample JSON response indicating a business-level error.

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

--------------------------------

### Subscription Request and Response

Source: https://docs.gelabs.org/docs/k-line/api-reference

Example of subscribing to a specific liquidity pool and the successful confirmation response.

```json
{

  "id": "sub-001",

  "type": "subscribe",

  "data": {

    "chain_type": "evm",

    "chain_id": 1,

    "pool_address": "0xabc123def456",

    "intervals": ["1m", "1h", "4h"]

  }

}
```

```json
{

  "id": "sub-001",

  "time": 1776682800000,

  "type": "subscribed",

  "code": 0,

  "data": {

    "key": "evm:1:0xabc123def456:base",

    "token": "base",

    "intervals": ["1m", "1h", "4h"]

  },

  "msg": "ok"

}
```

--------------------------------

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

Source: https://docs.gelabs.org/docs/token-price/api-reference

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

```APIDOC
## GET /price/api/v1/fiats/rates/{base}

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

### Method
GET

### Endpoint
/price/api/v1/fiats/rates/{base}

### Parameters
#### Path Parameters
- **base** (string) - Required - 基礎法幣代碼，如 USD、CNY。注意：參數大小寫不敏感。

### Response
#### Success Response (200)
- **code** (integer) - 狀態碼
- **msg** (string) - 訊息
- **data** (object) - 匯率資料
  - **total** (integer) - 總筆數
  - **items** (array) - 匯率列表
    - **target_fiat_id** (integer) - 目標法幣系統內部 ID
    - **target_fiat_code** (string) - 目標法幣代碼
    - **rate** (string) - 匯率值，精度為 8 位小數的字串格式

#### Response Example
{
  "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"
      }
    ]
  }
}
```

--------------------------------

### GET /price/api/v1/chains

Source: https://docs.gelabs.org/docs/token-price/api-reference

Retrieves a list of all blockchains currently supported by the system.

```APIDOC
## GET /price/api/v1/chains

### Description
Returns a list of all blockchain basic information supported by the system.

### Method
GET

### Endpoint
/price/api/v1/chains

### Response
#### Success Response (200)
- **code** (integer) - Status code (0 for success)
- **msg** (string) - Status message
- **data** (object) - Contains total count and items list

#### Response Example
{
  "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"
      }
    ]
  }
}
```

--------------------------------

### Get Chain List Request

Source: https://docs.gelabs.org/docs/token-price/api-reference

Retrieves all supported blockchain information.

```http
GET /price/api/v1/chains
```

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

--------------------------------

### Successful Response Example

Source: https://docs.gelabs.org/docs/token-price/api-reference

The structure of a successful API response containing token market data.

```json
{
  "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
      }
    ]
  }
}
```

--------------------------------

### Token List Query Examples

Source: https://docs.gelabs.org/docs/token-price/api-reference

Various curl commands to fetch token lists, including paginated results, native coins, and specific contract lookups.

```bash
# 取得第 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"
```

--------------------------------

### GET /price/api/v1/pools

Source: https://docs.gelabs.org/docs/token-price/api-reference

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

```APIDOC
## GET /price/api/v1/pools

### Description
根據鏈類型、鏈 ID 和 pool 合約地址查詢單筆 DEX 流動性池詳情。本介面結果快取 1 小時。

### Method
GET

### Endpoint
/price/api/v1/pools

### Parameters
#### Query Parameters
- **chain_type** (string) - Required - 鏈類型。標準值：evm、svm、tvm、utxo、cosmos、move。支援別名：ethereum→evm、solana→svm、tron→tvm、bitcoin/litecoin/dogecoin/bitcoin cash→utxo、sui/aptos→move
- **chain_id** (string) - Required - 鏈協定 ID，對應 blockchains 表中的 chain_id 欄位
- **pool_address** (string) - Required - Pool 合約地址

### Response
#### Success Response (200)
- **code** (integer) - 狀態碼
- **msg** (string) - 訊息
- **data** (object) - 流動性池詳細資料，若未找到則為 null

#### Response Example
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": "eth_0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
    "name": "WETH / USDC 0.05%",
    "address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
    "network": "eth",
    "dex": "uniswap_v3",
    "base_token_price_usd": "3653.12",
    "reserve_in_usd": "163988541.38"
  }
}
```

--------------------------------

### 查詢流動性池 API 端點

Source: https://docs.gelabs.org/docs/token-price/api-reference

使用 GET 請求獲取指定流動性池的詳細資訊。

```http
GET /price/api/v1/pools
```

--------------------------------

### Unsubscription Request and Response

Source: https://docs.gelabs.org/docs/k-line/api-reference

Example of unsubscribing from a liquidity pool and the confirmation response.

```json
{

  "id": "unsub-001",

  "type": "unsubscribe",

  "data": {

    "chain_type": "evm",

    "chain_id": 1,

    "pool_address": "0xabc123def456"

  }

}
```

```json
{

  "id": "unsub-001",

  "time": 1776682800000,

  "type": "unsubscribed",

  "code": 0,

  "data": {

    "key": "evm:1:0xabc123def456:",

    "removed_keys": ["evm:1:0xabc123def456:base"]

  },

  "msg": "ok"

}
```

--------------------------------

### Error Response Example

Source: https://docs.gelabs.org/docs/k-line/api-reference

The JSON structure returned when request parameters are missing or invalid.

```json
{
  "code": 10001,
  "message": "Invalid query params",
  "error": {
    "type": "ValidationError",
    "details": {
      "fieldErrors": {
        "interval": ["Required"],
        "pool_address": ["Required"]
      }
    }
  }
}
```

--------------------------------

### GET /price/api/v1/fiats

Source: https://docs.gelabs.org/docs/token-price/api-reference

Retrieve a list of fiat currencies supported by the system.

```APIDOC
## GET /price/api/v1/fiats

### Description
Returns a list of fiat currency information supported by the system.

### Method
GET

### Endpoint
/price/api/v1/fiats

### Response
#### Success Response (200)
- **code** (integer) - Status code
- **msg** (string) - Status message
- **data** (object) - Response data containing total and items list
```

--------------------------------

### Query Chain by ID or Name Response

Source: https://docs.gelabs.org/docs/token-price/api-reference

Example JSON response for a successful single chain query.

```json
{
  "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"
      }
    ]
  }
}
```

--------------------------------

### Get Fiat Currency List

Source: https://docs.gelabs.org/docs/token-price/api-reference

Retrieve a list of all fiat currencies supported by the system.

```http
GET /price/api/v1/fiats
```

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

```json
{
  "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
      }
    ]
  }
}
```

--------------------------------

### SSE Quote Response Example

Source: https://docs.gelabs.org/docs/any2any/integrator-quote-and-order

A sample response stream containing channel quotes, errors, and completion events.

```text
event: channel
data: {"channel_id":101,"name":"Channel A","symbol":"USDT","channel_icon":"https://.../a.png","estimated_out_str":"999500000","estimated_out_usd":"999.500000","channel_fee":0.3,"channel_fee_original":0.3,"promo_applied":false,"discount_pct":null}

event: channel
data: {"channel_id":102,"name":"Channel B","symbol":"USDT","channel_icon":"https://.../b.png","estimated_out_str":"999200000","estimated_out_usd":"999.200000","channel_fee":0.3,"channel_fee_original":0.3,"promo_applied":false,"discount_pct":null}

event: error
data: {"channel_id":103,"msg":"upstream timeout"}

event: done
data: {}
```

--------------------------------

### Successful Quote Response

Source: https://docs.gelabs.org/docs/token-price/api-reference

Example JSON response containing market data for requested tokens.

```json
{

  "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"

      }

    ]

  }

}
```

--------------------------------

### Token List Success Response

Source: https://docs.gelabs.org/docs/token-price/api-reference

Example JSON response structure for a successful token list query.

```json
{

  "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

      }

    ]

  }

}
```

--------------------------------

### GET /kline/api/v1/kline/ws

Source: https://docs.gelabs.org/docs/k-line/quick-start

Establishes a WebSocket connection for real-time K-line data updates.

```APIDOC
## GET /kline/api/v1/kline/ws

### Description
Establishes a WebSocket connection to subscribe to real-time K-line data pushes.

### Method
GET

### Endpoint
https://api.gelabs.org/kline/api/v1/kline/ws
```

--------------------------------

### GET /kline/api/v1/ws/{topic}

Source: https://docs.gelabs.org/docs/k-line/api-reference

Establishes a WebSocket connection for connectivity testing and basic ping/pong messaging. This endpoint is intended for validation purposes rather than real-time market data.

```APIDOC
## GET /kline/api/v1/ws/{topic}

### Description
Establishes a WebSocket connection for connectivity testing and basic ping/pong messaging. The `topic` parameter serves as the Durable Object instance name.

### Method
GET

### Endpoint
/kline/api/v1/ws/{topic}

### Parameters
#### Path Parameters
- **topic** (string) - Required - The Durable Object instance name.

### Request Example
{ "id": "req-001", "type": "ping", "data": {} }

### Response
#### Success Response (200)
- **id** (string) - Request identifier
- **time** (number) - Unix timestamp in milliseconds
- **type** (string) - Response type (e.g., "pong")
- **code** (number) - Status code (0 for success)
- **data** (object) - Response data
- **msg** (string) - Status message
```

--------------------------------

### Heartbeat Ping and Pong

Source: https://docs.gelabs.org/docs/k-line/api-reference

Example of a client heartbeat request and the corresponding server response.

```json
{ "id": "hb-001", "type": "ping", "data": {} }
```

```json
{

  "id": "hb-001",

  "time": 1776682800000,

  "type": "pong",

  "code": 0,

  "data": {},

  "msg": "ok"

}
```

--------------------------------

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

Source: https://docs.gelabs.org/docs/token-price/api-reference

Search for token platform records across multiple chains using a contract address, name, or symbol.

```APIDOC
## GET /price/api/v1/tokens/platforms/{keyword}

### Description
Search for token platform records across multiple chains using a contract address, name, or symbol. Matching priority: 1. Contract address, 2. Token name or symbol.

### Method
GET

### Endpoint
/price/api/v1/tokens/platforms/{keyword}

### Parameters
#### Path Parameters
- **keyword** (string) - Required - Token contract address, name, or symbol (exact match, case-insensitive)

### Response
#### Success Response (200)
- **code** (integer) - Status code
- **msg** (string) - Status message
- **data** (object) - Response data containing total and items list
```

--------------------------------

### Error Response for Missing Parameters

Source: https://docs.gelabs.org/docs/token-price/api-reference

Example JSON response when the required 'ids' parameter is omitted.

```json
{

  "code": 20001,

  "msg": "ids is required",

  "data": ""

}
```

--------------------------------

### GET /kline/api/v1/market/pools/{network}/{address}

Source: https://docs.gelabs.org/docs/k-line/api-reference

Retrieves detailed market information for a specific liquidity pool.

```APIDOC
## GET /kline/api/v1/market/pools/{network}/{address}

### Description
Retrieves detailed market information for a specific liquidity pool.

### Method
GET

### Endpoint
/kline/api/v1/market/pools/{network}/{address}

### Parameters
#### Path Parameters
- **network** (string) - Required - 網路標識符，1-100 字元
- **address** (string) - Required - 池合約地址，1-200 字元

#### Query Parameters
- **include** (string) - Optional - 額外包含的欄位，逗號分隔
- **include_volume_breakdown** (string) - Optional - "true" 或 "false"
- **include_composition** (string) - Optional - "true" 或 "false"

### Request Example
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/market/pools/eth/0xabc123def456?include=base_token,quote_token&include_volume_breakdown=true&include_composition=false"

### Response
#### Success Response (200)
- **data** (object) - Market data for the pool

#### Response Example
{
  "code": 99001,
  "message": "Internal server error",
  "error": { "type": "InternalServerError" }
}
```

--------------------------------

### GET /price/api/v1/tokens

Source: https://docs.gelabs.org/docs/token-price/api-reference

Retrieves a list of tokens based on the provided query parameters. Supports paginated lists, native coin lookup, and specific token lookup by address.

```APIDOC
## GET /price/api/v1/tokens

### Description
Queries system token information. Supports three modes: paginated full list, native coin lookup for a specific chain, or precise lookup by chain ID and contract address.

### Method
GET

### Endpoint
/price/api/v1/tokens

### Parameters
#### Query Parameters
- **chain_id** (string) - Optional - The system internal ID of the chain to limit the query scope.
- **address** (string) - Optional - The token contract address, typically used in combination with chain_id.
- **page** (integer) - Optional - Page number, starting from 1. Only effective when chain_id and address are not provided.
- **limit** (integer) - Optional - Number of items per page, max 1000. Only effective when chain_id and address are not provided.

### Response
#### Success Response (200)
- **code** (integer) - Status code (0 for success).
- **msg** (string) - Status message.
- **data** (object) - Contains total, page, limit, and items array.

#### Response Example
{
  "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
      }
    ]
  }
}
```

--------------------------------

### 建立 WebSocket 連線

Source: https://docs.gelabs.org/docs/address-transfer-notify/quick-start

使用 wscat 工具建立連線以接收即時交易推送。

```bash
# 安装 wscat（如果尚未安装）  
npm install -g wscat  
  
# 建立连接  
wscat -c "$BASE_URL/tx/api/v1/transaction/ws" \
  -H "X-API-Key: $API_KEY"
```

--------------------------------

### GET /api/v2/quote/stream

Source: https://docs.gelabs.org/docs/any2any/integrator-quote-and-order

Streams quotes from the system.

```APIDOC
## GET /api/v2/quote/stream

### Description
Retrieves a stream of quotes from the system.

### Method
GET

### Endpoint
/api/v2/quote/stream
```

--------------------------------

### GET /tx/api/v1/transaction/ws

Source: https://docs.gelabs.org/docs/address-transfer-notify/quick-start

建立 WebSocket 連線以接收即時交易推送。

```APIDOC
## GET /tx/api/v1/transaction/ws

### Description
建立 WebSocket 連線開始接收即時交易推送。

### Method
GET

### Endpoint
/tx/api/v1/transaction/ws

### Response
#### Success Response (200)
- **id** (string) - 訊息ID
- **type** (string) - 訊息類型
- **data** (object) - 交易詳情或連線確認資訊

#### Response Example
{
  "id": "msg-tx-001",
  "type": "transaction",
  "data": {
    "chain_type": "ethereum",
    "txhash": "0xabc123...",
    "amount": "1000000000000000000"
  }
}
```

--------------------------------

### PUT /tx/api/v1/app/config

Source: https://docs.gelabs.org/docs/address-transfer-notify/quick-start

配置 Webhook 回呼設定。

```APIDOC
## PUT /tx/api/v1/app/config

### Description
配置 Webhook 回呼 URL 與驗證密鑰。

### Method
PUT

### Endpoint
/tx/api/v1/app/config

### Request Body
- **enable_webhook** (boolean) - Required - 是否啟用
- **webhook_url** (string) - Required - 回呼地址
- **webhook_secret** (string) - Required - 驗證密鑰

### Request Example
{
  "enable_webhook": true,
  "webhook_url": "https://example.com/tx-history/webhook",
  "webhook_secret": "replace-with-shared-secret"
}
```

--------------------------------

### 新增監聽地址

Source: https://docs.gelabs.org/docs/address-transfer-notify/quick-start

將錢包地址加入監聽名單，支援單一或多鏈地址批次新增。

```bash
curl -X POST "$BASE_URL/tx/api/v1/addresses" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "wallets": [
      {
        "chain_type": "ethereum",
        "address": ["0x1234567890abcdef1234567890abcdef12345678"]
      }
    ]
  }'
```

```bash
curl -X POST "$BASE_URL/tx/api/v1/addresses" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "wallets": [
      {
        "chain_type": "ethereum",
        "address": ["0xabc...001", "0xabc...002"]
      },
      {
        "chain_type": "solana",
        "address": ["So1ana...address"]
      }
    ]
  }'
```

--------------------------------

### Fetch Prices in Alternative Fiat

Source: https://docs.gelabs.org/docs/token-price/quick-start

Specify a different fiat currency for price quotes using the fiat parameter.

```bash
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/quotes/latest?ids=1,1027&fiat=CNY"
```

--------------------------------

### 查詢流動性池 cURL 範例

Source: https://docs.gelabs.org/docs/token-price/api-reference

透過 cURL 請求查詢不同鏈上的流動性池資訊，需在 Header 中提供 API Key。

```bash
# 查詢以太坊主網上指定 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>"
```

--------------------------------

### Define Base URL

Source: https://docs.gelabs.org/docs/token-price/intro

The root path for all production environment API requests.

```text
https://api.gelabs.org
```

--------------------------------

### GET /kline/api/v1/kline/ohlcv

Source: https://docs.gelabs.org/docs/k-line/quick-start

Retrieves historical K-line (OHLCV) data for a specific pool.

```APIDOC
## GET /kline/api/v1/kline/ohlcv

### Description
Loads initial candle chart data for a specified pool.

### Method
GET

### Endpoint
https://api.gelabs.org/kline/api/v1/kline/ohlcv

### Parameters
#### Query Parameters
- **interval** (string) - Required - The time interval for candles (e.g., 1h)
- **from** (integer) - Required - Start timestamp
- **to** (integer) - Required - End timestamp
- **limit** (integer) - Required - Maximum number of records
- **chain_type** (string) - Required - The chain type (e.g., evm)
- **chain_id** (integer) - Required - The chain ID
- **pool_address** (string) - Required - The address of the liquidity pool

### Request Example
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/kline/ohlcv?interval=1h&from=1776679200&to=1776765600&limit=500&chain_type=evm&chain_id=1&pool_address=0xabc123def456"
```

--------------------------------

### 配置 Webhook 回呼

Source: https://docs.gelabs.org/docs/address-transfer-notify/quick-start

設定 Webhook URL 以接收交易結果推送，並包含相關的請求標頭與重試管理。

```bash
curl -X PUT "$BASE_URL/tx/api/v1/app/config" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "enable_webhook": true,
    "webhook_url": "https://example.com/tx-history/webhook",
    "webhook_secret": "replace-with-shared-secret"
  }'
```

```text
Content-Type: application/json  
Sign: replace-with-shared-secret  
```

```bash
curl "$BASE_URL/tx/api/v1/app/webhook/retry/status" \
  -H "X-API-Key: $API_KEY"
```

```bash
curl -X POST "$BASE_URL/tx/api/v1/app/webhook/retry" \
  -H "X-API-Key: $API_KEY"
```

--------------------------------

### GET /price/api/v1/chains/{id_or_name}

Source: https://docs.gelabs.org/docs/token-price/api-reference

Retrieves details for a specific blockchain by its numeric ID or name.

```APIDOC
## GET /price/api/v1/chains/{id_or_name}

### Description
Returns information for a single blockchain based on its numeric ID or name.

### Method
GET

### Endpoint
/price/api/v1/chains/{id_or_name}

### Parameters
#### Path Parameters
- **id_or_name** (string) - Required - The numeric ID (e.g., 1) or name (e.g., Ethereum) of the chain.

### Response
#### Success Response (200)
- **code** (integer) - Status code (0 for success)
- **msg** (string) - Status message
- **data** (object) - Contains the chain details

#### Response Example
{
  "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"
      }
    ]
  }
}
```

--------------------------------

### GET /kline/api/v1/market/coins/{network}/{address}

Source: https://docs.gelabs.org/docs/k-line/api-reference

Retrieves token metadata using the contract address.

```APIDOC
## GET /kline/api/v1/market/coins/{network}/{address}

### Description
Retrieves token metadata using the contract address.

### Method
GET

### Endpoint
/kline/api/v1/market/coins/{network}/{address}

### Parameters
#### Path Parameters
- **network** (string) - Required - 平台標識符，1-100 字元
- **address** (string) - Required - 代幣合約地址，1-200 字元

### Request Example
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/market/coins/ethereum/0xabc123def456"

### Response
#### Success Response (200)
- **data** (object) - Token metadata

#### Response Example
{
  "code": 99001,
  "message": "Internal server error",
  "error": { "type": "InternalServerError" }
}
```

--------------------------------

### GET /kline/api/v1/market/tokens/{network}/{address}/top-holders

Source: https://docs.gelabs.org/docs/k-line/api-reference

Retrieves the top holders for a specific token.

```APIDOC
## GET /kline/api/v1/market/tokens/{network}/{address}/top-holders

### Description
Retrieves the top holders for a specific token.

### Method
GET

### Endpoint
/kline/api/v1/market/tokens/{network}/{address}/top-holders

### Parameters
#### Path Parameters
- **network** (string) - Required - 網路標識符，1-100 字元
- **address** (string) - Required - 代幣合約地址，1-200 字元

#### Query Parameters
- **holders** (string) - Optional - 正整數字串或 "max"
- **include_pnl_details** (string) - Optional - "true" 或 "false"

### Request Example
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/market/tokens/eth/0xabc123def456/top-holders?holders=10&include_pnl_details=false"

### Response
#### Success Response (200)
- **data** (object) - Top holders data

#### Response Example
{
  "code": 99001,
  "message": "Internal server error",
  "error": { "type": "InternalServerError" }
}
```

--------------------------------

### Common Error Responses

Source: https://docs.gelabs.org/docs/token-price/api-reference

Examples of error responses returned when the request body is invalid or empty.

```json
// token_addrs 为空数组  
{
  "code": 20003,
  "msg": "token_addrs is required",
  "data": ""
}
  
// 請求體 JSON 格式錯誤  
{
  "code": 20003,
  "msg": "invalid JSON body",
  "data": ""
}
```

--------------------------------

### 設定環境變數

Source: https://docs.gelabs.org/docs/address-transfer-notify/quick-start

定義基礎 URL 與 API 金鑰以供後續請求使用。

```bash
BASE_URL=https://api.gelabs.org  

API_KEY=your-api-key  

```

--------------------------------

### Fetch Latest Token Prices

Source: https://docs.gelabs.org/docs/token-price/quick-start

Retrieve the latest USD prices for specific tokens using their internal IDs.

```bash
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/quotes/latest?ids=1,1027"
```

--------------------------------

### Create Integrator Order Request

Source: https://docs.gelabs.org/docs/any2any/integrator-quote-and-order

The request body for creating an order, including token details, channel selection, and optional metadata.

```http
POST /api/v1/integrator/orders HTTP/1.1

Content-Type: application/json

X-Integrator-Api-Key: <api_key>
```

```json
{
  "src_token_id": 1,
  "dst_token_id": 2,
  "amount_in": "1000000",
  "dst_address": "0xRecipientAddress...",
  "chosen_channel_id": 101,
  "slippage": 0.01,
  "main_channel_estimated_out_amount": "999500000",
  "min_acceptable_out_amount": "989505000",
  "channels": [
    {
      "channel_id": 101,
      "estimated_out_str": "999500000",
      "name": "Channel A",
      "symbol": "USDT",
      "channel_icon": "https://.../a.png",
      "estimated_out_usd": "999.500000",
      "channel_fee": 0.3
    },
    {
      "channel_id": 102,
      "estimated_out_str": "999200000",
      "name": "Channel B"
    }
  ],
  "client_order_id": "your-internal-order-no-001",
  "promo_code": "WELCOME"
}
```

--------------------------------

### GET /kline/api/v1/kline/ohlcv

Source: https://docs.gelabs.org/docs/k-line/api-reference

Retrieves historical OHLCV candle data for a specified pool, chain, and time interval.

```APIDOC
## GET /kline/api/v1/kline/ohlcv

### Description
Queries historical OHLCV candle data for a specific liquidity pool. This is used for rendering historical K-line charts and filling data gaps.

### Method
GET

### Endpoint
/kline/api/v1/kline/ohlcv

### Parameters
#### Query Parameters
- **interval** (string) - Required - K-line period: 1s, 1m, 15m, 1h, 4h, 1d, 1w, 1M, 1Y
- **from** (integer) - Required - Start time in Unix seconds or milliseconds
- **to** (integer) - Required - End time in Unix seconds or milliseconds
- **limit** (integer) - Optional - Max records to return (1-5000), default 1000
- **chain_type** (string) - Required - Chain type
- **chain_id** (integer) - Required - Chain ID
- **pool_address** (string) - Required - Pool contract address

### Request Example
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/kline/ohlcv?interval=1h&from=1776679200&to=1776765600&limit=500&chain_type=evm&chain_id=1&pool_address=0xabc123def456"

### Response
#### Success Response (200)
- **code** (integer) - Status code
- **message** (string) - Status message
- **data** (array) - List of OHLCV objects

#### Response Example
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "pool_id": 42,
      "interval": "1h",
      "open_time": 1776679200,
      "open": 3500.12,
      "high": 3520,
      "low": 3480.5,
      "close": 3510.88,
      "volume": 1234567.89
    }
  ]
}
```

--------------------------------

### Query Pool Market Details

Source: https://docs.gelabs.org/docs/k-line/api-reference

Retrieves detailed information for a specific liquidity pool. Requires network and contract address as path parameters.

```http
GET /kline/api/v1/market/pools/{network}/{address}
```

```shell
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/market/pools/eth/0xabc123def456?include=base_token,quote_token&include_volume_breakdown=true&include_composition=false"
```

--------------------------------

### POST /api/v1/integrator/orders

Source: https://docs.gelabs.org/docs/any2any/integrator-quote-and-order

Places an order as an integrator.

```APIDOC
## POST /api/v1/integrator/orders

### Description
Allows an integrator to place a new order.

### Method
POST

### Endpoint
/api/v1/integrator/orders
```

--------------------------------

### GET /price/api/v1/quotes/latest

Source: https://docs.gelabs.org/docs/token-price/api-reference

Retrieves the latest token price. This endpoint supports HTTP caching via Cache-Control headers.

```APIDOC
## GET /price/api/v1/quotes/latest

### Description
Retrieves the latest token price information. Clients are recommended to poll this endpoint for near real-time data, utilizing the provided Cache-Control headers to manage polling frequency.

### Method
GET

### Endpoint
/price/api/v1/quotes/latest

### Response
#### Success Response (200)
- **Cache-Control** (header) - public, max-age=3, s-maxage=3
```

--------------------------------

### Batch Fetch Latest Token Quotes

Source: https://docs.gelabs.org/docs/token-price/api-reference

Retrieve market data for multiple tokens using their internal IDs. Requires an API key in the request header.

```bash
# 查詢 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"
```

--------------------------------

### GET /api/v2/quote/stream

Source: https://docs.gelabs.org/docs/any2any/integrator-quote-and-order

Establishes a Server-Sent Events (SSE) connection to stream quotes for a specific token pair and amount.

```APIDOC
## GET /api/v2/quote/stream

### Description
Retrieves a stream of quotes for a token swap request. The server pushes 'channel' events containing quote data and a 'done' event when the stream is complete.

### Method
GET

### Endpoint
/api/v2/quote/stream

### Parameters
#### Query Parameters
- **src_token_id** (string) - Required - The source token identifier.
- **dst_token_id** (string) - Required - The destination token identifier.
- **amount_in** (string) - Required - The amount of source tokens to swap.
- **slippage** (string) - Required - The maximum acceptable slippage percentage.

### Response
#### Success Response (200)
- **estimated_out_str** (string) - The net amount of destination tokens received after fees and discounts.
```

--------------------------------

### Generic WebSocket Endpoint

Source: https://docs.gelabs.org/docs/k-line/api-reference

The base path for establishing a WebSocket connection where the topic serves as the Durable Object instance name.

```text
GET /kline/api/v1/ws/{topic}
```

--------------------------------

### Base URL Configuration

Source: https://docs.gelabs.org/docs/any2any/integrator-quote-and-order

The base URL for all API requests.

```text
https://<aggregator-api-host>
```