# swarms Finance Tools Documentation

## Installation

```bash
pip3 install -U swarms-tools yfinance requests httpx pandas loguru backoff web3 solana spl-token
```

## Environment Variables

Create a `.env` file in your project root with the following variables (as needed):

| Environment Variable      | Description             | Required For       |
| ------------------------- | ----------------------- | ------------------ |
| `COINBASE_API_KEY`        | Coinbase API Key        | Coinbase Trading   |
| `COINBASE_API_SECRET`     | Coinbase API Secret     | Coinbase Trading   |
| `COINBASE_API_PASSPHRASE` | Coinbase API Passphrase | Coinbase Trading   |
| `COINMARKETCAP_API_KEY`   | CoinMarketCap API Key   | CoinMarketCap Data |
| `HELIUS_API_KEY`          | Helius API Key          | Solana Data        |
| `EODHD_API_KEY`           | EODHD API Key           | Stock News         |
| `OKX_API_KEY`             | OKX API Key             | OKX Trading        |
| `OKX_API_SECRET`          | OKX API Secret          | OKX Trading        |
| `OKX_PASSPHRASE`          | OKX Passphrase          | OKX Trading        |

## Tools Overview

| Tool            | Description                     | Requires API Key |
| --------------- | ------------------------------- | ---------------- |
| Yahoo Finance   | Real-time stock market data     | No               |
| CoinGecko       | Cryptocurrency market data      | No               |
| Coinbase        | Cryptocurrency trading and data | Yes              |
| CoinMarketCap   | Cryptocurrency market data      | Yes              |
| Helius          | Solana blockchain data          | Yes              |
| DexScreener     | DEX trading pairs and data      | No               |
| HTX (Huobi)     | Cryptocurrency exchange data    | No               |
| OKX             | Cryptocurrency exchange data    | Yes              |
| EODHD           | Stock market news               | Yes              |
| Jupiter         | Solana DEX aggregator           | No               |
| Sector Analysis | GICS sector ETF analysis        | No               |
| Solana Tools    | Solana wallet and token tools   | Yes              |

## Detailed Documentation

### Yahoo Finance API

Fetch real-time and historical stock market data.

```python
from swarms_tools.finance import yahoo_finance_api

# Fetch data for single stock
data = yahoo_finance_api(["AAPL"])

# Fetch data for multiple stocks
data = yahoo_finance_api(["AAPL", "GOOG", "MSFT"])
```

**Arguments:**

| Parameter     | Type      | Description           | Required |
| ------------- | --------- | --------------------- | -------- |
| stock_symbols | List[str] | List of stock symbols | Yes      |

### CoinGecko API

Fetch comprehensive cryptocurrency data.

```python
from swarms_tools.finance import coin_gecko_coin_api

# Fetch Bitcoin data
data = coin_gecko_coin_api("bitcoin")
```

**Arguments:**

| Parameter | Type | Description                         | Required |
| --------- | ---- | ----------------------------------- | -------- |
| coin      | str  | Cryptocurrency ID (e.g., 'bitcoin') | Yes      |

### Coinbase Trading

Execute trades and fetch market data from Coinbase.

```python
from swarms_tools.finance import get_coin_data, place_buy_order, place_sell_order

# Fetch coin data
data = get_coin_data("BTC-USD")

# Place orders
buy_order = place_buy_order("BTC-USD", amount=100)  # Buy $100 worth of BTC
sell_order = place_sell_order("BTC-USD", amount=0.01)  # Sell 0.01 BTC
```

**Arguments:**

| Parameter | Type                       | Description                    | Required |
| --------- | -------------------------- | ------------------------------ | -------- |
| symbol    | str                        | Trading pair (e.g., 'BTC-USD') | Yes      |
| amount    | Union[str, float, Decimal] | Trade amount                   | Yes      |
| sandbox   | bool                       | Use sandbox environment        | No       |

### CoinMarketCap API

Fetch cryptocurrency market data from CoinMarketCap.

```python
from swarms_tools.finance import coinmarketcap_api

# Fetch single coin data
data = coinmarketcap_api(["Bitcoin"])

# Fetch multiple coins
data = coinmarketcap_api(["Bitcoin", "Ethereum", "Tether"])
```

**Arguments:**

| Parameter  | Type                | Description        | Required |
| ---------- | ------------------- | ------------------ | -------- |
| coin_names | Optional[List[str]] | List of coin names | No       |

### Helius API (Solana)

Fetch Solana blockchain data.

```python
from swarms_tools.finance import helius_api_tool

# Fetch account data
account_data = helius_api_tool("account", "account_address")

# Fetch transaction data
tx_data = helius_api_tool("transaction", "tx_signature")

# Fetch token data
token_data = helius_api_tool("token", "token_mint_address")
```

