Skip to main content
GET
/
networks
/
{network}
/
tokens
/
{address}
Token Data by Token Address
curl --request GET \
  --url https://pro-api.coingecko.com/api/v3/onchain/networks/{network}/tokens/{address} \
  --header 'x-cg-pro-api-key: <api-key>'
{
  "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"
          }
        }
      }
    }
  ]
}

​
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 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 on GeckoTerminal.com 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).

Authorizations

​
x-cg-pro-api-key
string
header
required

Path Parameters

​
network
string
default:eth
required

network ID *refers to /networks

Example:

"eth"

​
address
string
default:0xdac17f958d2ee523a2206206994597c13d831ec7
required

token contract address

Example:

"0xdac17f958d2ee523a2206206994597c13d831ec7"

Query Parameters

​
include
enum<string>

attributes to include

Available options:
top_pools
​
include_composition
boolean

include pool composition, default: false

​
include_inactive_source
boolean
default:false

include token data from inactive pools using the most recent swap, default: false

Response

200 - application/json

Get specific token on a network

​
data
object
​
included
object[]