finclaw
# FinClaw — AI Finance Assistant
Your personal finance assistant covering **US stocks**, **BIST (Turkish market)**, **crypto**, and **forex**. Includes portfolio tracking, price alerts, charts, technical analysis, daily briefings, and more.
## First-Time Setup
Run once after installation to create the Python venv and database:
```bash
python3 {baseDir}/scripts/setup.py
```
Then add to `openclaw.json` under `skills.entries`:
```json
"finclaw": {
"env": {
"FINNHUB_API_KEY": "",
"FRED_API_KEY": "",
"ALPHA_VANTAGE_API_KEY": "",
"EXCHANGE_RATE_API_KEY": ""
}
}
```
API keys are optional — core features (prices, charts, TA, portfolio, alerts) work without any keys.
## Running Scripts
All scripts use the skill's Python venv:
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/<script>.py [args]
```
---
## Market Data
### quote.py — Real-Time Quotes
Auto-detects asset type from symbol. Results cached for 60 seconds.
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/quote.py AAPL # US stock
{baseDir}/venv/bin/python3 {baseDir}/scripts/quote.py THYAO.IS # BIST stock
{baseDir}/venv/bin/python3 {baseDir}/scripts/quote.py BTC # Crypto
{baseDir}/venv/bin/python3 {baseDir}/scripts/quote.py USD/TRY # Forex
{baseDir}/venv/bin/python3 {baseDir}/scripts/quote.py AAPL MSFT BTC # Multiple
{baseDir}/venv/bin/python3 {baseDir}/scripts/quote.py AAPL --force # Skip cache
{baseDir}/venv/bin/python3 {baseDir}/scripts/quote.py AAPL --json # JSON output
```
**Symbol detection:** `.IS` → BIST | `BTC/ETH/SOL...` → Crypto | `USD/TRY` → Forex | else → US stock
### crypto.py — Crypto Market Data
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/crypto.py price BTC # Binance price
{baseDir}/venv/bin/python3 {baseDir}/scripts/crypto.py top --limit 10 # Top gainers
{baseDir}/venv/bin/python3 {baseDir}/scripts/crypto.py try BTC # Price in TRY
```
### forex.py — Exchange Rates
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/forex.py rate USD TRY
{baseDir}/venv/bin/python3 {baseDir}/scripts/forex.py convert USD TRY --amount 1000
{baseDir}/venv/bin/python3 {baseDir}/scripts/forex.py multi USD --targets TRY EUR GBP
```
### chart.py — Price Charts
Generates PNG charts. Send the saved file to the user.
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/chart.py AAPL # Candlestick
{baseDir}/venv/bin/python3 {baseDir}/scripts/chart.py BTC --type line --period 1y # Line chart
{baseDir}/venv/bin/python3 {baseDir}/scripts/chart.py AAPL --sma 20 50 200 # With SMAs
```
Periods: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, max
### technical.py — Technical Analysis
SMA, EMA, RSI, MACD, Bollinger Bands with buy/sell signals.
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/technical.py AAPL
{baseDir}/venv/bin/python3 {baseDir}/scripts/technical.py BTC --period 1y --json
```
### news.py — Financial News (requires FINNHUB_API_KEY)
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/news.py company --symbol AAPL
{baseDir}/venv/bin/python3 {baseDir}/scripts/news.py market --category crypto
```
### screener.py — Stock Screener
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/screener.py us # US gainers
{baseDir}/venv/bin/python3 {baseDir}/scripts/screener.py bist --direction bottom # BIST losers
{baseDir}/venv/bin/python3 {baseDir}/scripts/screener.py crypto --limit 15 # Crypto gainers
```
---
## Portfolio & Alerts
### portfolio.py — Position Management
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/portfolio.py add --symbol AAPL --shares 10 --price 150
{baseDir}/venv/bin/python3 {baseDir}/scripts/portfolio.py sell --symbol AAPL --shares 5 --price 175
{baseDir}/venv/bin/python3 {baseDir}/scripts/portfolio.py remove --symbol AAPL
{baseDir}/venv/bin/python3 {baseDir}/scripts/portfolio.py list
{baseDir}/venv/bin/python3 {baseDir}/scripts/portfolio.py summary
```
Optional: `--fees 1.50`, `--date 2024-01-15`, `--name "Apple Inc"`, `--notes "Long hold"`
### alerts.py — Price Alerts
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/alerts.py create --symbol AAPL --condition above --target 200
{baseDir}/venv/bin/python3 {baseDir}/scripts/alerts.py create --symbol BTC --condition below --target 60000 --note "Buy signal"
{baseDir}/venv/bin/python3 {baseDir}/scripts/alerts.py list
{baseDir}/venv/bin/python3 {baseDir}/scripts/alerts.py delete --id 3
{baseDir}/venv/bin/python3 {baseDir}/scripts/alerts.py snooze --id 3 --hours 48
```
Conditions: `above`, `below`, `change_pct`, `volume_above`
### check_alerts.py — Alert Checker (for cron)
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/check_alerts.py
```
### pnl.py — Profit & Loss
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/pnl.py # All positions
{baseDir}/venv/bin/python3 {baseDir}/scripts/pnl.py --symbol AAPL # Single symbol
```
### watchlist.py — Watchlists
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/watchlist.py create --name "Tech"
{baseDir}/venv/bin/python3 {baseDir}/scripts/watchlist.py add --name "Tech" --symbol AAPL
{baseDir}/venv/bin/python3 {baseDir}/scripts/watchlist.py show --name "Tech" --prices
{baseDir}/venv/bin/python3 {baseDir}/scripts/watchlist.py list
```
---
## Intelligence
### briefing.py — Market Briefings
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/briefing.py morning # Full morning briefing
{baseDir}/venv/bin/python3 {baseDir}/scripts/briefing.py close # End-of-day summary
{baseDir}/venv/bin/python3 {baseDir}/scripts/briefing.py weekend # Weekend crypto + forex recap
```
### macro.py — Macro Economics (requires FRED_API_KEY)
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/macro.py dashboard
{baseDir}/venv/bin/python3 {baseDir}/scripts/macro.py indicator --name fed_rate
{baseDir}/venv/bin/python3 {baseDir}/scripts/macro.py list
```
### earnings.py — Earnings Calendar (requires FINNHUB_API_KEY)
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/earnings.py calendar
{baseDir}/venv/bin/python3 {baseDir}/scripts/earnings.py symbol --symbol AAPL
```
### sentiment.py — News Sentiment (requires ALPHA_VANTAGE_API_KEY)
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/sentiment.py --symbol AAPL
{baseDir}/venv/bin/python3 {baseDir}/scripts/sentiment.py --topics technology
```
### research.py — Deep Research
```bash
{baseDir}/venv/bin/python3 {baseDir}/scripts/research.py AAPL
```
---
## Data Sources
- **US Stocks**: Finnhub (primary), yfinance (fallback) — no key needed
- **BIST**: yfinance with .IS suffix — no key needed
- **Crypto**: Binance API — no key needed
- **Forex**: ExchangeRate-API — works without key
- **Charts/TA**: matplotlib + mplfinance + pandas — local computation
- **News**: Finnhub — needs FINNHUB_API_KEY
- **Macro**: FRED — needs FRED_API_KEY
- **Sentiment**: Alpha Vantage — needs ALPHA_VANTAGE_API_KEY
标签
skill
ai
