Gdex Token Discovery

GDEX: Token Discovery

Research tokens with price data, market metrics, trending rankings, candlestick charts, and top trader leaderboards.

Auth required: All token discovery endpoints (except /v1/token_details) return 403 "Access denied: Invalid client" without a Bearer token. Always call loginWithApiKey() first.

When to Use

• Looking up token price, market cap, volume, liquidity, and socials
• Finding trending tokens on a specific chain
• Getting OHLCV candlestick data for charting or analysis
• Researching a token before buying (DEX info, security audit, holder count)
• Finding top-performing trader wallets

Prerequisites

import { GdexSkill, GDEX_API_KEY_PRIMARY } from '@gdexsdk/gdex-skill';

const skill = new GdexSkill();
skill.loginWithApiKey(GDEX_API_KEY_PRIMARY);

Token Details

const token = await skill.getTokenDetails({
  tokenAddress: 'EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm',
  chain: 622112261,  // Solana
});

console.log(token.symbol);        // "$WIF"
console.log(token.priceUsd);      // 0.176
console.log(token.marketCap);     // 176054268
console.log(token.liquidityUsd);  // 4574052
console.log(token.dexId);         // "raydium"
console.log(token.isRaydium);     // true
console.log(token.priceChanges);  // { m5: 0, h1: -0.2, h6: -2.2, h24: -1.3 }
console.log(token.volumes);       // { m5: 482, h1: 15438, h6: 74105, h24: 316704 }
console.log(token.securities?.holderCount);  // 201554

TokenDetails (response)

interface TokenDetails {
  address: string;           // token contract address
  chainId: number;           // numeric chain ID
  symbol: string;            // may include $ prefix (e.g. "$WIF")
  name: string;              // full name
  decimals: number;
  priceUsd?: number;         // current USD price
  priceNative?: number;      // price in native token (SOL/ETH)
  marketCap?: number;        // market cap in USD
  liquidityUsd?: number;     // liquidity in USD
  liquidityEth?: number;     // liquidity in native token
  totalSupply?: string;      // raw units
  pairAddress?: string;      // DEX pair address
  dexId?: string;            // primary DEX (e.g. "raydium")
  dexes?: string[];          // all DEXes
  isRaydium?: boolean;
  isMeteora?: boolean;
  isPumpfun?: boolean;
  isPumpSwap?: boolean;
  priceChanges?: {           // price changes by period
    m5?: number; h1?: number; h6?: number; h24?: number;
  };
  volumes?: {                // volume by period
    m5?: number; h1?: number; h6?: number; h24?: number;
  };
  socialInfo?: {
    telegramUrl?: string; twitterUrl?: string;
    websiteUrl?: string; logoUrl?: string;
  };
  securities?: {             // security audit
    mintAbility?: boolean; freezeAbility?: boolean;
    lpLockPercentage?: number; holderCount?: number;
    topHoldersPercentage?: number;
  };
  createdTime?: number;      // creation timestamp (Unix ms)
}

Trending Tokens

const trending = await skill.getTrendingTokens({
  chain: 622112261,   // Solana (chainId)
  period: '24h',      // '1h' | '6h' | '24h' | '7d'
  limit: 5,
});

trending.forEach(t => {
  console.log(`${t.symbol}: $${t.priceUsd} mcap=$${t.marketCap} liq=$${t.liquidityUsd}`);
});

Parameters

Trending tokens have the same shape as TokenDetails — same fields from the tokens collection.

OHLCV Candlestick Data

const ohlcv = await skill.getOHLCV({
  tokenAddress: 'EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm',
  chain: 622112261,
  resolution: '60',   // 1-hour candles
  from: Math.floor(Date.now() / 1000) - 86400,  // 24h ago
  to: Math.floor(Date.now() / 1000),
});

console.log('Candles:', ohlcv.candles.length);
ohlcv.candles.forEach(c => {
  console.log(`[${new Date(c.time * 1000).toISOString()}] O=${c.open} H=${c.high} L=${c.low} C=${c.close}`);
});

