> ## 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.
# Trades within Time Range by Token Address
> To query the trades, across all pools, within a range of timestamp 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;
};
export const PlanExclusivity = ({tier}) => {
if (tier === "enterprise") {
return
Enterprise Only
This endpoint is exclusively available to Enterprise plan.
→ Contact sales
;
}
if (tier === "analyst_above") {
return
Analyst Plan and Above
This endpoint is only available to Analyst, Lite, Pro, and Enterprise plan.
→ View pricing
;
}
if (tier === "basic_above") {
return
Basic Plan and Above
This endpoint is only available to Basic, Analyst, Lite, Pro, and Enterprise plan.
→ View pricing
;
}
throw new Error(`PlanExclusivity: invalid tier "${tier}". Use "basic_above", "analyst_above", or "enterprise".`);
};
#### Notes
* Paginate with `cursor` rather than a page number:
* Pass `meta.next_cursor` back unchanged as `cursor` to fetch the next page.
* `meta.next_cursor` is `null` on the last page.
* For a relative lookback instead of an absolute window, use [Trades by Token Address](/reference/token-trades-contract-address) with `trading_period`.
`from` and `to` are both required, and the window between them cannot exceed 30 days.
* Both ends are inclusive.
* Neither may be later than the current server time.
## OpenAPI
````yaml openapi-specs/pro-api.json get /onchain/networks/{network}/tokens/{token_address}/trades/range
openapi: 3.0.0
info:
title: CoinGecko Pro API
version: 3.0.0
servers:
- url: https://pro-api.coingecko.com/api/v3
security:
- headerAuth: []
- queryAuth: []
paths:
/onchain/networks/{network}/tokens/{token_address}/trades/range:
get:
summary: Trades within Time Range by Token Address
description: >-
To query the trades, across all pools, within a range of timestamp based
on the provided token contract address on a network
operationId: token-trades-contract-address-range
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: trade_volume_in_usd_greater_than
in: query
required: false
description: |-
Filter trades by trade volume in USD greater than this value.
Default value: 0
schema:
type: number
- name: from
in: query
required: true
description: >-
Starting date in ISO date string (`YYYY-MM-DD` or
`YYYY-MM-DDTHH:MM`) or UNIX timestamp.
**Use ISO date string for best compatibility.**
schema:
type: string
default: '2026-09-01'
- name: to
in: query
required: true
description: >-
Ending date in ISO date string (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`)
or UNIX timestamp.
**Use ISO date string for best compatibility.**
schema:
type: string
default: '2026-09-08'
- name: cursor
in: query
required: false
description: >-
Cursor from the previous response, passed back unchanged to fetch
the next page.
schema:
type: string
- name: per_page
in: query
required: false
description: |-
Total results per page.
Default value: 100
Valid values: 1...300
schema:
type: integer
responses:
'200':
description: Trades from a token across all pools within a time range
content:
application/json:
schema:
$ref: '#/components/schemas/TokenTrades'
example:
data:
- id: >-
eth_25928919_0xe5278132946375ba292473819aa96c86fd7219d66009a067ed280f679bdf45eb_73_1788825611
type: trade
attributes:
pool_address: >-
0x0fb0e40cec3bb23e13abc585958a93c796fbea56955e19a23727a716a0423239
pool_dex: uniswap-v4-ethereum
block_number: 25928919
tx_hash: >-
0xe5278132946375ba292473819aa96c86fd7219d66009a067ed280f679bdf45eb
tx_from_address: '0xb5469a903df8dad9df1da1341a85f84fd434c724'
from_token_amount: '2489.650395'
to_token_amount: '2489.845103'
price_from_in_currency_token: '0.000401610882268168'
price_to_in_currency_token: '0.000401008437871588'
price_from_in_usd: '1.00030427279179'
price_to_in_usd: '0.9988037464599'
block_timestamp: '2026-09-07T23:59:59Z'
kind: sell
volume_in_usd: '2490.40792787628'
from_token_address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
to_token_address: '0xdac17f958d2ee523a2206206994597c13d831ec7'
- id: >-
eth_25928919_0xe5278132946375ba292473819aa96c86fd7219d66009a067ed280f679bdf45eb_67_1788825611
type: trade
attributes:
pool_address: >-
0x3b1b1f2e775a6db1664f8e7d59ad568605ea2406312c11aef03146c0cf89d5b9
pool_dex: uniswap-v4-ethereum
block_number: 25928919
tx_hash: >-
0xe5278132946375ba292473819aa96c86fd7219d66009a067ed280f679bdf45eb
tx_from_address: '0xb5469a903df8dad9df1da1341a85f84fd434c724'
from_token_amount: '19917.582875'
to_token_amount: '19919.253008'
price_from_in_currency_token: '0.000401042063308448'
price_to_in_currency_token: '0.000401008437871588'
price_from_in_usd: '0.998887498344251'
price_to_in_usd: '0.9988037464599'
block_timestamp: '2026-09-07T23:59:59Z'
kind: buy
volume_in_usd: '19895.424531073'
from_token_address: '0xdc035d45d973e3ec169d2276ddab16f1e407384f'
to_token_address: '0xdac17f958d2ee523a2206206994597c13d831ec7'
meta:
next_cursor: >-
eyJidCI6IjIwMjYtMDktMDdUMjM6NTk6NTkuMDAwMDAwMDAwWiIsImJuIjoyNTkyODkxOSwidHgiOiIweGU1Mjc4MTMyOTQ2Mzc1YmEyOTI0NzM4MTlhYTk2Yzg2ZmQ3MjE5ZDY2MDA5YTA2N2VkMjgwZjY3OWJkZjQ1ZWIiLCJsaSI6NjcsIndmIjoxNzg4MjIwODAwLCJmcCI6IjBkYzBiMzc1ZjU5NGE5Y2Y0ZjVkOWRlOTNkN2UxNjU2NTQzZTZlODJlOTEwN2IwMmUxYzRlZjNkZTFiNjgwODAiLCJpYXQiOjE3ODg5Mzk0NDN9
components:
schemas:
TokenTrades:
type: object
required:
- data
properties:
data:
type: array
items:
type: object
required:
- id
- type
- attributes
properties:
id:
type: string
description: Trade identifier
type:
type: string
description: Resource type
attributes:
type: object
required:
- pool_address
- pool_dex
- block_number
- tx_hash
- tx_from_address
- from_token_amount
- to_token_amount
- price_from_in_currency_token
- price_to_in_currency_token
- price_from_in_usd
- price_to_in_usd
- block_timestamp
- kind
- volume_in_usd
- from_token_address
- to_token_address
properties:
pool_address:
type: string
description: Pool contract address where the trade occurred
pool_dex:
type: string
description: DEX identifier of the pool
block_number:
type: integer
description: Block number of the trade
tx_hash:
type: string
description: Transaction hash
tx_from_address:
type: string
description: Transaction sender address
from_token_amount:
type: string
description: Amount of token sent
to_token_amount:
type: string
description: Amount of token received
price_from_in_currency_token:
type: string
description: Price of from-token in currency token
price_to_in_currency_token:
type: string
description: Price of to-token in currency token
price_from_in_usd:
type: string
description: Price of from-token in USD
price_to_in_usd:
type: string
description: Price of to-token in USD
block_timestamp:
type: string
description: Block timestamp
kind:
type: string
description: Trade kind (buy or sell)
volume_in_usd:
type: string
description: Trade volume in USD
from_token_address:
type: string
description: From-token contract address
to_token_address:
type: string
description: To-token contract address
meta:
type: object
required:
- next_cursor
properties:
next_cursor:
type: string
nullable: true
description: Cursor for the next page, null when there are no further pages
securitySchemes:
headerAuth:
type: apiKey
in: header
name: x-cg-pro-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_pro_api_key
description: >-
Learn how to [set up your API
key](https://docs.coingecko.com/docs/setting-up-your-api-key)
````