# 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()) 
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.agentipy.fun/tools/use-coingecko/using-the-coingecko-manager-tool.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.