Parameters

Note: The backend candle data may not be populated for all tokens. If candles is empty, the data isn't available yet — not an SDK error.

Top Traders

const traders = await skill.getTopTraders({
  chain: 622112261,  // Solana
  period: '7d',
  limit: 5,
});

traders.forEach((t, i) => {
  console.log(`#${i + 1}: ${t.wallet_address} PnL(7d)=$${t.realized_profit_7d} name=${t.name || '?'}`);
});

Parameters

TopTrader (response)

interface TopTrader {
  wallet_address: string;     // wallet address
  address: string;            // same as wallet_address
  name?: string;              // display name
  twitter_username?: string;
  twitter_name?: string;
  avatar?: string;
  tags?: string[];            // e.g. ["app_smart_money", "kol"]
  realized_profit_1d?: number;
  realized_profit_7d?: number;
  realized_profit_30d?: number;
  pnl_1d?: number;           // PnL ratio (1d)
  pnl_7d?: number;
  pnl_30d?: number;
  buy?: number;               // recent buy count
  sell?: number;
  last_active?: number;       // Unix timestamp
}

Example: Token Research Before Buying

const skill = new GdexSkill();
skill.loginWithApiKey(GDEX_API_KEY_PRIMARY);

// 1. Find trending tokens on Solana
const trending = await skill.getTrendingTokens({
  chain: 622112261,
  period: '1h',
  limit: 5,
});

// 2. Get details on the top trending token
const top = trending[0];
const details = await skill.getTokenDetails({
  tokenAddress: top.address,
  chain: 622112261,
});

console.log(`${details.symbol}: $${details.priceUsd}`);
console.log(`Market Cap: $${details.marketCap}`);
console.log(`Liquidity: $${details.liquidityUsd}`);
console.log(`Holders: ${details.securities?.holderCount}`);
console.log(`DEX: ${details.dexId} (Raydium: ${details.isRaydium})`);

// 3. Check who the top traders are
const traders = await skill.getTopTraders({ chain: 622112261, period: '7d', limit: 3 });
traders.forEach(t => console.log(`  ${t.name || t.wallet_address}: $${t.realized_profit_7d} PnL`));

Autonomous Agent Notes (Live-Tested)

Chain Parameter Must Be Numeric

All token discovery endpoints (getOHLCV, getTopTraders, getTrendingTokens, getTokenDetails) require numeric chainId, not string chain. Use 622112261 for Solana, 8453 for Base, etc.

// ✅ Correct
await skill.getOHLCV({ tokenAddress, chain: 622112261, resolution: '60', from, to });
await skill.getTopTraders({ chain: 622112261, period: '7d', limit: 5 });

// ❌ Wrong — string chain names may not work for all endpoints
await skill.getOHLCV({ tokenAddress, chain: 'solana', resolution: '60', from, to });

OHLCV Data May Be Empty

Not all tokens have OHLCV data populated. If candles is an empty array, the data isn't available yet — this is not an SDK error. Try a different token or wider time range.

Token Safety Checks Before Buying

Before buying a token autonomously, check:

1. dexId: Must be 'raydium' on Solana (Meteora fails — see gdex-spot-trading)
2. liquidityUsd: Should be > $1000 to avoid slippage problems
3. securities.mintAbility: If true, the token can be infinitely minted (rug risk)
4. securities.freezeAbility: If true, your tokens can be frozen
5. securities.lpLockPercentage: Higher is safer (100% = fully locked LP)
6. marketCap: Sanity check — very low mcap tokens are extremely volatile

Auth Required

All token discovery endpoints return 403 "Access denied: Invalid client" without a Bearer token. Always call loginWithApiKey() first — even for read-only data.

Related Skills

• gdex-spot-trading — Buy/sell tokens after researching them
• gdex-portfolio — Check if you already hold a token
• gdex-authentication — Required for all token discovery endpoints