> ## 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.
# Top Pools by Token Address
> To query top pools 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
* Top pools are ranked by a combination of liquidity (`reserve_in_usd`) and 24-hour trading volume (`volume_usd`).
* Returns up to 20 pools per page. Pagination beyond 10 pages requires [Analyst plan or above](https://www.coingecko.com/en/api/pricing).
* Unverified token market cap returns `null` — the displayed value on GeckoTerminal may match FDV and might not be accurate.
* Use `include` to return related attributes under the top-level `included` key.
#### SDK Examples
```typescript TypeScript theme={null}
const response = await client.onchain.networks.tokens.pools.get('0xdac17f958d2ee523a2206206994597c13d831ec7', {
network: 'eth',
});
console.log(JSON.stringify(response, null, 2));
```
```python Python theme={null}
response = client.onchain.networks.tokens.pools.get(
"0xdac17f958d2ee523a2206206994597c13d831ec7",
network="eth",
)
print(response.model_dump_json(indent=2))
```
## OpenAPI
````yaml openapi-specs/demo-api.json get /onchain/networks/{network}/tokens/{token_address}/pools
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/{token_address}/pools:
get:
summary: Top Pools by Token Address
description: >-
To query top pools based on the provided token contract address on a
network
operationId: top-pools-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: token_address
in: path
required: true
description: Token contract address.
schema:
type: string
default: '0xdac17f958d2ee523a2206206994597c13d831ec7'
- name: include
in: query
required: false
description: |-
Attributes to include, comma-separated if more than one.
Available values: `base_token`, `quote_token`, `dex`
schema:
type: string
- name: include_inactive_source
in: query
required: false
description: |-
Include tokens from inactive pools using the most recent swap.
Default: `false`
schema:
type: boolean
- name: page
in: query
required: false
description: |-
Page through results.
Default value: 1
schema:
type: integer
- name: sort
in: query
required: false
description: |-
Sort the pools by field.
Default: `h24_volume_usd_liquidity_desc`
schema:
type: string
enum:
- h24_volume_usd_liquidity_desc
- h24_tx_count_desc
- h24_volume_usd_desc
- name: include_gt_community_data
in: query
required: false
description: >-
Include GeckoTerminal community data (sentiment votes, suspicious
reports).
Default: `false`
schema:
type: boolean
responses:
'200':
description: Top pools for a token
content:
application/json:
schema:
$ref: '#/components/schemas/Pool'
example:
data:
- id: >-
eth_0x395f91b34aa34a477ce3bc6505639a821b286a62b1a164fc1887fa3a5ef713a5
type: pool
attributes:
base_token_price_usd: '1.0008763651'
base_token_price_native_currency: '0.000482317790072442'
quote_token_price_usd: '0.998449563724543'
quote_token_price_native_currency: '0.000481148325490986'
base_token_price_quote_token: '1.0024305698'
quote_token_price_base_token: '0.9975753236'
address: >-
0x395f91b34aa34a477ce3bc6505639a821b286a62b1a164fc1887fa3a5ef713a5
name: USDC / USDT
pool_created_at: '2025-04-13T14:45:47Z'
token_price_usd: '0.998449563724543'
fdv_usd: '96921299344.3568'
market_cap_usd: '189288747230.058'
price_change_percentage:
m5: '0'
m15: '-0.08'
m30: '-0.02'
h1: '-0.55'
h6: '0.23'
h24: '-0.21'
transactions:
m5:
buys: 1
sells: 0
buyers: 1
sellers: 0
m15:
buys: 2
sells: 13
buyers: 2
sellers: 12
m30:
buys: 16
sells: 22
buyers: 15
sellers: 21
h1:
buys: 44
sells: 50
buyers: 41
sellers: 46
h6:
buys: 306
sells: 373
buyers: 240
sellers: 305
h24:
buys: 1062
sells: 1217
buyers: 677
sellers: 803
volume_usd:
m5: '100.4170370205'
m15: '44354.6645720277'
m30: '2972422.02951497'
h1: '6273480.14455755'
h6: '31080731.7699018'
h24: '65665560.4792908'
reserve_in_usd: '545933958.0815'
sentiment_vote_positive_percentage: 0
sentiment_vote_negative_percentage: 0
community_sus_report: 2
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
included:
- id: eth_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
type: token
attributes:
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
name: USD Coin
symbol: USDC
decimals: 6
image_url: >-
https://coin-images.coingecko.com/coins/images/6319/large/USDC.png?1769615602
coingecko_coin_id: usd-coin
- 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
- id: uniswap-v4-ethereum
type: dex
attributes:
name: Uniswap V4 (Ethereum)
components:
schemas:
Pool:
type: object
required:
- data
properties:
data:
type: array
items:
type: object
required:
- id
- type
- attributes
- relationships
properties:
id:
type: string
description: Pool identifier
type:
type: string
description: Resource type
attributes:
type: object
required:
- base_token_price_usd
- base_token_price_native_currency
- quote_token_price_usd
- quote_token_price_native_currency
- base_token_price_quote_token
- quote_token_price_base_token
- address
- name
- pool_created_at
- fdv_usd
- market_cap_usd
- price_change_percentage
- transactions
- volume_usd
- reserve_in_usd
properties:
base_token_price_usd:
type: string
description: Base token price in USD
base_token_price_native_currency:
type: string
nullable: true
description: Base token price in native currency
quote_token_price_usd:
type: string
description: Quote token price in USD
quote_token_price_native_currency:
type: string
nullable: true
description: Quote token price in native currency
base_token_price_quote_token:
type: string
nullable: true
description: Base token price in quote token
quote_token_price_base_token:
type: string
nullable: true
description: Quote token price in base token
address:
type: string
description: Pool contract address
name:
type: string
description: Pool name
pool_created_at:
type: string
description: Pool creation timestamp
fdv_usd:
type: string
nullable: true
description: Fully diluted valuation in USD
market_cap_usd:
type: string
nullable: true
description: Market cap in USD
price_change_percentage:
type: object
description: Price change percentage over various timeframes
properties:
m5:
type: string
m15:
type: string
m30:
type: string
h1:
type: string
h6:
type: string
h24:
type: string
transactions:
type: object
description: Transaction counts over various timeframes
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
description: Volume in USD over various timeframes
properties:
m5:
type: string
m15:
type: string
m30:
type: string
h1:
type: string
h6:
type: string
h24:
type: string
reserve_in_usd:
type: string
nullable: true
description: Total reserve in USD
token_price_usd:
type: string
description: >-
Price of the queried token in USD, present when querying
pools by token address
sentiment_vote_positive_percentage:
type: number
description: GeckoTerminal community positive sentiment vote percentage
sentiment_vote_negative_percentage:
type: number
description: GeckoTerminal community negative sentiment vote percentage
community_sus_report:
type: integer
description: GeckoTerminal community suspicious reports count
relationships:
type: object
description: Related resources
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
network:
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
included:
type: array
description: >-
Included related resources, present when include parameter is
specified
items:
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
nullable: true
coingecko_coin_id:
type: string
nullable: true
coingecko_asset_platform_id:
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)
````