> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendai.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# CoinGecko Market Data Integration

> Learn how to fetch market data, token information, and trends using CoinGecko

Solana Agent Kit provides comprehensive integration with CoinGecko's API for accessing market data, token information, and trending metrics. The integration supports both Pro and Demo API keys with fallback functionality.

## Key Features

* Token price data
* Token information
* Latest pools tracking
* Trending pools analysis
* Top gainers identification
* Trending tokens discovery
* Support for both Pro and Demo API
* Configurable time ranges

## Basic Usage

### Getting Token Price Data

```typescript theme={"system"}
const priceData = await agent.methods.getTokenPriceData([
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  // USDC
  "So11111111111111111111111111111111111111112"    // SOL
]);
```

### Getting Token Information

```typescript theme={"system"}
const tokenInfo = await agent.methods.getTokenInfo(
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"  // USDC
);
```

### Getting Latest Pools

```typescript theme={"system"}
const latestPools = await agent.methods.getLatestPools();
```

### Getting Trending Pools

```typescript theme={"system"}
const trendingPools = await agent.methods.getTrendingPools("24h");
```

### Getting Top Gainers

```typescript theme={"system"}
const topGainers = await agent.methods.getTopGainers("24h", "all");
```

### Getting Trending Tokens

```typescript theme={"system"}
const trendingTokens = await agent.methods.getTrendingTokens();
```

## Configuration

### API Key Setup

```typescript theme={"system"}
interface CoinGeckoConfig {
  COINGECKO_PRO_API_KEY?: string;    // Pro API key
  COINGECKO_DEMO_API_KEY?: string;    // Demo API key
}
```

### Time Range Options

```typescript theme={"system"}
type DurationOptions = "5m" | "1h" | "6h" | "24h";  // For trending pools
type GainerDuration = "1h" | "24h" | "7d" | "14d" | "30d" | "60d" | "1y";
type TopCoinsLimit = 300 | 500 | 1000 | "all";
```

## API Response Types

### Token Price Data

```typescript theme={"system"}
interface TokenPriceData {
  [tokenAddress: string]: {
    usd: number;
    usd_market_cap: number;
    usd_24h_vol: number;
    usd_24h_change: number;
    last_updated_at: number;
  }
}
```

### Pool Data

```typescript theme={"system"}
interface PoolData {
  pool_address: string;
  base_token: {
    address: string;
    symbol: string;
    name: string;
  };
  quote_token: {
    address: string;
    symbol: string;
    name: string;
  };
  volume_24h: number;
  liquidity_usd: number;
  created_at: string;
}
```

## Important Notes

1. **API Key Requirements**
   * Pro API key required for advanced endpoints
   * Demo API key supports basic endpoints
   * Some endpoints work without any key

2. **Rate Limits**
   * Pro API: Higher rate limits
   * Demo API: Limited requests per minute
   * Public API: Lowest rate limits

3. **Data Freshness**
   * Price data updated every minute
   * Pool data updated every 5 minutes
   * Trending data updated every hour

## Best Practices

1. **API Key Management**
   ```typescript theme={"system"}
   // Check for API key availability
   if (!agent.methods.config.COINGECKO_PRO_API_KEY) {
     // Fallback to demo key if available
     if (agent.methods.config.COINGECKO_DEMO_API_KEY) {
       // Use demo endpoints
     }
   }
   ```

2. **Error Handling**
   ```typescript theme={"system"}
   try {
     const data = await agent.methods.getTokenPriceData(tokens);
   } catch (error) {
     if (error.message.includes("API key")) {
       // Handle authentication issues
     } else if (error.message.includes("rate limit")) {
       // Handle rate limiting
     }
   }
   ```

3. **Batch Processing**
   ```typescript theme={"system"}
   // Process tokens in batches to avoid URL length limits
   const batchSize = 100;
   const batches = chunk(tokenAddresses, batchSize);
   const results = await Promise.all(
     batches.map(batch => agent.methods.getTokenPriceData(batch))
   );
   ```

## Technical Details

### API Endpoints

```typescript theme={"system"}
const ENDPOINTS = {
  PRO: {
    BASE: "https://pro-api.coingecko.com/api/v3",
    TOKEN_PRICE: "/simple/token_price/solana",
    TRENDING_POOLS: "/onchain/networks/solana/trending_pools",
    NEW_POOLS: "/onchain/networks/solana/new_pools",
    TOP_GAINERS: "/coins/top_gainers_losers",
    TRENDING: "/search/trending"
  },
  DEMO: {
    BASE: "https://api.coingecko.com/api/v3",
    // Similar endpoints without pro prefix
  }
};
```

### Common Parameters

```typescript theme={"system"}
const PARAMS = {
  VS_CURRENCY: "usd",
  INCLUDE_FIELDS: [
    "market_cap",
    "24hr_vol",
    "24hr_change",
    "last_updated_at"
  ]
};
```

## Example Use Cases

1. **Market Analysis**
   ```typescript theme={"system"}
   // Get price data and trending info
   const prices = await agent.methods.getTokenPriceData(tokens);
   const trending = await agent.methods.getTrendingTokens();
   const gainers = await agent.methods.getTopGainers("24h", 300);
   ```

2. **Pool Discovery**
   ```typescript theme={"system"}
   // Get new and trending pools
   const newPools = await agent.methods.getLatestPools();
   const trendingPools = await agent.methods.getTrendingPools("1h");
   ```

3. **Token Research**
   ```typescript theme={"system"}
   // Get comprehensive token information
   const tokenInfo = await agent.methods.getTokenInfo(address);
   const priceData = await agent.methods.getTokenPriceData([address]);
   ```

## Error Messages

Common error messages and their meanings:

```typescript theme={"system"}
const ERROR_MESSAGES = {
  NO_API_KEY: "No CoinGecko Pro API key provided",
  RATE_LIMIT: "API rate limit exceeded",
  INVALID_TOKEN: "Invalid token address",
  NETWORK_ERROR: "Failed to fetch data from CoinGecko"
};
```