Token Price API — API reference

Chain information

This module provides basic blockchain information for supported chains. Use it to:

Display the list of chains supported by the platform
Resolve chain configuration by chain name or ID, including icons and explorer links

List chains

Returns basic information for all blockchains currently supported by the system.

Request

GET /price/api/v1/chains

Request parameters

None.

curl example

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

Successful 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"
      },
      {
        "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"
      }
    ]
  }
}

Response fields (data.items[])

Field	Type	Always returned	Description
`id`	integer	Yes	Internal primary key ID for the chain
`name`	string	Yes	Chain name, such as `Ethereum`
`short_name`	string	Yes	Chain short name, such as `eth`
`chain_id`	integer	No	Protocol-level chain ID. EVM chains usually have this field
`chain_type`	string	No	Chain type, such as `evm`, `svm`, `tvm`, `utxo`, `cosmos`, or `move`
`chain_icon_url`	string	No	Chain icon URL
`explorer_url`	string	No	Chain block explorer URL

Get chain by ID or name

Returns a single chain by numeric ID or chain name.

Request

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

Path parameters

Parameter	Type	Required	Description
`id_or_name`	string	Yes	Chain numeric ID, such as `1`, or chain name, such as `Ethereum`

curl example

# Query by numeric ID
curl -H "X-API-Key: $API_KEY" https://api.gelabs.org/price/api/v1/chains/1

# Query by chain name
curl -H "X-API-Key: $API_KEY" https://api.gelabs.org/price/api/v1/chains/Ethereum

Successful 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"
      }
    ]
  }
}

Response when not found

Note: When a chain is not found, the HTTP status code is still 200. The failure is indicated by business code 20002.

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

Token quote queries

This module provides real-time token quote capabilities with two query modes:

By token ID: suitable when you already know the system's internal token IDs. Returns quote data with full market fields.
By contract address: suitable when you know the chain and contract address. Returns chain-specific price data.

Batch latest quotes

Gets latest quotes in batch by token ID list, with optional target fiat.

Request

GET /price/api/v1/quotes/latest

Query parameters

Parameter	Type	Required	Default	Description
`ids`	string	Yes	—	Token ID list. Separate multiple values with commas, such as `1,1027,825`
`fiat`	string	No	`USD`	Target fiat code, such as `USD` or `CNY`. Defaults to `USD` when omitted

curl example

# Query USD quotes for BTC (id=1) and ETH (id=1027)
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/quotes/latest?ids=1,1027"

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

Caching

Successful responses from this endpoint include the following cache header, allowing clients and CDNs to cache for 3 seconds:

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

Successful response example

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

Response fields (data.items[])

Field	Type	Description
`token_id`	integer	Internal token ID
`name`	string	Token name
`symbol`	string	Token symbol
`fiat_id`	integer	Internal fiat ID for the quote currency
`fiat_code`	string	Quote fiat code, such as `USD`
`price`	string	Current price as a string
`market_cap`	string	Market capitalization as a string
`volume_24h`	string	24-hour volume as a string
`volume_change_24h`	string	24-hour volume change as a string
`percent_change_1h`	string	1-hour percentage change as a string
`percent_change_24h`	string	24-hour percentage change as a string
`percent_change_7d`	string	7-day percentage change as a string
`percent_change_30d`	string	30-day percentage change as a string
`fully_diluted_valuation`	string	Fully diluted valuation as a string
`circulating_supply`	string	Circulating supply as a string
`total_supply`	string	Total supply as a string
`max_supply`	string	Maximum supply as a string

Note: All price, market-cap, supply, and similar numeric fields in this endpoint are strings. Parse them into numbers in your own application as needed.

Error response when ids is missing

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

Batch prices by contract address

Returns token price information in batch by chain type, chain ID, and token contract address. This is suitable when you know on-chain addresses and need to locate token prices precisely at the chain level.

Request

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

Request body

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

Request body fields

