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 run2. 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 run3. 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 run4. 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 run5. 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 run6. 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()) Last updated