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

# Web3 tools

## Web3 Tools Reference Documentation

This documentation provides detailed information about the Web3 tools available within the Galadriel framework. These tools enable agents to interact with blockchain networks, retrieve market data, and manage user portfolios.

### Market Data Tools

#### `CoingeckoTool`

(Abstract base class) Provides common functionality for accessing the Coingecko API.

**Inheritance:** `Tool`

**Attributes:**

* `api_key` (str): The Coingecko API key. Must be set as an environment variable `COINGECKO_API_KEY`.

**Methods:**

* `__init__(self, *args, **kwargs)`: Initializes the Coingecko tool. Raises `ValueError` if `COINGECKO_API_KEY` environment variable is not set.

#### `GetCoinPriceTool`

Retrieves current cryptocurrency price and market data from Coingecko.

**Inheritance:** `CoingeckoTool`, `Tool`

**Name:** "get\_coin\_price"

**Description:** "This is a tool that returns the price of given crypto token together with market cap, 24hr vol and 24hr change."

**Inputs:**

* `task` (str): The full name of the token. Example: 'solana' not 'sol'.

**Output Type:** `string`

**Methods:**

* `forward(self, task: str) -> str`: Fetches current price and market data for a cryptocurrency from Coingecko. Returns a JSON string containing price and market data.

#### `GetCoinMarketDataTool`

Retrieves current market data for a specified cryptocurrency from Coingecko.

**Inheritance:** `CoingeckoTool`, `Tool`

**Name:** "get\_coin\_market\_data"

**Description:** "This is a tool that returns the market data of given crypto token."

**Inputs:**

* `coin_id` (str): The full name of the token. Example: 'solana' not 'sol'.

**Output Type:** `string`

**Methods:**

* `forward(self, coin_id: str) -> str`: Fetches current market data for a cryptocurrency from Coingecko. Returns a JSON string containing market data.

#### `GetCoinHistoricalDataTool`

Retrieves historical cryptocurrency price data from Coingecko.

**Inheritance:** `CoingeckoTool`, `Tool`

**Name:** "get\_coin\_historical\_data"

**Description:** "This is a tool that returns the historical data of given crypto token."

**Inputs:**

* `task` (str): The full name of the token. Example: 'solana' not 'sol'.
* `days` (str): Number of days of historical data to fetch.

**Output Type:** `string`

**Methods:**

* `forward(self, task: str, days: str) -> str`: Fetches historical price data for a cryptocurrency from Coingecko. Returns a JSON string containing historical price data.

#### `FetchMarketDataPerCategoriesTool`

Tool for retrieving market data for cryptocurrencies in specific categories.

**Inheritance:** `CoingeckoTool`, `Tool`

**Name:** "fetch\_market\_data\_per\_categories"

**Description:** "This is a tool that returns the market data for cryptocurrencies in specific categories."

**Inputs:**

* `categories` (list): The categories of the cryptocurrencies to fetch data for.

**Output Type:** `string`

**Methods:**

* `forward(self, categories: list) -> str`: Fetches market data for cryptocurrencies in specified categories from Coingecko. Returns a JSON string containing the market data for the given categories.

#### `FetchTrendingCoinsTool`

Retrieves trending cryptocurrency data from Coingecko.

**Inheritance:** `CoingeckoTool`, `Tool`

**Name:** "fetch\_trending\_coins"

**Description:** "This tool fetches the current trending cryptocurrencies based on Coingecko's trending coins data."

**Inputs:**

* None

**Output Type:** `string`

**Methods:**

* `forward(self) -> str`: Fetches a list of currently trending cryptocurrencies from Coingecko. Returns a JSON string containing trending coin details.

#### `GetTokenDataTool`

Retrieves and formats token data from the DexScreener API.

**Inheritance:** `Tool`

**Name:** "get\_token\_data"

**Description:** "Fetch detailed data for a specific token from DexScreener."

**Inputs:**

* `ecosystem` (str): The ecosystem of the token (e.g., 'solana', 'ethereum').
* `token_address` (str): The address of the token to fetch data for.

**Output Type:** `object`

**Methods:**

* `forward(self, ecosystem: str, token_address: str) -> Dict[str, Any]`: Fetches token data from DexScreener API. Returns a dictionary containing token details or an empty dictionary if the request fails.

#### `fetch_mock_market_data`

Fetches market data for the Solana Devnet.

**Inheritance:** `Tool`

**Name:** "fetch\_mock\_market\_data"

**Description:** "Fetches market data for the Solana Devnet."

**Inputs:**

* None

**Output Type:** `string`

**Methods:**

* `fetch_mock_market_data() -> str`: Returns a JSON string containing mock market data for the Solana Devnet.

### Solana On-Chain Tools

#### `SolanaBaseTool`

(Abstract base class) Base class for Solana tools that require wallet access and on-chain operations.

**Inheritance:** `Tool`

**Attributes:**

* `wallet_manager` (`WalletManager`): Manager for handling wallet operations.
* `network` (`Network`): The Solana network being used (mainnet or devnet).
* `client` (`Client`, optional): The Solana RPC client for network interactions.
* `async_client` (`AsyncClient`, optional): The HTTPX async client for network interactions.

