1---
2name: charting
3version: 1.0.0
4description: Generate TradingView-style candlestick charts with indicators. Use when the user wants a visual chart, price visualization, or technical analysis plot.
5 
6metadata:
7  starchild:
8    emoji: "📊"
9    skillKey: charting
10    requires:
11      env: [COINGECKO_API_KEY]
12    install:
13      - kind: pip
14        package: mplfinance
15      - kind: pip
16        package: pandas
17      - kind: pip
18        package: numpy
19 
20user-invocable: true
21disable-model-invocation: false
22---
23 
24# Charting
25 
26## ⚠️ CRITICAL: DO NOT CALL DATA TOOLS
27 
28**NEVER** call `price_chart`, `get_coin_ohlc_range_by_id`, `twelvedata_time_series`, or ANY market data tools when creating charts. Chart scripts fetch data internally. Calling these tools floods your context with 78KB+ of unnecessary data.
29 
30**Workflow (4 steps):**
311. Read template from `skills/charting/scripts/`
322. Write script to `scripts/`
333. Run script with `bash`
344. Call `read_file` on the output PNG, then display it using markdown image syntax: `![Chart description](output/filename.png)`
35 
36---
37 
38You generate TradingView-quality candlestick charts. Dark theme, clean layout, professional colors. Every chart is a standalone Python script — no internal imports.
39 
40**Additional Rules:**
41- Chart scripts run in workspace and cannot import from `core`. Use `requests` library directly, NOT `proxied_get()`.
42- Templates include proxy auto-configuration. If `PROXY_HOST` env var exists, scripts automatically configure `HTTP_PROXY`/`HTTPS_PROXY`.
43 
44Tools: `write_file`, `bash`, `read_file`
45 
46## When to Use Which Chart
47 
48**Simple price action** → Candlestick with no indicators. Good for "show me BTC this month."
49**Trend analysis** → Add EMA/SMA overlays. Good for "is ETH in an uptrend?"
50**Momentum check** → Add RSI or MACD as subplots. Good for "is SOL overbought?"
51**Full technical view** → Candles + Bollinger Bands + RSI + MACD. Good for "give me the full picture on BTC."
52**Volume analysis** → Requires separate fetch from market_chart endpoint (OHLC endpoint has no volume).
53**Asset comparison** → Line chart comparing two assets (BTC vs Gold, ETH vs S&P500, etc.). Use comparison template for normalized or percentage-based comparisons.
54 
55## How to Build Charts
56 
57Read and customize the template scripts in `skills/charting/scripts/`:
58- `chart_template.py` — Baseline candlestick chart with TradingView styling (crypto via CoinGecko)
59- `chart_with_indicators.py` — RSI, MACD, Bollinger Bands, EMA/SMA examples (crypto via CoinGecko)
60- `chart_stock_template.py` — Stock/forex chart using Twelve Data API
61- `chart_comparison_template.py` — Compare two assets (crypto vs commodity, stock vs crypto, etc.)
62 
63Copy the relevant template to `scripts/`, customize the config section (coin, days, indicators), and run it.
64 
65The templates handle all data fetching internally with retry logic and error handling.
66 
67**Note:** These templates are for market data visualization (price charts, indicators). For backtest result charts (equity curves, drawdowns, performance dashboards), add matplotlib charting directly to your backtest script — the data is already there, no need to re-fetch or create a separate file.
68 
69## TradingView Color Palette
70 
71| Element | Color | Hex |
72|---------|-------|-----|
73| Up candles | Teal | `#26a69a` |
74| Down candles | Red | `#ef5350` |
75| Background | Dark | `#131722` |
76| Grid | Subtle dotted | `#1e222d` |
77| Text / axes | Light gray | `#d1d4dc` |
78| MA lines | Blue / Orange | `#2196f3` / `#ff9800` |
79| RSI line | Purple | `#b39ddb` |
80| MACD line | Blue | `#2196f3` |
81| Signal line | Orange | `#ff9800` |
82 
83Do not deviate from this palette unless the user asks.
84 
85## Data Source APIs
86 
87### CoinGecko (Crypto Only)
88 
89**Endpoint:** `https://pro-api.coingecko.com/api/v3/coins/{coin_id}/ohlc/range`
90**Auth:** Header `x-cg-pro-api-key: {COINGECKO_API_KEY}`
91**Use for:** BTC, ETH, SOL, and all cryptocurrencies
92 
93Example:
94```python
95url = f"https://pro-api.coingecko.com/api/v3/coins/{COIN_ID}/ohlc/range"
96params = {"vs_currency": "usd", "from": from_ts, "to": now, "interval": "daily"}
97headers = {"x-cg-pro-api-key": os.getenv("COINGECKO_API_KEY")}
98resp = requests.get(url, params=params, headers=headers)
99raw = resp.json()  # [[timestamp_ms, open, high, low, close], ...]
100```
101 
102### Twelve Data (Stocks, Forex, Commodities)
103 
104**Endpoint:** `https://api.twelvedata.com/time_series`
105**Auth:** Query param `apikey={TWELVEDATA_API_KEY}`
106**Use for:** Stocks (AAPL, MSFT), Forex (EUR/USD), Commodities (XAU/USD for gold)
107 
108**Common Symbols:**
109- Stocks: `AAPL`, `MSFT`, `GOOGL`, `TSLA`, `SPY`
110- Forex: `EUR/USD`, `GBP/JPY`, `USD/CHF`
111- Commodities: `XAU/USD` (gold), `XAG/USD` (silver), `CL/USD` (crude oil)
112 
113**Intervals:** `1min`, `5min`, `15min`, `30min`, `1h`, `4h`, `1day`, `1week`, `1month`
114 
115Example:
116```python
117url = "https://api.twelvedata.com/time_series"
118params = {
119    "symbol": "XAU/USD",  # Gold spot price
120    "interval": "1day",
121    "outputsize": 90,  # Number of candles
122    "apikey": os.getenv("TWELVEDATA_API_KEY")
123}
124resp = requests.get(url, params=params)
125data = resp.json()
126# data["values"] = [{"datetime": "2024-01-01", "open": "2050.00", "high": "2060.00", ...}, ...]
127```
128 
129**IMPORTANT:** Twelve Data returns data in **reverse chronological order** (newest first). Always reverse the list before creating a DataFrame:
130```python
131values = data["values"][::-1]  # Reverse to oldest-first
132```
133 
134## Interval Selection Strategy
135 
136The templates now auto-select optimal intervals to minimize data volume while maintaining visual quality:
137 
138| Time Range | Auto-Selected Interval | Rationale |
139|------------|----------------------|-----------|
140| ≤31 days | Hourly | High granularity for short-term analysis |
141| 32-365 days | Daily | Sufficient detail, lower data volume |
142| >365 days | Daily | Daily is optimal for long-term trends |
143 
144**Override:** Set `INTERVAL = "daily"` or `INTERVAL = "hourly"` in the config to override auto-selection.
145 
146## Key Gotchas
147 
148- **`savefig` facecolor**: You MUST set `facecolor='#131722'` and `edgecolor='#131722'` in `savefig`, or the saved PNG reverts to white background.
149- **Title spacing**: Prefix titles with `\n` to add spacing from the top edge.
150- **`returnfig=True`**: Use when you need post-plot customization (price formatting, annotations). When using it, call `fig.savefig()` manually — don't pass `savefig` to `mpf.plot()`.
151- **No volume in OHLC**: CoinGecko OHLC endpoint returns `[timestamp_ms, open, high, low, close]` only. Use `volume=False` or fetch volume separately from `coin_chart` endpoint.
152- **Panel ratios**: Set `panel_ratios` when adding indicator subplots. E.g., `(4, 1, 2)` for candles + volume + one indicator, `(5, 1, 2, 2)` for two indicators.
153- **Figure size**: Default `(14, 8)`. Increase to `(14, 10)` or `(14, 12)` when adding subplots.
154 
155## Rules
156 
157- **Paths are relative to workspace.** Write to `scripts/foo.py`, not `workspace/scripts/foo.py`. The bash CWD is already workspace.
158- **Always save to `output/` directory.** Use `os.makedirs("output", exist_ok=True)`.
159- **Always run the script with `bash("python3 scripts/<name>.py")`** to verify it works.
160- **Always call `read_file` on the generated PNG, then use markdown image syntax to display it:** `![Chart](output/filename.png)`
161- **Scripts must be standalone.** Use `requests` + `os.getenv()`. No internal imports, no dotenv.
162- **CRITICAL: Do NOT use proxied_get() in chart scripts.** Chart scripts are standalone and run in the workspace - they cannot import from `core.http_client`. Always use `requests.get()` and `requests.post()` directly. This is an exception to the PLATFORM.md proxy rules because these scripts execute outside the main Star Child process. The templates demonstrate the correct pattern.
163- **Env vars are inherited.** `os.getenv("COINGECKO_API_KEY")` works directly.
164- **Default to dark theme** unless user asks for light.
165- **Filename should describe the chart.** e.g. `btc_30d_candles.png`, `eth_7d_rsi_macd.png`.
166- **Data sources:** Use CoinGecko API for crypto (BTC, ETH, etc). Use Twelve Data API for stocks, forex, and commodities (AAPL, EUR/USD, XAU/USD for gold). Never mix APIs - keep scripts focused on one data source.
167- **Think about what you're measuring:** Before creating a chart, ask yourself: "What question is the user trying to answer?" A normalized chart (all start at 100) shows relative trends but hides actual gain magnitude. If the user wants to know "which gained more" or is comparing investment performance, they need the actual multipliers (e.g., 50x vs 10x), not just lines that look similar.
168 
169## Troubleshooting
170 
171### 401 Unauthorized Errors
172 
173Templates auto-configure proxy from `PROXY_HOST`/`PROXY_PORT` env vars. If 401 errors occur:
174 
175**Check environment:**
176```bash
177bash("env | grep -E 'PROXY|REQUESTS_CA'")
178```
179 
180**Expected vars:**
181- `PROXY_HOST` / `PROXY_PORT` - Proxy address (templates use these to set HTTP_PROXY/HTTPS_PROXY)
182- `REQUESTS_CA_BUNDLE` - Proxy CA cert for SSL
183- `COINGECKO_API_KEY` / `TWELVEDATA_API_KEY` - Can be fake in proxied environments
184 
185If vars are missing, this is an environment configuration issue, not a script issue.
186