A free, crypto-focused AI chatbot with a web UI, live USD spot prices (CoinGecko), and headlines from crypto RSS feeds (CoinDesk, Decrypt, BeInCrypto). The brain uses either Groq (free cloud, no local install) or Ollama (fully local).
There is no separate frontend dev server — uvicorn serves frontend/ and the API on http://127.0.0.1:8000.
Disclaimer: Crypto ChatPal is for education and information only — not financial advice. AI outputs can be wrong; crypto is high risk. Stjepan Paun is not a licensed financial adviser and is not liable for trading losses. See DISCLAIMER.md (English + Deutsch).
| Path | Purpose |
|---|---|
backend/main.py |
FastAPI app: chat, prices, news, paper outcomes; serves static frontend/ |
backend/llm_tools.py |
Groq tools (prices, headlines, macro, F&G, on-chain, trade card) |
backend/paper.py |
Paper-trade outcome scoring vs historical CoinGecko USD |
backend/memory.py |
Per-user vector memory (sqlite-vec + sentence-transformers) |
backend/war_room.py |
Bull / Bear / Referee war-room prompts and message builders |
backend/mcp_server.py |
stdio MCP server for Claude Desktop, Cursor, ChatGPT |
backend/prices.py |
CoinGecko live prices (cached), shared with chat context |
backend/news.py |
RSS headline aggregation (cached), shared with chat context |
backend/accounts.py |
SQLite API keys (hashed) and per-day usage counters |
backend/saas_middleware.py |
Optional /api/* auth, rate limits, usage on successful responses |
backend/admin_routes.py |
POST /api/admin/keys, GET /api/me/usage |
backend/redis_cache.py |
Redis read-through cache helpers and shared rate-limit windows |
frontend/index.html |
Page structure only |
frontend/css/style.css |
Layout and visual design |
frontend/js/app.js |
Chat + prices + news panel behavior |
frontend/js/offline-llm.js |
WebLLM wrapper for offline in-browser chat |
frontend/sw.js |
PWA service worker (shell precache) |
requirements.txt |
Python dependencies |
docker-compose.yml |
Optional Redis (--profile cache) + named volume for .data (accounts DB) |
.env / .env.example |
Groq/Ollama, optional REDIS_URL, optional CCP_* tenant settings |
-
Create a free API key at console.groq.com.
-
In the project root, copy
.env.exampleto.envand set:GROQ_API_KEY=gsk_your_key_here
-
Install and run (from the project root):
py -3.14 -m venv venv .\venv\Scripts\activate python -m pip install -r requirements.txt python -m uvicorn backend.main:app --reload --reload-dir backend --reload-dir frontend
Do not use bare
--reloadwithout--reload-dir— StatReload watches the whole project includingvenv/and can loop forever or block port 8000.On Windows, prefer
py -3.14 -m venv(python.org) over MSYS2’spython— mingw builds often lack wheels forpydantic-core/watchfilesand fail without Rust.If imports fail (
BaseMetadata,anyio.to_thread), the venv may be corrupted — purge pip cache and reinstall:python -m pip cache purgethenpython -m pip install --no-cache-dir -r requirements.txt. -
Open http://127.0.0.1:8000. You should see the chat and the Live prices + Latest news column on the right (stacked below the chat on narrow screens).
-
Install Ollama (Windows installer) and keep the app running (system tray).
-
Pull the default model:
ollama pull llama3.2 ollama list -
In
.env, remove or leave emptyGROQ_API_KEY. If agsk_…key is still set, the app uses Groq, not Ollama. -
Optional:
OLLAMA_MODEL=llama3.2,OLLAMA_URL=http://localhost:11434. -
Run the server as in the Groq quick start (same
uvicorncommand). -
Open http://127.0.0.1:8000 and chat.
Ollama-only limits: no chart screenshot vision, no Groq tool loop / multi-model routing — text chat, prices, news, and session desk still work. Test Ollama: ollama run llama3.2 "hi".
Use .env.example as the checklist for every variable (each is commented there).
If .env has… |
Backend uses |
|---|---|
GROQ_API_KEY=gsk_… (non-empty) |
Groq (cloud) |
No / empty GROQ_API_KEY |
Ollama at OLLAMA_URL (default http://localhost:11434) |
- Groq:
GROQ_API_KEY; optionalGROQ_MODELwhenGROQ_MODEL_ROUTING=0. With routing on (default):GROQ_FAST_MODEL(8b Q&A),GROQ_TRADE_MODEL(70b trades),GROQ_VISION_MODEL(chart images). See.env.example. - Ollama:
OLLAMA_MODEL(defaultllama3.2),OLLAMA_URLif Ollama runs elsewhere. - News RSS: optional
NEWS_CACHE_SECONDS(default300),NEWS_MAX_HEADLINES_LLM(default18),NEWS_USER_AGENT.
Port 8000 busy? Stop the old uvicorn process or use --port 8001.
If REDIS_URL is set (for example redis://redis:6379/0 when using Docker Compose), the server uses Redis for price and news read-through cache and for per-key / per-IP rate limits, so behavior is consistent across multiple workers. Without Redis, those features fall back to in-process memory (fine for one process; not shared across processes).
Compose: docker compose --profile cache up -d, then point REDIS_URL at the redis service as in .env.example.
By default the app stays open (no tenant API key). For SaaS-style controls:
| Variable | Role |
|---|---|
CCP_AUTH_MODE |
off (default), optional (validate key when present), or required (HTTP /api/* and live WebSocket need a valid key). |
CCP_ADMIN_SECRET |
Protects POST /api/admin/keys via header X-CCP-Admin-Secret. Use a long random value in production. |
CCP_ACCOUNTS_DB |
Optional SQLite path; default .data/ccp_accounts.sqlite (gitignored). |
CCP_KEY_PEPPER |
Pepper for hashing stored keys; change the default in production. |
CCP_RATE_LIMIT_PER_KEY, CCP_RATE_LIMIT_ANON_IP, CCP_RATE_LIMIT_WINDOW_SEC |
Fixed-window limits; anonymous IP bucket applies without a key or when auth is off/optional. |
Bootstrap a key: POST /api/admin/keys with the admin header; optional JSON body {"label":"my laptop"}. The JSON response includes api_key once (prefix ccp_sk_…); the server only stores a hash.
Calling the API: header X-CCP-API-Key or Authorization: Bearer <your ccp_sk_… key>. GET /api/me/usage?days=14 returns daily request totals for that key.
Web UI with required auth: set browser localStorage key ccp_api_key to your secret so requests send X-CCP-API-Key and the live socket uses ?api_key=... (custom WebSocket headers are awkward in browsers).
Usage accounting: successful /api/* responses increment per-key daily counters when a key is attached. Paths such as /api/health, /api/metrics, /api/admin, /docs, /redoc, and /openapi.json are excluded from that behavior.
Docker: docker-compose.yml mounts a named volume at /app/.data so the default accounts database survives container recreation.
Default feeds (crypto news):
-
CoinDesk —
https://www.coindesk.com/arc/outboundfeeds/rss/ -
Decrypt —
https://decrypt.co/feed -
BeInCrypto —
https://beincrypto.com/feed/(often returns HTTP 403 to automated/server IPs; if so, that source contributes no items until it succeeds) -
GET /api/news— JSON for the UI (cached). -
Chat — each request includes a text snapshot of recent headlines (source + title + link + short snippet) so the model can discuss them with attribution.
Sentiment labels in the UI are rough keyword heuristics, not financial analysis.
- The UI polls
GET /api/pricesevery second so you do not need to refresh the page. - CoinGecko is not queried every second (that would hit rate limits). The server caches responses for 10 seconds by default (
PRICE_CACHE_SECONDSin.envif you want a different interval). - Each chat request uses the same cached snapshot in context (from
backend/prices.py). - Data comes from CoinGecko public API (free tier; rate limits may apply). No CoinGecko key is required for basic use.
- Groq: free tier with limits; check Groq’s current policy.
- Ollama: no API cost when running models locally.
- CoinGecko: public API within free-tier limits.
- In the chat input area, use Attach to add up to 5 text files per send.
- Allowed: common text types (e.g.
.md,.txt,.csv,.json,.log) and othertext/*MIME types; each file is capped at 256 KB on the client. - File contents are read in the browser and merged into the outgoing user message for that request only. They are not uploaded to a separate server storage.
- Saved chat history stores your message plus a line like
(Attached: README.md)so you know what you sent; it does not re-store full file bodies. To discuss the same file again in a later turn, attach it again. - The API accepts up to 200,000 characters per message body (including merged attachment text); very large pastes may be rejected.
- No server or API cost — uses the browser’s built-in speech recognition and synthesis (Chrome/Edge work best).
- Mic (input row): tap to start/stop dictation; transcript fills the message box (edit, then Send).
- Toolbar Mic / Speaker: toggle voice input and auto-read new assistant replies.
- Each assistant message gets Listen / Stop for on-demand read-aloud.
- Requires microphone permission for input; uses
localStoragekeyscryptochatpal_voice_inputandcryptochatpal_voice_output.
- In the Coin prices editor, click Share watchlist — a short URL like
http://127.0.0.1:8000/#wl.Yml0Y29...is copied to the clipboard. - Anyone opening that link gets a confirm prompt to load the watchlist (replaces their current one).
- No server upload — the entire list is encoded in the URL hash (base64url,
#wl.prefix). Compact enough to paste in chat, DMs, or social posts. - Supports up to 30 coins; coin ids and short labels are preserved.
- Use the Light and Dark buttons in the page header to switch themes.
- The choice is saved in the browser (
localStoragekeycryptochatpal_theme) and applied on the next visit.
- The UI calls
POST /api/chat/stream, which streams the assistant reply as NDJSON (one JSON object per line: text chunks in{"c":"..."}, then{"done":true,"model":"..."}). - Groq and Ollama both stream; the same price and news context is injected as for
/api/chat.
- Turn on Agent in the chat toolbar (saved in
localStorageascryptochatpal_agent_mode). - Groq only — requires
GROQ_API_KEYandLLM_TOOLS=1(default). Ollama does not run the tool loop. - The model chains tools before answering, e.g. live prices → Binance funding/OI → Fear & Greed → headlines/macro → structured trade card.
- Extra tools:
get_fear_greed,get_onchain_derivatives(plus the standard price/headline/macro/trade tools). - Uses the 70b trade model with up to
LLM_AGENT_MAX_TOOL_ROUNDSsteps (default 12; normal chat uses 8). - While thinking, the status line shows steps like
Agent: Funding & flows (step 2)via NDJSON{"agent_step":{...}}. - Request body:
"agent_mode": trueon/api/chatand/api/chat/stream.
- Turn on War room in the chat toolbar (mutually exclusive with Agent; saved as
cryptochatpal_war_room_mode). - Groq only — runs three calls: Bull and Bear in parallel (8b, injected context), then Referee (70b) synthesizes the final answer.
- UI shows a 3-panel view: Bull | Bear on top, Referee final answer below (also in the main reply area).
- Referee may call
emit_trade_analysisfor structured trade output on buy/sell questions. - Slower (~3× API calls) but useful for trade decisions. Optional
WAR_ROOM_DEBATE_MAX_TOKENS(default1024) caps bull/bear length. - Request body:
"war_room_mode": true. Does not support chart image uploads yet.
Expose the same price / news / macro tools to any MCP client — no Groq key needed for data tools.
| Tool | Description |
|---|---|
get_prices |
CoinGecko USD spot + 24h change |
get_crypto_headlines |
Crypto RSS headlines |
get_macro_snapshot |
Oil/metals + Fed headlines |
get_fear_greed |
Fear & Greed index |
get_onchain_derivatives |
Binance funding, OI, positioning |
get_macro_radar |
FOMC / CPI / SEC within 48h |
From the project root (venv activated):
python -m backend.mcp_serverOr double-click run_mcp.bat on Windows. The process speaks MCP over stdin/stdout — leave it running; the client spawns it automatically when configured.
- Settings → MCP → Add server (or edit
~/.cursor/mcp.json). - Copy paths from
mcp_config.example.json— setcommandto your venv Python andcwdto this repo. - Restart Cursor; tools appear as cryptochatpal.
Example:
{
"mcpServers": {
"cryptochatpal": {
"command": "C:/Users/YOU/.../CryptoChatPal/venv/Scripts/python.exe",
"args": ["-m", "backend.mcp_server"],
"cwd": "C:/Users/YOU/.../CryptoChatPal"
}
}
}Edit %APPDATA%\\Claude\\claude_desktop_config.json with the same mcpServers block (use forward slashes in paths).
Add a custom MCP connector (Desktop app → Settings → Connectors) pointing at the same command + args if your plan supports local MCP.
- Install deps:
pip install -r requirements.txt(includesmcp). - Uses
.envfor optionalREDIS_URL, cache TTLs, etc. — same as the web app. - Do not run uvicorn and debug-print inside the MCP process; stdout is the protocol stream.
The app is a PWA (manifest.json + sw.js). The service worker precaches the UI shell so the page loads without network after one visit.
- Toolbar Offline AI — use the in-browser model instead of Groq/Ollama when checked, or automatically when the browser is offline.
- Download AI — one-time download of Llama-3.2-1B (~1 GB, WebLLM via CDN); falls back to SmolLM2-360M on low memory. Weights stay in the browser cache for later offline use.
- Requires Chrome or Edge with WebGPU. Not a replacement for cloud trade tools / war room / vision — offline chat is text-only with cached market context.
- Last prices and headlines are saved to
localStorage(cryptochatpal_offline_market_snap) whenever the live panels update.
- Open the app while online.
- Click Download AI and wait for the progress line in the toolbar to finish.
- Use the app normally once (prices/news cache fills).
- Go offline (or enable Offline AI) and chat still works for general crypto Q&A with stale cached numbers.
- First visit still needs network (WebLLM library + model weights from CDN).
- No live prices, news, or API tools while fully offline unless previously cached in the UI.
- Agent mode, war room, chart vision, and MCP require network + server.
- In the right column, under the price editor, Portfolio lets you track holdings by CoinGecko id: amount and optional average buy price (USD).
- Value and unrealized P/L use the same live prices as the watchlist (
GET /api/prices). Coins only in the portfolio are still fetched (IDs are merged into one request). - Everything is stored in
localStorage(cryptochatpal_portfolio); nothing is sent to a server except the existing public price API.
- FOMC, CPI, and SEC events from official
.govschedules (Fed, BLS, SEC), cached ~1h. - Shows amber banners above the chat when something falls in the next 48 hours (configurable via
MACRO_RADAR_WINDOW_HOURS). GET /api/macro/radar— JSON for the UI; the same summary is injected into chat context when events are active.- WebSocket
macropushes include aradarfield when live feed is connected.
- Each browser gets a stable
memory_user_id(localStorage→cryptochatpal_memory_user, also sent asX-CCP-Memory-User). - After each chat turn, user + assistant text is embedded and stored in sqlite-vec (
.data/ccp_memory.sqliteby default). - Before the next reply, the server retrieves the top similar past snippets and injects them as a system block.
- Session desk → Vector memory shows chunk count; Clear my memory calls
DELETE /api/memory. - Requires
pip install -r requirements.txt(sqlite-vec,sentence-transformers,numpy). First chat after install downloads the embedding model (~80MB). SetCCP_MEMORY_ENABLED=0to disable. - With CCP API keys, memory is scoped per key (
key_<id>) instead of the browser id.
- Open Session desk from the chat toolbar for a Market pulse (0–100): a blend of your watchlist 24h volatility and RSS headline sentiment counts from the left column.
- Paper trading / backtest: each
emit_trade_analysisreply is stored inlocalStorage(cryptochatpal_paper_trades) with entry USD, coin id, and full structured fields. After 24h and 7d, the UI callsGET /api/paper/outcome(CoinGecko historical USD) and scores aligned / mixed / missed vs the stated view (buy/sell/hold). Optionalcoin_gecko_idin the tool output improves asset detection. - Stance log: when the assistant replies using the structured trade format (lines like
View:,Confidence:,Score:), those fields are parsed and appended automatically (stored inlocalStorageundercryptochatpal_stance_ledger, last 24 entries). - Export snapshot downloads a JSON file with the current pulse readout, paper trades, and stance log (handy for journaling or sharing what the UI “saw” in that session).
- Change structure in
frontend/index.html. - Change look (colors, spacing, layout) in
frontend/css/style.css. - Change behavior (chat, price refresh, news refresh) in
frontend/js/app.js.
After edits, refresh the browser; with --reload, the server restarts when Python files change.
From the project root (with your venv activated):
python -m pip install -r requirements.txt
ruff check backend tests
pytest -q