**Methods:**

* `__init__(self, is_wallet_required: bool, is_async_client: bool, *args, **kwargs)`: Initializes the Solana tool. Raises `ValueError` if `SOLANA_KEY_PATH` environment variable is not set.

#### `GetUserBalanceTool`

Retrieves the user's balance for a specific token from the blockchain.

**Inheritance:** `SolanaBaseTool`, `Tool`

**Name:** "get\_user\_balance"

**Description:** "Retrieves the user's balance for a specific token from the blockchain."

**Inputs:**

* `user_address` (str): The address of the user.
* `token` (str): The token address in Solana.

**Output Type:** `number` (Optional\[float])

**Methods:**

* `forward(self, user_address: str, token: str) -> Optional[float]`: Retrieves the user's token balance. Returns the balance or `None` if the query fails.

#### `SwapTokenTool`

Tool for performing token swaps using Jupiter Protocol on Solana.

**Inheritance:** `SolanaBaseTool`, `Tool`

**Name:** "swap\_token"

**Description:** "Swaps one token for another in the user's portfolio."

**Inputs:**

* `token1` (str): The address of the token to sell.
* `token2` (str): The address of the token to buy.
* `amount` (float): The amount of `token1` to swap.
* `slippage_bps` (int, default: `300`): Slippage tolerance in basis points.

**Output Type:** `string`

**Methods:**

* `forward(self, token1: str, token2: str, amount: float, slippage_bps: int = 300) -> str`: Executes a token swap transaction. Returns a success message containing the transaction signature.

#### `GetAdminWalletAddressTool`

Retrieves the wallet address of the admin.

**Inheritance:** `SolanaBaseTool`, `Tool`

**Name:** "get\_admin\_wallet\_address"

**Description:** "This tool returns the wallet address of the admin."

**Inputs:**

* `dummy` (str): Dummy input.

**Output Type:** `string`

**Methods:**

* `forward(self, dummy: str) -> str`: Returns the admin's wallet address.

#### `BuyTokenWithSolTool` (Raydium CPMM)

Tool for buying tokens using SOL on Raydium CPMM.

**Inheritance:** `SolanaBaseTool`, `Tool`

**Name:** "buy\_token\_with\_sol\_cpmm"

**Description:** "Buy a token with SOL using the Raydium CPMM."

**Inputs:**

* `pair_address` (str): The address of the CPMM pair.
* `sol_in` (number, default: 0.01): The amount of SOL to swap.
* `slippage` (integer, default: 5): The slippage tolerance percentage.

**Output Type:** `string`

**Methods:**

* `forward(self, pair_address: str, sol_in: float = 0.01, slippage: int = 5) -> str`: Executes a SOL to token swap transaction.  Returns a success or failure message.

#### `SellTokenForSolTool` (Raydium CPMM)

Tool for selling tokens for SOL using Raydium CPMM.

**Inheritance:** `SolanaBaseTool`, `Tool`

**Name:** "sell\_token\_for\_sol\_cpmm"

**Description:** "Sell a token for SOL using the Raydium CPMM."

**Inputs:**

* `pair_address` (str): The address of the CPMM pair.
* `percentage` (integer, default: 100): The percentage of token to sell.
* `slippage` (integer, default: 5): The slippage tolerance percentage.

**Output Type:** `string`

**Methods:**

* `forward(self, pair_address: str, percentage: int = 100, slippage: int = 5) -> str`: Executes a token to SOL swap. Returns a success or failure message.

#### `BuyTokenWithSolTool` (Raydium AMM V4)

Tool for buying tokens using SOL on Raydium AMM V4.

**Inheritance:** `SolanaBaseTool`, `Tool`
**Name:** "buy\_token\_with\_sol"
**Description:** "Buy a token with SOL using the Raydium AMM V4."

**Inputs:**

* `pair_address` (str): The address of the AMM V4 pair.
* `sol_in` (number, `default`: 0.01): The amount of SOL to swap.
* `slippage` (integer, `default`: 5): The slippage tolerance percentage.

**Output Type:** `string`

**Methods:**

* `forward(self, pair_address: str, sol_in: float = 0.01, slippage: int = 5) -> str`:  Executes a SOL to token swap transaction. Returns a success or failure message.

#### `SellTokenForSolTool` (Raydium AMM V4)

Tool for selling tokens for SOL using Raydium AMM V4.

**Inheritance:** `SolanaBaseTool`, `Tool`
**Name:** "sell\_token\_for\_sol"
**Description:** "Sell a token for SOL using the Raydium AMM V4."

**Inputs:**

* `pair_address` (str): The address of the AMM V4 pair.
* `percentage` (integer, `default`: 100): The percentage of token to sell.
* `slippage` (integer, `default`: 5): The slippage tolerance percentage.

**Output Type:** `string`

**Methods:**

* `forward(self, pair_address: str, percentage: int = 100, slippage: int = 5) -> str`: Executes a token to SOL swap transaction. Returns a success or failure message.