Field	Type	Required	Description
`token_addrs`	array	Yes	Array of token addresses to query. Must not be empty
`token_addrs[].chain_type`	string	Yes	Chain type. Standard values are `evm`, `svm`, `tvm`, `utxo`, `cosmos`, and `move`. Aliases such as `ethereum`, `solana`, and `tron` are also normalized automatically
`token_addrs[].chain_id`	integer	No	Protocol chain ID. Required for EVM chains, such as `1` for Ethereum mainnet. Other chains may use `null`
`token_addrs[].token_address`	string	Yes	Token contract address or on-chain identifier
`fiat`	string	No	Target fiat code. Defaults to `USD`; the current underlying processing is mainly based on USD prices

curl example

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

Successful response example

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

Response fields (data.items[])

Field	Type	Description
`token_id`	integer	Internal token ID
`name`	string	Token name
`symbol`	string	Token symbol
`chain_type`	string	Chain type
`chain_id`	integer	Protocol chain ID
`address`	string	Token address
`external_id`	string	Extended token identifier
`price_usd`	number	USD price as a number
`market_cap_usd`	number	USD market capitalization as a number
`volume_24h_usd`	number	24-hour volume in USD as a number
`percent_change_1h`	number	1-hour percentage change as a number
`percent_change_24h`	number	24-hour percentage change as a number
`percent_change_7d`	number	7-day percentage change as a number
`percent_change_30d`	number	30-day percentage change as a number
`last_updated`	string	Last update time in ISO 8601 format
`market_cap`	number	Market capitalization as a number
`fully_diluted_valuation`	number	Fully diluted valuation as a number
`total_volume`	number	Total volume as a number
`circulating_supply`	number	Circulating supply as a number
`total_supply`	number	Total supply as a number
`max_supply`	number	Maximum supply as a number

Difference from /price/api/v1/quotes/latest: price, market-cap, and similar numeric fields in this endpoint are numbers, while /price/api/v1/quotes/latest returns strings.

Common error responses

// token_addrs is an empty array
{
  "code": 20003,
  "msg": "token_addrs is required",
  "data": ""
}

// Request body JSON is malformed
{
  "code": 20003,
  "msg": "invalid JSON body",
  "data": ""
}

Asset information

This module provides basic token and fiat asset information. Use it to:

Build token selectors and search boxes
Display cross-chain platform distribution for a token
Get fiat currency lists and real-time exchange rates

List tokens

Queries token information in the system. Three query modes are supported. The full list supports pagination, and a single request returns at most 1000 items.

Request

GET /price/api/v1/tokens

Query parameters

Parameter	Type	Required	Default	Description
`chain_id`	string	No	—	Internal chain ID used to limit the query scope
`address`	string	No	—	Token contract address. Usually used together with `chain_id`
`page`	integer	No	`1`	Page number starting from `1`. Only applies when neither `chain_id` nor `address` is provided
`limit`	integer	No	`100`	Items per page, maximum `1000`. Only applies when neither `chain_id` nor `address` is provided

Query modes

Parameter combination	Behavior
No parameters	Returns a paginated list of active tokens, controlled by `page` and `limit`
Only `chain_id`	Attempts to return the chain's native token without pagination
Both `chain_id` and `address`	Performs an exact match for one token by chain ID and contract address, without pagination

curl example

# Get the first page of tokens, defaulting to 100 items per page
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/tokens"

# Paginated query: page 2, 200 items per page
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/tokens?page=2&limit=200"

# Get native ETH on Ethereum (chain_id=1)
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/tokens?chain_id=1"

# Exact query for USDC by chain and contract address
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/tokens?chain_id=1&address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

Successful response example (full paginated list)

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

Top-level response fields (data)

Field	Type	Description
`total`	integer	Total number of tokens matching the condition
`page`	integer	Current page number. In exact query mode, this is fixed to `1`
`limit`	integer	Page size for this request. In exact query mode, this equals the number of returned items
`items`	array	Token list for the current page

Response fields (data.items[])

