> ## 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
> To query specific token data based on the provided token contract address on a network
export const CacheInfo = ({publicRate, paidRate, rate}) => {
const fmt = v => v === 0 ? 'Real-time (Cacheless)' : `Every ${v}`;
if (rate !== undefined) {
return
Cache / Update Frequency:
{fmt(rate)}
;
}
if (publicRate !== undefined && paidRate !== undefined) {
return
Cache / Update Frequency:- {fmt(paidRate)} (Paid API)
- {fmt(publicRate)} (Demo / Keyless API)
;
}
return null;
};
#### Notes
* `total_reserve_in_usd` represents the total reserve of the requested token only across all its pools, not both tokens in a pair.
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate. Verified market cap is sourced from CoinGecko and may exceed FDV if it includes tokens on other networks.
* Use `include=top_pools` to include top pools data. Add `include_composition=true` to surface balance and liquidity of base and quote tokens (requires `include=top_pools`).
* Bonding curve tokens (non-graduated launchpad tokens) include a `launchpad_details` object with graduation status.
For token metadata (socials, websites, description), use [Token Info](/demo/reference/token-info-contract-address) instead.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.getAddress('0xdac17f958d2ee523a2206206994597c13d831ec7', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.get_address(
"0xdac17f958d2ee523a2206206994597c13d831ec7",
network="eth",
)
print(response.model_dump_json(indent=2))
```
## OpenAPI
````yaml openapi-specs/demo-api.json get /onchain/networks/{network}/tokens/{address}
openapi: 3.0.0
info:
title: CoinGecko Demo API
version: 3.0.0
servers:
- url: https://api.coingecko.com/api/v3
security:
- headerAuth: []
- queryAuth: []
paths:
/onchain/networks/{network}/tokens/{address}:
get:
summary: Token Data by Token Address
description: >-
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
required: true
description: |-
Network ID.
*refers to [`/onchain/networks`](/reference/networks-list).
schema:
type: string
default: eth
- name: address
in: path
required: true
description: Token contract address.
schema:
type: string
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
responses:
'200':
description: Token data
content:
application/json:
schema:
$ref: '#/components/schemas/TokenData'
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: '97071854588430319.0'
normalized_total_supply: '97071854588.4303'
price_usd: '0.9976477279'
fdv_usd: '96843463696.399'
total_reserve_in_usd: '2701052887.0071499413427031774184'
volume_usd:
h24: '572433180.559528'
market_cap_usd: '189135294432.762'
last_trade_timestamp: '1779897731'
relationships:
top_pools:
data:
- id: >-
eth_0x395f91b34aa34a477ce3bc6505639a821b286a62b1a164fc1887fa3a5ef713a5
type: pool
included:
- id: >-
eth_0x395f91b34aa34a477ce3bc6505639a821b286a62b1a164fc1887fa3a5ef713a5
type: pool
attributes:
base_token_price_usd: '1.00076841159283'
base_token_price_native_currency: '0.000482652821375511'
quote_token_price_usd: '0.99764772791269'
quote_token_price_native_currency: '0.000481147771090756'
base_token_price_quote_token: '1.0031280417'
quote_token_price_base_token: '0.9968817124'
address: >-
0x395f91b34aa34a477ce3bc6505639a821b286a62b1a164fc1887fa3a5ef713a5
name: USDC / USDT
pool_created_at: '2025-04-13T14:45:47Z'
token_price_usd: '0.99764772791269'
fdv_usd: '96843463696.399'
market_cap_usd: '189136733045.442'
price_change_percentage:
m5: '0.74'
m15: '0.52'
m30: '0.41'
h1: '0.49'
h6: '0.73'
h24: '0.1'
transactions:
m5:
buys: 0
sells: 6
buyers: 0
sellers: 6
m15:
buys: 11
sells: 23
buyers: 11
sellers: 13
m30:
buys: 15
sells: 41
buyers: 15
sellers: 28
h1:
buys: 53
sells: 60
buyers: 50
sellers: 45
h6:
buys: 314
sells: 393
buyers: 247
sellers: 311
h24:
buys: 1066
sells: 1219
buyers: 682
sellers: 800
volume_usd:
m5: '5390.4353119892'
m15: '73424.879752289'
m30: '2984135.66431702'
h1: '6251379.50994286'
h6: '31152723.862617'
h24: '64799943.9574331'
reserve_in_usd: '548688496.6398'
last_trade_timestamp: '1779897791'
relationships:
base_token:
data:
id: eth_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
type: token
quote_token:
data:
id: eth_0xdac17f958d2ee523a2206206994597c13d831ec7
type: token
dex:
data:
id: uniswap-v4-ethereum
type: dex
components:
schemas:
TokenData:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/TokenItem'
included:
type: array
description: Included top pool data, present when include=top_pools is specified
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
quote_token_price_usd:
type: string
quote_token_price_native_currency:
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
nullable: true
market_cap_usd:
type: string
nullable: true
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
last_trade_timestamp:
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
TokenItem:
type: object
required:
- id
- type
- attributes
- relationships
properties:
id:
type: string
description: Token identifier
type:
type: string
description: Resource type
attributes:
type: object
required:
- address
- name
- symbol
- decimals
- image_url
- coingecko_coin_id
- total_supply
- normalized_total_supply
- price_usd
- fdv_usd
- total_reserve_in_usd
- volume_usd
- market_cap_usd
properties:
address:
type: string
description: Token contract address
name:
type: string
description: Token name
symbol:
type: string
description: Token symbol
decimals:
type: integer
description: Token decimals
image_url:
type: string
nullable: true
description: Token image URL
coingecko_coin_id:
type: string
nullable: true
description: CoinGecko coin ID
total_supply:
type: string
description: Token total supply
normalized_total_supply:
type: string
description: Normalized token total supply
price_usd:
type: string
nullable: true
description: Token price in USD
fdv_usd:
type: string
nullable: true
description: Fully diluted valuation in USD
total_reserve_in_usd:
type: string
description: Total reserve in USD across all pools
volume_usd:
type: object
description: Volume in USD
properties:
h24:
type: string
market_cap_usd:
type: string
nullable: true
description: Market cap in USD
last_trade_timestamp:
type: string
description: Last trade timestamp in UNIX
launchpad_details:
type: object
description: Launchpad details for pump-style tokens
properties:
graduation_percentage:
type: number
completed:
type: boolean
completed_at:
type: string
nullable: true
migrated_destination_pool_address:
type: string
nullable: true
relationships:
type: object
properties:
top_pools:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
type:
type: string
securitySchemes:
headerAuth:
type: apiKey
in: header
name: x-cg-demo-api-key
description: >-
Learn how to [set up your API
key](https://docs.coingecko.com/docs/setting-up-your-api-key)
queryAuth:
type: apiKey
in: query
name: x_cg_demo_api_key
description: >-
Learn how to [set up your API
key](https://docs.coingecko.com/docs/setting-up-your-api-key)
````