**Arguments:**

| Parameter  | Type | Description                                        | Required |
| ---------- | ---- | -------------------------------------------------- | -------- |
| action     | str  | Type of action ('account', 'transaction', 'token') | Yes      |
| identifier | str  | Address/signature to query                         | Yes      |

### DexScreener API

Fetch DEX trading pair data.

```python
from swarms_tools.finance import (
    fetch_dex_screener_profiles,
    fetch_latest_token_boosts,
    fetch_solana_token_pairs
)

# Fetch latest profiles
profiles = fetch_dex_screener_profiles()

# Fetch token boosts
boosts = fetch_latest_token_boosts()

# Fetch Solana pairs
pairs = fetch_solana_token_pairs(["token_address"])
```

### HTX (Huobi) API

Fetch cryptocurrency data from HTX.

```python
from swarms_tools.finance import fetch_htx_data

# Fetch coin data
data = fetch_htx_data("BTC")
```

**Arguments:**

| Parameter | Type | Description           | Required |
| --------- | ---- | --------------------- | -------- |
| coin_name | str  | Cryptocurrency symbol | Yes      |

### OKX API

Fetch cryptocurrency data from OKX.

```python
from swarms_tools.finance import okx_api_tool

# Fetch single coin
data = okx_api_tool(["BTC-USDT"])

# Fetch multiple coins
data = okx_api_tool(["BTC-USDT", "ETH-USDT"])
```

**Arguments:**

| Parameter    | Type                | Description           | Required |
| ------------ | ------------------- | --------------------- | -------- |
| coin_symbols | Optional[List[str]] | List of trading pairs | No       |

### EODHD Stock News

Fetch stock market news.

```python
from swarms_tools.finance import fetch_stock_news

# Fetch news for a stock
news = fetch_stock_news("AAPL")
```

**Arguments:**

| Parameter  | Type | Description  | Required |
| ---------- | ---- | ------------ | -------- |
| stock_name | str  | Stock symbol | Yes      |

### Jupiter (Solana DEX)

Fetch Solana DEX prices.

```python
from swarms_tools.finance import get_jupiter_price

# Fetch price data
price = get_jupiter_price(input_mint="input_token", output_mint="output_token")
```

**Arguments:**

| Parameter   | Type | Description               | Required |
| ----------- | ---- | ------------------------- | -------- |
| input_mint  | str  | Input token mint address  | Yes      |
| output_mint | str  | Output token mint address | Yes      |

### Sector Analysis

Analyze GICS sector ETFs.

```python
from swarms_tools.finance.sector_analysis import analyze_index_sectors

# Run sector analysis
analyze_index_sectors()
```

### Solana Tools

Check Solana wallet balances and manage tokens.

```python
from swarms_tools.finance import check_solana_balance, check_multiple_wallets

# Check single wallet
balance = check_solana_balance("wallet_address")

# Check multiple wallets
balances = check_multiple_wallets(["wallet1", "wallet2"])
```

**Arguments:**

| Parameter        | Type      | Description              | Required |
| ---------------- | --------- | ------------------------ | -------- |
| wallet_address   | str       | Solana wallet address    | Yes      |
| wallet_addresses | List[str] | List of wallet addresses | Yes      |

## Complete Example

Here's a comprehensive example using multiple tools:

```python
from swarms_tools.finance import (
    yahoo_finance_api,
    coin_gecko_coin_api,
    coinmarketcap_api,
    fetch_htx_data
)

# Fetch stock data
stocks = yahoo_finance_api(["AAPL", "GOOG"])
print("Stock Data:", stocks)

# Fetch crypto data from multiple sources
bitcoin_cg = coin_gecko_coin_api("bitcoin")
print("Bitcoin Data (CoinGecko):", bitcoin_cg)

crypto_cmc = coinmarketcap_api(["Bitcoin", "Ethereum"])
print("Crypto Data (CoinMarketCap):", crypto_cmc)

btc_htx = fetch_htx_data("BTC")
print("Bitcoin Data (HTX):", btc_htx)
```

## Error Handling

All tools include proper error handling and logging. Errors are logged using the `loguru` logger. Example error handling:

```python
from loguru import logger

try:
    data = yahoo_finance_api(["INVALID"])
except Exception as e:
    logger.error(f"Error fetching stock data: {e}")
```

## Rate Limits

Please be aware of rate limits for various APIs:

- CoinGecko: 50 calls/minute (free tier)
- CoinMarketCap: Varies by subscription
- Helius: Varies by subscription
- DexScreener: 300 calls/minute for pairs, 60 calls/minute for profiles
- Other APIs: Refer to respective documentation

## Dependencies

The package automatically handles most dependencies, but you may need to install some manually:
