> For the complete documentation index, see [llms.txt](https://docs.agentipy.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agentipy.fun/tools/use-coingecko/using-the-coingecko-manager-tool.md).

# Using the CoinGecko Manager Tool

All methods in the CoingeckoManager are static asynchronous methods. You call them directly from the CoingeckoManager class and must use await.

#### 1. get\_trending\_tokens

Description: Fetches the current list of cryptocurrencies that are trending on CoinGecko. This is often based on recent search popularity.

Endpoint: Uses CoinGecko's public /search/trending endpoint. May use the demo API key if available and no Pro key is set.

**Method Signature:**

```python
async def get_trending_tokens(agent: SolanaAgentKit) -> dict:
```

Parameters:

* agent (SolanaAgentKit): Required. The initialized agent instance.
* Returns:
  * A dict containing the trending tokens data. The exact structure is determined by the CoinGecko API response, but typically includes a coins key which is a list of trending coin objects, each with details like id, coin\_id, name, symbol, market\_cap\_rank, etc.

Example:

```python
import asyncio
from agentipy.agent import SolanaAgentKit
from agentipy.tools.use_coingecko import CoingeckoManager
# Assuming 'agent' is your initialized SolanaAgentKit instance

async def fetch_trending():
    try:
        trending_data = await CoingeckoManager.get_trending_tokens(agent)
        print("Currently Trending Tokens:")
        for coin in trending_data.get('coins', []):
            item = coin.get('item', {})
            print(f"- {item.get('symbol', 'N/A')} ({item.get('name', 'N/A')}): Rank {item.get('market_cap_rank', 'N/A')}")
    except Exception as e:
        print(f"Error fetching trending tokens: {e}")

# asyncio.run(fetch_trending()) # Example of how to run
```

#### 2. get\_trending\_pools

**Description:** Fetches liquidity pools that are currently trending on CoinGecko, filtered specifically for the Solana network. This endpoint is valuable for identifying pools with high recent trading volume or activity.

* Endpoint: Uses CoinGecko's Pro API endpoint /onchain/networks/solana/trending\_pools.

**Method Signature:**

```python
async def get_trending_pools(agent: SolanaAgentKit, duration: str = "24h") -> dict:
```

Parameters:

* agent (SolanaAgentKit): Required. The initialized agent instance with a CoinGecko Pro API key configured.
* duration (str): Optional. The time window to consider for trending activity. Defaults to "24h". Allowed values based on the code: "5m", "1h", "6h", "24h".
* Returns:
  * A dict containing the trending pools data. The structure includes a data key which is a list of pool objects, with details about the pool address, network, base/quote tokens, volume, etc.

Example:

```python
import asyncio
from agentipy.agent import SolanaAgentKit
from agentipy.tools.use_coingecko import CoingeckoManager
# Assuming 'agent' is initialized with a PRO CoinGecko key

async def fetch_trending_pools():
    try:
        print("Fetching trending Solana pools for the last hour...")
        trending_pools = await CoingeckoManager.get_trending_pools(agent, duration="1h")
        print("Trending Pools:")
        for pool in trending_pools.get('data', []):
            base_token = pool.get('base_token', {})
            network = pool.get('network', {})
            print(f"- {base_token.get('symbol', 'N/A')} Pool on {network.get('name', 'N/A')}: Address {pool.get('address', 'N/A')}")
    except Exception as e:
        print(f"Error fetching trending pools: {e}")
        print("Hint: This endpoint requires a CoinGecko Pro API Key configured in your agent.")

# asyncio.run(fetch_trending_pools()) # Example of how to run
```

#### 3. get\_top\_gainers

* Description: Retrieves a list of top-performing tokens by percentage change over a specified duration, including both gainers and losers.
* Endpoint: Uses CoinGecko's Pro API endpoint /coins/top\_gainers\_losers.

**Method Signature:**

```python
async def get_top_gainers(
    agent: SolanaAgentKit,
    duration: str = "24h",  # Allowed values: "1h", "24h", "7d", "14d", "30d", "60d", "1y"
    top_coins: int | str = "all"  # Allowed values: 300, 500, 1000, or "all"
) -> dict:
```

**Parameters:**

* agent (SolanaAgentKit): Required. The initialized agent instance with a CoinGecko Pro API key configured.
* duration (str): Optional. The time window for calculating price changes. Defaults to "24h". Supports various periods like "1h", "7d", "30d", etc.
* top\_coins (int | str): Optional. Limits the scope to tokens within the top N market capitalization ranks. Defaults to "all". Can be specific integers (300, 500, 1000) or "all".
* Returns:
  * A dict containing top\_gainers and top\_losers keys, each holding a list of token objects with relevant performance data.

Example:

```python
import asyncio
from agentipy.agent import SolanaAgentKit
from agentipy.tools.use_coingecko import CoingeckoManager
# Assuming 'agent' is initialized with a PRO CoinGecko key

async def fetch_top_performers():
    try:
        print("Fetching top 5 gainers/losers over the last 7 days...")
        performers = await CoingeckoManager.get_top_gainers(agent, duration="7d", top_coins=500)

        print("\nTop 5 Gainers (7d):")
        for token in performers.get('top_gainers', [])[:5]:
            print(f"- {token.get('symbol', 'N/A')}: {token.get('price_change_percentage', 0):.2f}%")

        print("\nTop 5 Losers (7d):")
        for token in performers.get('top_losers', [])[:5]:
            print(f"- {token.get('symbol', 'N/A')}: {token.get('price_change_percentage', 0):.2f}%")

    except Exception as e:
        print(f"Error fetching top performers: {e}")
        print("Hint: This endpoint requires a CoinGecko Pro API Key configured in your agent.")

# asyncio.run(fetch_top_performers()) # Example of how to run
```

#### 4. get\_token\_price\_data

Description: Fetches current price (vs. USD), market cap, 24h volume, and 24h price change for a list of specific token addresses on the Solana network.

Endpoint: Uses CoinGecko's public /simple/token\_price/{network\_id} endpoint (with network\_id=solana). May use the demo API key if available and no Pro key is set.

**Method Signature:**

```python
async def get_token_price_data(agent: SolanaAgentKit, token_addresses: list[str]) -> dict:
```

**Parameters:**

* agent (SolanaAgentKit): Required. The initialized agent instance. Accesses API keys if available.
* token\_addresses (list\[str]): Required. A list of token contract addresses on the Solana network, provided as strings.
* Returns:
  * A dict where the keys are the requested token addresses (strings) and the values are dictionaries containing the price and market data (e.g., usd, usd\_market\_cap, usd\_24h\_vol, usd\_24h\_change, last\_updated\_at).

Example:

```python
import asyncio
from agentipy.agent import SolanaAgentKit
from agentipy.tools.use_coingecko import CoingeckoManager
# Assuming 'agent' is your initialized SolanaAgentKit instance

async def fetch_prices():
    # Example SOL and USDC addresses on Mainnet-beta
    sol_address = "So11111111111111111111111111111111111111112"
    usdc_address = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    token_list = [sol_address, usdc_address]

    try:
        print(f"Fetching price data for: {token_list}...")
        price_info = await CoingeckoManager.get_token_price_data(agent, token_list)

        for address, data in price_info.items():
            print(f"\nData for {address}:")
            print(f"- Price (USD): ${data.get('usd', 0):.4f}")
            print(f"- 24h Change (%): {data.get('usd_24h_change', 0):.2f}%")
            print(f"- Last Updated: {data.get('last_updated_at', 'N/A')}")

    except Exception as e:
        print(f"Error fetching token price data: {e}")

# asyncio.run(fetch_prices()) # Example of how to run
```

#### 5. get\_token\_info

* Description: Fetches detailed information for a single token address on the Solana network. This can include links (website, explorer, social media), descriptions, and other metadata.
* Endpoint: Uses CoinGecko's Pro API endpoint /onchain/networks/solana/tokens/{token\_address}/info.

**Method Signature:**

```python
async def get_token_info(agent: SolanaAgentKit, token_address: str) -> dict:
```

**Parameters:**

* agent (SolanaAgentKit): Required. The initialized agent instance with a CoinGecko Pro API key configured.
* token\_address (str): Required. The contract address of the token (as a string).
* Returns:
  * A dict containing detailed information about the specified token.

Example:

```python
import asyncio
from agentipy.agent import SolanaAgentKit
from agentipy.tools.use_coingecko import CoingeckoManager
# Assuming 'agent' is initialized with a PRO CoinGecko key

async def fetch_token_details():
    usdc_address = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" # USDC Mainnet-beta address
    try:
        print(f"Fetching detailed info for {usdc_address} (USDC)...")
        token_info = await CoingeckoManager.get_token_info(agent, usdc_address)
        print("Token Info:")
        print(f"- Name: {token_info.get('name', 'N/A')}")
        print(f"- Symbol: {token_info.get('symbol', 'N/A')}")
        print(f"- Description (partial): {token_info.get('description', '')[:150]}...")
        # Access links: token_info.get('links', {})
    except Exception as e:
        print(f"Error fetching token info: {e}")
        print("Hint: This endpoint requires a CoinGecko Pro API Key configured in your agent.")

# asyncio.run(fetch_token_details()) # Example of how to run
```

#### 6. get\_latest\_pools

* Description: Fetches the most recently created liquidity pools on the Solana network. This is useful for agents looking for new trading opportunities as soon as they arise.
* Endpoint: Uses CoinGecko's Pro API endpoint /onchain/networks/solana/new\_pools.

**Method Signature:**

```python
async def get_latest_pools(agent: SolanaAgentKit) -> dict:
```

**Parameters:**

* agent (SolanaAgentKit): Required. The initialized agent instance with a CoinGecko Pro API key configured.
* Returns:
  * A dict containing the latest pools data, typically under a data key, which is a list of pool objects similar in structure to trending pools.

Example:

```python
import asyncio
from agentipy.agent import SolanaAgentKit
from agentipy.tools.use_coingecko import CoingeckoManager
# Assuming 'agent' is initialized with a PRO CoinGecko key

async def fetch_latest_pools():
    try:
        print("Fetching the latest Solana pools...")
        latest_pools = await CoingeckoManager.get_latest_pools(agent)
        print(f"Found {len(latest_pools.get('data', []))} latest pools:")
        for pool in latest_pools.get('data', [])[:5]: # Print data for the first 5
            base_token = pool.get('base_token', {})
            network = pool.get('network', {})
            print(f"- {base_token.get('symbol', 'N/A')} Pool on {network.get('name', 'N/A')}: Address {pool.get('address', 'N/A')}")
    except Exception as e:
        print(f"Error fetching latest pools: {e}")
        print("Hint: This endpoint requires a CoinGecko Pro API Key configured in your agent.")

# asyncio.run(fetch_latest_pools()) 
```