🐧 Loud Penguin

Your frosty financial friend for Discord

---

🐧 About

Waddle waddle!

Meet Loud Penguin — the coolest Discord bot this side of Antarctica! While other bots are out there being all serious, this penguin brings the chill vibes to your financial tracking needs.

What Does This Penguin Do?

Loud Penguin is a feature-rich Discord bot that helps your server stay on top of the financial markets without breaking a sweat (penguins don't sweat anyway 🧊). Whether you're tracking stocks, riding the crypto waves, or converting currencies, this bird's got you covered.

Here's the icy truth:

• 📈 Stock Market Tracking — Real-time quotes, charts, and company info
• 🪙 Cryptocurrency Data — Prices, trending coins, and market caps
• 💱 Forex Rates — Currency conversions at your flippers
• 🔔 Price Alerts — Get notified when prices hit your targets
• 📋 Personal Watchlists — Track your favorite assets
• 📰 Financial News — Stay informed with the latest headlines
• ⏰ Daily Reports — Automated market summaries every trading day
• ⚙️ Server Settings — Customize the bot for your community

Why a Penguin?

Because penguins are:

• Cool under pressure (literally)
• Great at diving deep into data
• Known for their excellent portfolio... of fish
• The only birds that can actually stand the cold hard facts of the market

---

🎣 Functions

Time to see what this penguin can catch!

Command Overview

Command	Description
/stock	Stock market data and analysis
/crypto	Cryptocurrency tracking
/forex	Currency exchange rates
/alerts	Price alert management
/watchlist	Personal watchlist management
/news	Financial news headlines
/settings	Server configuration
/help	Command reference (with penguin jokes!)

---

📈 /stock — Stock Market Commands

Dive into the stock market like a penguin diving for fish!

Subcommand	Usage	Description
quote	/stock quote symbol:AAPL	Get current price, change, and volume
chart	/stock chart symbol:TSLA period:1M	View price chart (1D, 1W, 1M, 3M, 1Y)
info	/stock info symbol:MSFT	Company details, market cap, 52-week range
compare	/stock compare symbols:AAPL,GOOGL,MSFT	Compare multiple stocks side-by-side

Example:

/stock quote symbol:NVDA

🐧 Returns: NVIDIA Corporation at $485.20 (+3.8%) with a penguin-approved analysis!

---

🪙 /crypto — Cryptocurrency Commands

Catch the crypto waves without getting your feathers wet!

Subcommand	Usage	Description
price	/crypto price coin:bitcoin	Current price and 24h change
top	/crypto top limit:10	Top cryptocurrencies by market cap
trending	/crypto trending	What's hot in the crypto world
chart	/crypto chart coin:ethereum period:7d	Price chart for any coin

Example:

/crypto price coin:bitcoin

🧊 Returns: Bitcoin's current price with market data, served ice cold!

---

💱 /forex — Currency Exchange Commands

Convert currencies faster than a penguin slides on ice!

Subcommand	Usage	Description
convert	/forex convert amount:100 from:USD to:EUR	Convert between currencies
rates	/forex rates base:USD	View exchange rates for a base currency

Example:

/forex convert amount:1000 from:USD to:JPY

❄️ Returns: Your converted amount with current exchange rate!

---

🔔 /alerts — Price Alert Commands

Never miss a price movement — this penguin watches while you sleep!

Subcommand	Usage	Description
set	/alerts set symbol:AAPL price:200 direction:above	Create a price alert
list	/alerts list	View all your active alerts
remove	/alerts remove id:abc123	Remove a specific alert
clear	/alerts clear	Remove all your alerts

Example:

/alerts set symbol:BTC price:100000 direction:above

🐧 The penguin will squawk when Bitcoin hits $100k!

---

📋 /watchlist — Watchlist Commands

Build your portfolio of favorites — like a penguin's favorite fishing spots!

Subcommand	Usage	Description
add	/watchlist add symbol:AAPL type:stock	Add to your watchlist
remove	/watchlist remove symbol:AAPL	Remove from watchlist
view	/watchlist view	See your entire watchlist with prices
clear	/watchlist clear	Start fresh with an empty watchlist

Example:

/watchlist add symbol:TSLA type:stock

📋 Tesla added to your watchlist. This penguin approves of electric vehicles!

---

📰 /news — Financial News Commands

Stay informed without drowning in information!

Subcommand	Usage	Description
headlines	/news headlines category:business	Top financial headlines
search	/news search query:Tesla earnings	Search for specific news

Example:

/news headlines category:technology

📰 Returns: Fresh headlines, delivered faster than a penguin mail service!

---

⚙️ /settings — Server Settings Commands

Customize your penguin's behavior for your server!

Subcommand	Usage	Description
view	/settings view	See current server configuration
update	/settings update option:report_channel value:#stocks	Update a setting
reset	/settings reset	Reset to default settings

Available Settings:

• report_channel — Where daily reports are posted
• report_time — When daily reports are sent (default: 4:15 PM ET)
• timezone — Server timezone for scheduling

---

❓ /help — Help Command

Lost in the financial tundra? This penguin's got directions!

/help

Returns a comprehensive guide to all commands, complete with a random penguin joke to brighten your day. Because even in volatile markets, laughter is the best medicine! 🐧

---

🧊 How to Run

Time to break the ice! Follow these steps to get your penguin sliding...

Prerequisites

Before this penguin can waddle, you'll need:

• Node.js 18+ — The penguin's flipper fuel
• MongoDB — Where the penguin stores its fish... I mean, data
• Discord Application — Your penguin's official ID card

Step 1: Clone the Repository

git clone https://github.com/yourusername/loud-penguin.git
cd loud-penguin

Step 2: Install Dependencies

npm install

Step 3: Set Up Environment Variables

Create a .env file in the root directory (or copy from .env.example):

# Required — The penguin won't swim without these! 🐧
DISCORD_TOKEN=your_discord_bot_token
DISCORD_CLIENT_ID=your_discord_application_id
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/loudpenguin

# Required for stocks
FINNHUB_API_KEY=your_finnhub_api_key

# Optional — Extra fish for the penguin
NEWSAPI_API_KEY=your_newsapi_key
ALPHA_VANTAGE_API_KEY=your_alpha_vantage_key
REPORT_TIME=09:00
NODE_ENV=production

Step 4: Get Your API Keys

API	Where to Get It	Cost
Discord Token	Discord Developer Portal	Free
Finnhub	finnhub.io	Free tier available
NewsAPI	newsapi.org	Free tier available
CoinGecko	No key needed!	Free
Open Exchange Rates	No key needed!	Free

Step 5: Build the Project

npm run build

Step 6: Start the Penguin! 🐧

npm start

You should see:

🐧 Loud Penguin is online and ready to waddle!
✅ Connected to MongoDB
✅ 8 slash commands registered
✅ Scheduler active

Development Mode

For development with hot reload:

npm run dev

---

🏔️ Tech Stack

The ice beneath this penguin's feet!

Core Technologies

Technology	Version	Purpose
TypeScript	5.3.3	Type-safe development (no slipping on bugs!)
Discord.js	14.14.1	Discord bot framework
MongoDB	—	Database for watchlists, alerts, settings
Mongoose	8.0.3	MongoDB ODM
Node.js	18+	Runtime environment

APIs (All Free Tier!) 🎉

API	Purpose	Auth Required
Finnhub	Stock quotes, market data	API Key
CoinGecko	Cryptocurrency data	None!
Open Exchange Rates	Forex conversion	None!
NewsAPI	Financial headlines	API Key

Utilities

Package	Purpose
axios	HTTP requests to APIs
node-cron	Scheduled daily reports
winston	Logging (the penguin keeps notes)
express	Health check endpoint
dotenv	Environment variable management

The Penguin's Aesthetic 🎨

• Primary Color: Icy Blue #1E90FF
• Accent Colors: Arctic whites and deep ocean blues
• Emojis: 🐧 🧊 ❄️ 🎣 📈 📉
• Personality: 10+ penguin jokes in rotation
• Vibes: Cool, helpful, occasionally punny

---

📁 Project Structure

loud-penguin/
├── src/
│   ├── index.ts              # Entry point — where the penguin wakes up
│   ├── commands/             # All slash commands
│   │   ├── stock.ts          # Stock market commands
│   │   ├── crypto.ts         # Cryptocurrency commands
│   │   ├── forex.ts          # Currency exchange commands
│   │   ├── alerts.ts         # Price alert commands
│   │   ├── watchlist.ts      # Watchlist commands
│   │   ├── news.ts           # News commands
│   │   ├── settings.ts       # Server settings commands
│   │   └── help.ts           # Help command (with jokes!)
│   ├── services/             # Business logic
│   │   ├── stockService.ts   # Stock API integration
│   │   ├── cryptoService.ts  # Crypto API integration
│   │   ├── forexService.ts   # Forex API integration
│   │   ├── alertService.ts   # Alert management
│   │   ├── newsService.ts    # News API integration
│   │   └── ...
│   ├── models/               # MongoDB schemas
│   ├── utils/                # Helpers and utilities
│   │   ├── embedBuilder.ts   # Discord embed creation
│   │   ├── cache.ts          # API response caching
│   │   ├── logger.ts         # Winston logger setup
│   │   └── scheduler.ts      # Cron job management
│   └── types/                # TypeScript type definitions
├── logs/                     # Log files
├── package.json
├── tsconfig.json
└── .env                      # Your secrets (not committed!)

---

🐟 Contributing

Want to help this penguin fish for more features? Contributions are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

In other words: Do what you want, just don't blame the penguin if something goes wrong! 🐧

---

Made with 🧊 and TypeScript
Stay cool, stay invested!

🐧