Field	Type	Always returned	Description
`id`	integer	Yes	Internal token ID
`name`	string	Yes	Token name
`symbol`	string	Yes	Token symbol
`decimals`	integer	Yes	Token precision, in decimal places
`logo_url`	string	No	Token icon URL
`chain_id`	integer	Yes	Internal ID of the chain the token belongs to
`chain_name`	string	Yes	Name of the chain the token belongs to
`contract_address`	string	No	Token contract address. Native tokens do not return this field
`is_native`	boolean	Yes	Whether this is the chain's native token, such as ETH or SOL

Pagination example: To fetch all data, calculate the total page count from total and limit, then request each page in sequence:
total_pages = Math.ceil(total / limit), then loop from page=1 to page=total_pages.

Search token platform records

Searches for a token's platform records across multiple chains by contract address, name, or symbol.

Request

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

Path parameters

Parameter	Type	Required	Description
`keyword`	string	Yes	Token contract address, name, or symbol. Matching is exact and case-insensitive

Matching priority

First, try to match keyword exactly as a contract address, case-insensitively.
If no result is found, match exactly by token name or symbol, case-insensitively.

curl example

# Search platform distribution for USDC by symbol
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/tokens/platforms/USDC"

# Search by contract address
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/tokens/platforms/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

Successful response example

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

The response fields have the same meaning as the TokenItem fields in List tokens.

List fiat currencies

Returns the fiat currencies supported by the system.

Request

GET /price/api/v1/fiats

Request parameters

None.

curl example

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

Successful response example

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

Response fields (data.items[])

Field	Type	Always returned	Description
`id`	integer	Yes	Internal fiat ID
`code`	string	Yes	Fiat code, such as `USD` or `CNY`
`name`	string	Yes	Fiat name
`symbol`	string	Yes	Fiat symbol, such as `$` or `¥`. Returns an empty string when not configured
`icon_url`	string	No	Fiat icon URL
`precision`	integer	Yes	Display precision in decimal places. Defaults to `2` when not configured

Fiat exchange rates

Returns exchange rates between the base fiat code and other fiat currencies.

Request

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

Path parameters

Parameter	Type	Required	Description
`base`	string	Yes	Base fiat code, such as `USD` or `CNY`

Note: The base parameter is case-insensitive. The server converts it to uppercase automatically.

curl example

# Get all fiat exchange rates based on USD
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/fiats/rates/USD"

Successful 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"
      }
    ]
  }
}

Response fields (data.items[])

Field	Type	Description
`target_fiat_id`	integer	Internal ID of the target fiat
`target_fiat_code`	string	Target fiat code
`rate`	string	Exchange-rate value as a string with 8 decimal places

Description: When the queried base fiat has no exchange-rate data, the endpoint still returns a successful structure, but items is an empty array and total is 0.

DEX liquidity pool queries

This module provides exact DEX liquidity pool queries. Use it to:

Query details for a single liquidity pool by chain information and pool contract address
View pool prices, trading volume, and liquidity depth
Monitor real-time on-chain trading activity

Query a liquidity pool

Queries details for a single DEX liquidity pool by chain type, chain ID, and pool contract address.

Request

GET /price/api/v1/pools

Query parameters

Parameter	Type	Required	Description
`chain_type`	string	Yes	Chain type. Standard values: `evm`, `svm`, `tvm`, `utxo`, `cosmos`, `move`. Supported aliases: `ethereum`→`evm`, `solana`→`svm`, `tron`→`tvm`, `bitcoin`/`litecoin`/`dogecoin`/`bitcoin cash`→`utxo`, `sui`/`aptos`→`move`
`chain_id`	string	Yes	Protocol chain ID, corresponding to the `chain_id` field in the `blockchains` table, such as `1` for Ethereum mainnet
`pool_address`	string	Yes	Pool contract address

curl example

# Query a specified pool on Ethereum mainnet
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/pools?chain_type=evm&chain_id=1&pool_address=0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"

# Use a chain_type alias. ethereum is normalized to evm automatically
curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/price/api/v1/pools?chain_type=ethereum&chain_id=1&pool_address=0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"

