> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coingecko.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Token Data by Token Address
> This endpoint allows you to **query specific token data based on the provided token contract address on a network**
### Tips
* You may add values such as `top_pools` in the `include` param to include top pools along with the pools information.
* If you would like to query token information such as socials, websites, description, etc., you can go to this endpoint [`/networks/{network}/tokens/{address}/info`](/reference/token-info-contract-address) instead.
* Attributes specified in the `include` param will be returned under the top-level "included" key.
* Set `include_composition=true` to surface the balance and liquidity value of the pool's base and quote tokens. (requires `include=top_pools`)
* For tokens on a bonding curve (i.e. non-graduated tokens from launchpads), the response will include a `launchpad_details` object containing their graduation status and details.
### Note
* Addresses not found in GeckoTerminal will be ignored.
* The endpoint will only return the top most liquid pool for each token. The top pool is determined through a combination of two key factors: liquidity (`reserve_in_usd`) and 24-Hour Trading Volume (`volume_usd`).
* `total_reserve_in_usd` represents the total reserve of the requested token only across all its pools, not the combined reserve of both tokens in a pair.
* If the token's market cap is not verified by the team, the API response will return `null` for its market cap value, even though it has a displayed value on GeckoTerminal, which might not be accurate as it often matches the Fully Diluted Valuation (FDV).
* Market Cap can be verified by and sourced from CoinGecko, and the number may be higher than FDV as it may include Market Cap of tokens issued on other blockchain networks.
* Cache / Update Frequency: every 10 seconds for Pro API (Basic, Analyst, Lite, Pro, Enterprise).
## OpenAPI
````yaml api-reference/onchain-pro.json get /networks/{network}/tokens/{address}
openapi: 3.0.0
info:
title: Onchain DEX API (Pro)
version: 3.0.0
servers:
- url: https://pro-api.coingecko.com/api/v3/onchain
security:
- apiKeyAuth: []
- apiKeyQueryParam: []
paths:
/networks/{network}/tokens/{address}:
get:
tags:
- Tokens
summary: Token Data by Token Address
description: >-
This endpoint allows you to **query specific token data based on the
provided token contract address on a network**
operationId: token-data-contract-address
parameters:
- name: network
in: path
description: |-
network ID
*refers to [/networks](/reference/networks-list)
required: true
schema:
type: string
example: eth
default: eth
- name: address
in: path
description: token contract address
required: true
schema:
type: string
example: '0xdac17f958d2ee523a2206206994597c13d831ec7'
default: '0xdac17f958d2ee523a2206206994597c13d831ec7'
- name: include
in: query
required: false
description: attributes to include
schema:
type: string
enum:
- top_pools
- name: include_composition
in: query
required: false
description: 'include pool composition, default: false'
schema:
type: boolean
- name: include_inactive_source
in: query
required: false
description: >-
include token data from inactive pools using the most recent swap,
default: false
schema:
type: boolean
default: false
responses:
'200':
description: Get specific token on a network
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
components:
schemas:
Token:
type: object
properties:
data:
type: object
properties:
id:
type: string
type:
type: string
attributes:
type: object
properties:
address:
type: string
name:
type: string
symbol:
type: string
decimals:
type: integer
image_url:
type: string
coingecko_coin_id:
type: string
total_supply:
type: string
normalized_total_supply:
type: string
price_usd:
type: string
fdv_usd:
type: string
total_reserve_in_usd:
type: string
volume_usd:
type: object
properties:
h24:
type: string
market_cap_usd:
type: string
last_trade_timestamp:
type: integer
relationships:
type: object
properties:
top_pools:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
type:
type: string
included:
type: array
items:
type: object
properties:
id:
type: string
type:
type: string
attributes:
type: object
properties:
base_token_price_usd:
type: string
base_token_price_native_currency:
type: string
base_token_balance:
type: string
base_token_liquidity_usd:
type: string
quote_token_price_usd:
type: string
quote_token_price_native_currency:
type: string
quote_token_balance:
type: string
quote_token_liquidity_usd:
type: string
base_token_price_quote_token:
type: string
quote_token_price_base_token:
type: string
address:
type: string
name:
type: string
pool_created_at:
type: string
token_price_usd:
type: string
fdv_usd:
type: string
market_cap_usd:
type: string
price_change_percentage:
type: object
properties:
m5:
type: string
m15:
type: string
m30:
type: string
h1:
type: string
h6:
type: string
h24:
type: string
transactions:
type: object
properties:
m5:
type: object
properties:
buys:
type: integer
sells:
type: integer
buyers:
type: integer
sellers:
type: integer
m15:
type: object
properties:
buys:
type: integer
sells:
type: integer
buyers:
type: integer
sellers:
type: integer
m30:
type: object
properties:
buys:
type: integer
sells:
type: integer
buyers:
type: integer
sellers:
type: integer
h1:
type: object
properties:
buys:
type: integer
sells:
type: integer
buyers:
type: integer
sellers:
type: integer
h6:
type: object
properties:
buys:
type: integer
sells:
type: integer
buyers:
type: integer
sellers:
type: integer
h24:
type: object
properties:
buys:
type: integer
sells:
type: integer
buyers:
type: integer
sellers:
type: integer
volume_usd:
type: object
properties:
m5:
type: string
m15:
type: string
m30:
type: string
h1:
type: string
h6:
type: string
h24:
type: string
reserve_in_usd:
type: string
relationships:
type: object
properties:
base_token:
type: object
properties:
data:
type: object
properties:
id:
type: string
type:
type: string
quote_token:
type: object
properties:
data:
type: object
properties:
id:
type: string
type:
type: string
dex:
type: object
properties:
data:
type: object
properties:
id:
type: string
type:
type: string
example:
data:
id: eth_0xdac17f958d2ee523a2206206994597c13d831ec7
type: token
attributes:
address: '0xdac17f958d2ee523a2206206994597c13d831ec7'
name: Tether USD
symbol: USDT
decimals: 6
image_url: >-
https://coin-images.coingecko.com/coins/images/325/large/Tether.png?1696501661
coingecko_coin_id: tether
total_supply: '91775654692250534.0'
normalized_total_supply: '91775654692.2505'
price_usd: '0.999188255'
fdv_usd: '91700939859.6687'
total_reserve_in_usd: '405089394.14192413773442554227'
volume_usd:
h24: '1142454033.37436'
market_cap_usd: '171798403974.784'
last_trade_timestamp: 1712534400
relationships:
top_pools:
data:
- id: eth_0x667701e51b4d1ca244f17c78f7ab8744b4c99f9b
type: pool
- id: eth_0xf063bd202e45d6b2843102cb4ece339026645d4a
type: pool
- id: >-
eth_0x8aa4e11cbdf30eedc92100f4c8a31ff748e201d44712cc8c90d189edaa8e4e47
type: pool
included:
- id: eth_0x667701e51b4d1ca244f17c78f7ab8744b4c99f9b
type: pool
attributes:
base_token_price_usd: '0.999949947925521'
base_token_price_native_currency: '0.000223341206041575'
base_token_balance: '74198606.301554'
base_token_liquidity_usd: '74194892.50738515'
quote_token_price_usd: '0.99918825500163'
quote_token_price_native_currency: '0.000223171080110164'
quote_token_balance: '29771050.29628'
quote_token_liquidity_usd: '29746883.795105774'
base_token_price_quote_token: '1.0007623117'
quote_token_price_base_token: '0.9992382689'
address: '0x667701e51b4d1ca244f17c78f7ab8744b4c99f9b'
name: USDC / USDT
pool_created_at: '2025-09-18T08:28:30Z'
token_price_usd: '0.99918825500163'
fdv_usd: '91700939859.6687'
market_cap_usd: '171798403975.064'
price_change_percentage:
m5: '-0.02'
m15: '-0.65'
m30: '-0.01'
h1: '0'
h6: '-0.18'
h24: '-0.5'
transactions:
m5:
buys: 0
sells: 2
buyers: 0
sellers: 2
m15:
buys: 4
sells: 7
buyers: 3
sellers: 5
m30:
buys: 12
sells: 19
buyers: 7
sellers: 9
h1:
buys: 39
sells: 48
buyers: 16
sellers: 15
h6:
buys: 180
sells: 271
buyers: 31
sellers: 35
h24:
buys: 870
sells: 1109
buyers: 55
sellers: 59
volume_usd:
m5: '988.7572917698'
m15: '1857835.95996426'
m30: '3190909.49729904'
h1: '9434171.29930675'
h6: '84784863.3965608'
h24: '388004708.962186'
reserve_in_usd: '103939687.035'
relationships:
base_token:
data:
id: eth_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
type: token
quote_token:
data:
id: eth_0xdac17f958d2ee523a2206206994597c13d831ec7
type: token
dex:
data:
id: fluid-ethereum
type: dex
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-cg-pro-api-key
apiKeyQueryParam:
type: apiKey
in: query
name: x_cg_pro_api_key
````