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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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