Token Data by Token Address

To query specific token data based on the provided token contract address on a network

GET /onchain/networks/{network}/tokens/{address}

Token Data by Token Address

cURL

curl --request GET \
  --url https://pro-api.coingecko.com/api/v3/onchain/networks/{network}/tokens/{address} \
  --header 'x-cg-pro-api-key: <api-key>'

200

{
  "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"
          }
        }
      }
    }
  ]
}

Notes

• Addresses not found in GeckoTerminal will be ignored.
• Returns the top most liquid pool per token, ranked by liquidity (reserve_in_usd) and 24-hour volume (volume_usd).
• 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 instead.

SDK Examples

TypeScript

const response = await client.onchain.networks.tokens.getAddress('0xdac17f958d2ee523a2206206994597c13d831ec7', {
  network: 'eth',
});

console.log(JSON.stringify(response, null, 2));

Authorizations

headerAuthqueryAuth

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

Learn how to set up your API key

Path Parameters

network · string · default: eth · required

Network ID. *refers to /onchain/networks.

address · string · default: 0xdac17f958d2ee523a2206206994597c13d831ec7 · required

Token contract address.

Query Parameters

include · enum<string>

Attributes to include.

Available options: top_pools

include_composition · boolean

Include pool composition. Default: false

include_inactive_source · boolean

Include token data from inactive pools using the most recent swap. Default: false

Response

200 - application/json

Token data

data · object · required

Show child attributes

included · object[]

Included top pool data, present when include=top_pools is specified

Show child attributes