# Query a pool on Solana. Use the corresponding chain_id value
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>"

Caching

Results from this endpoint are cached for 1 hour. The cache key is determined by chain_type, chain_id, and pool_address together.

Successful response example (data found)

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

Successful response example (data not found)

When the chain or pool does not exist, the HTTP status code is still 200 and data is null.

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

Response fields when data is not null

Field	Type	Description
`id`	string	Pool unique identifier, formatted as `{network}_{pool_address}`
`name`	string	Pool name, such as `WETH / USDC 0.05%`
`address`	string	Pool contract address
`network`	string	Network identifier
`dex`	string	DEX identifier, such as `uniswap_v3`
`pool_created_at`	string	Pool creation time in ISO 8601 format
`base_token`	object	Base token information. See below
`quote_token`	object	Quote token information. See below
`base_token_price_usd`	string	USD price of the base token as a string
`quote_token_price_usd`	string	USD price of the quote token as a string
`fdv_usd`	string / null	Fully diluted valuation in USD. `null` when unavailable
`market_cap_usd`	string / null	Market capitalization in USD. `null` when unavailable
`price_change_percentage`	object	Multi-window percentage changes. Keys are `m5`, `m15`, `m30`, `h1`, `h6`, and `h24`
`volume_usd`	object	Multi-window USD trading volume. Uses the same keys as above
`reserve_in_usd`	string	Total pool liquidity in USD as a string
`transactions`	object	Multi-window transaction statistics. Uses the same keys as above; see below

base_token / quote_token fields

Field	Type	Description
`address`	string	Token contract address
`name`	string	Token name
`symbol`	string	Token symbol
`image_url`	string	Token icon URL

transactions fields for each time window

Field	Type	Description
`buys`	integer	Number of buy trades
`sells`	integer	Number of sell trades
`buyers`	integer	Number of unique buyer addresses
`sellers`	integer	Number of unique seller addresses

Common error responses

// Missing chain_type parameter
{
  "code": 20001,
  "msg": "chain_type is required",
  "data": ""
}

// Missing chain_id parameter
{
  "code": 20001,
  "msg": "chain_id is required",
  "data": ""
}

// Missing pool_address parameter
{
  "code": 20001,
  "msg": "pool_address is required",
  "data": ""
}

// Internal query failed (HTTP 503)
{
  "code": 30001,
  "msg": "Failed to fetch pool data",
  "data": ""
}

Real-time protocols and WebSocket

The current version only provides HTTP/JSON APIs. It does not provide WebSocket, SSE, or other long-lived real-time protocols.

Item	Current support	Description
WebSocket upgrade path	Not supported	No `ws://` / `wss://` entry point and no HTTP `Upgrade` handling
Protocol constants	None	No constants for subscribe, unsubscribe, channels, or event types
Client message shape	None	No WS request frames, subscription frames, or heartbeat frames
Server push message shape	None	No WS response frames, error frames, or market-data push frames
Heartbeat and reconnect	None	Use HTTP endpoints for polling as needed

For near-real-time prices, poll GET /price/api/v1/quotes/latest. Successful responses from that endpoint include Cache-Control: public, max-age=3, s-maxage=3, so clients can control polling frequency according to business needs and the cache header.

Document version: v1.2.0 | Last updated: 2026-04-28

Chain information​

List chains​

Get chain by ID or name​

Token quote queries​

Batch latest quotes​

Batch prices by contract address​

Asset information​

List tokens​

Search token platform records​

List fiat currencies​

Fiat exchange rates​

DEX liquidity pool queries​

Query a liquidity pool​

Real-time protocols and WebSocket​

Chain information

List chains

Get chain by ID or name

Token quote queries

Batch latest quotes

Batch prices by contract address

Asset information

List tokens

Search token platform records

List fiat currencies

Fiat exchange rates

DEX liquidity pool queries

Query a liquidity pool

Real-time protocols and WebSocket