1---
2name: twelvedata
3version: 2.0.4
4description: |
5  Stocks, forex, and commodities prices: real-time quotes and historical bars.
6 
7  Use when looking up traditional-market prices (e.g. AAPL quote, EUR/USD chart, gold price, SPY history). Not for crypto.
8delivery: script
9metadata:
10  starchild:
11    emoji: "📊"
12    skillKey: twelvedata
13    requires:
14      env:
15        - TWELVEDATA_API_KEY
16 
17user-invocable: false
18disable-model-invocation: false
19 
20---
21 
22# Twelve Data
23 
24Stocks, forex, and commodities price data. **Traditional markets only — not for crypto.**
25 
26## Script Usage
27 
28This skill ships a single `exports.py` with all functions. Call it from a
29`bash` block:
30 
31```bash
32python3 - <<'EOF'
33import sys, json
34sys.path.insert(0, "/data/workspace/skills/twelvedata")
35from exports import twelvedata_price, twelvedata_quote, twelvedata_time_series
36 
37# Single quote
38print(twelvedata_quote(symbol="AAPL"))
39 
40# Time series (last 30 daily candles)
41series = twelvedata_time_series(symbol="AAPL", interval="1day", outputsize=30)
42print(json.dumps(series.get("values", [])[:3], indent=2))
43EOF
44```
45 
46Available functions in `exports.py`: `twelvedata_price`, `twelvedata_quote`,
47`twelvedata_time_series`, `twelvedata_eod`, `twelvedata_quote_batch`,
48`twelvedata_price_batch`, `twelvedata_search`, `twelvedata_stocks`,
49`twelvedata_forex_pairs`, `twelvedata_exchanges`. Read `exports.py`
50directly when you need exact signatures.
51 
52 
53## Function Reference (signatures)
54 
55All functions are in `exports.py`. Symbols use TwelveData format (e.g. `AAPL`,
56`EUR/USD`, `XAU/USD`). Use `prepost=True` for pre/post-market data on
57US stocks.
58 
59| Function | Description |
60|---|---|
61| `twelvedata_price(symbol, prepost=False)` | Current price for one symbol. |
62| `twelvedata_price_batch(symbols, prepost=False)` | Prices for multiple symbols (`symbols` = comma-separated string). |
63| `twelvedata_quote(symbol, prepost=False)` | Detailed quote: price, volume, 52w high/low, change %. |
64| `twelvedata_quote_batch(symbols, prepost=False)` | Detailed quotes for multiple symbols. |
65| `twelvedata_time_series(symbol, interval='1day', outputsize=30, start_date=None, end_date=None, prepost=False)` | OHLCV bars. `interval` = `1min`/`5min`/`15min`/`30min`/`1h`/`2h`/`4h`/`1day`/`1week`/`1month`. |
66| `twelvedata_eod(symbol, date=None, prepost=False)` | End-of-day price for a date (default: latest). |
67| `twelvedata_search(query)` | Search symbols by name or ticker. |
68| `twelvedata_stocks(exchange=None, country=None)` | List supported stocks (filterable). |
69| `twelvedata_forex_pairs()` | List all supported forex pairs. |
70| `twelvedata_exchanges()` | List supported exchanges. |
71 
72## Keyword → Tool Lookup
73 
74| User asks about | Tool | NOT this |
75|----------------|------|----------|
76| "AAPL 股价", "current price" (single) | `twelvedata_quote` | Not `twelvedata_price` (less detail) |
77| "just the price number" | `twelvedata_price` | — |
78| "多只股票对比" (2+ symbols) | `twelvedata_quote_batch` | Not multiple `twelvedata_quote` calls |
79| "K线", "历史数据", "time series" | `twelvedata_time_series` | — |
80| "收盘价" | `twelvedata_eod` | — |
81| "找股票代码" | `twelvedata_search` | — |
82| "NASDAQ 有哪些股票" | `twelvedata_stocks` | — |
83| "汇率", "EUR/USD" | `twelvedata_quote(symbol="EUR/USD")` | — |
84| "外汇对列表" | `twelvedata_forex_pairs` | — |
85| "金价", "oil price" | `twelvedata_quote(symbol="XAU/USD")` | Not CoinGecko |
86| "BTC price", any crypto | **CoinGecko** `coin_price` | ❌ Never twelvedata for crypto |
87 
88## TwelveData vs CoinGecko — Boundary
89 
90| Asset class | Use | Why |
91|-------------|-----|-----|
92| Stocks (AAPL, TSLA) | **TwelveData** | CoinGecko has no stocks |
93| Forex (EUR/USD) | **TwelveData** | CoinGecko has no forex |
94| Commodities (gold, oil) | **TwelveData** | CoinGecko has no commodities |
95| Crypto (BTC, ETH, SOL) | **CoinGecko** | TwelveData crypto data is limited/unreliable |
96 
97## MISTAKES — Read Before Calling
98 
99### ❌ MISTAKE 1: Using TwelveData for crypto
100```
101User: "BTC 价格"
102❌ WRONG: twelvedata_quote(symbol="BTC/USD")
103✅ RIGHT: coin_price(ids="bitcoin")  ← CoinGecko
104```
105 
106### ❌ MISTAKE 2: Calling quote individually for multiple stocks
107```
108User: "AAPL MSFT GOOGL 现在什么价"
109❌ WRONG: twelvedata_quote("AAPL"), twelvedata_quote("MSFT"), twelvedata_quote("GOOGL")  ← 3 calls
110✅ RIGHT: twelvedata_quote_batch(symbols=["AAPL", "MSFT", "GOOGL"])  ← 1 call, up to 120 symbols
111```
112 
113### ❌ MISTAKE 3: Forex without slash
114```
115❌ WRONG: twelvedata_quote(symbol="EURUSD")
116✅ RIGHT: twelvedata_quote(symbol="EUR/USD")  ← always slash format
117```
118Also: `USD/CNH` not `USDCNH`, `GBP/JPY` not `GBPJPY`.
119 
120### ❌ MISTAKE 4: Expecting bid/ask from quote
121```
122❌ WRONG: "EUR/USD bid: 1.0850, ask: 1.0852"  ← quote only returns close
123✅ RIGHT: "EUR/USD current price: 1.0851 (close/last price — bid/ask spread not available)"
124```
125 
126### ❌ MISTAKE 5: Wrong interval format
127```
128❌ WRONG: twelvedata_time_series(interval="1D")  ← uppercase
129✅ RIGHT: twelvedata_time_series(interval="1day")
130```
131Valid: `1min`, `5min`, `15min`, `30min`, `1h`, `2h`, `4h`, `8h`, `1day`, `1week`, `1month`
132 
133### ❌ MISTAKE 6: Using full output when compact suffices
134```
135User: "AAPL 最近走势"
136❌ WRONG: twelvedata_time_series(symbol="AAPL", interval="1day", outputsize="full")  ← 5000 candles
137✅ RIGHT: twelvedata_time_series(symbol="AAPL", interval="1day", outputsize="compact")  ← 30 candles
138```
139Use `full` only when user explicitly needs deep history.
140 
141## Symbol Reference
142 
143### Commodities (verified)
144 
145| Asset | Symbol |
146|-------|--------|
147| Gold | `XAU/USD` |
148| Silver | `XAG/USD` |
149| Platinum | `XPT/USD` |
150| Palladium | `XPD/USD` |
151| Crude Oil (WTI) | `WTI/USD` |
152| Natural Gas | `NG/USD` |
153 
154### Popular Forex Pairs
155 
156| Pair | Symbol |
157|------|--------|
158| Euro / USD | `EUR/USD` |
159| GBP / USD | `GBP/USD` |
160| USD / JPY | `USD/JPY` |
161| USD / CNH | `USD/CNH` |
162 
163Use `twelvedata_search` to discover others.
164 
165## Pre/Post-Market Data
166 
167```
168twelvedata_quote(symbol="AAPL", prepost=true)
169twelvedata_time_series(symbol="AAPL", interval="1min", prepost=true)
170```
171Returns `premarket_change`, `premarket_change_percent`, `postmarket_change`, `postmarket_change_percent` when available.
172 
173## Output Sizes
174 
175- `compact` — Last 30 data points (default, faster). Use for "最近走势".
176- `full` — Up to 5000 data points. Use for deep analysis / charting.
177 
178## Proxy-Safe Usage
179 
1801. **Agent tool calls**: Always prefer `twelvedata_*` tools (this skill).
1812. **Platform code** (`skills/`, `tools/`): use `core.http_client`.
1823. **Workspace scripts** (`bash`): Do NOT call TwelveData directly. Use skill tools.
183 
184## Compound Queries
185 
186### Stock Comparison
187```
1881. twelvedata_quote_batch(symbols=["AAPL", "MSFT", "GOOGL", "TSLA"])
1892. twelvedata_time_series(symbol="AAPL", interval="1day", outputsize="compact")  ← only for the one user cares most about
190```
191 
192### Macro Dashboard (stocks + forex + commodities)
193```
1941. twelvedata_quote_batch(symbols=["SPY", "QQQ"])          → US indices
1952. twelvedata_quote_batch(symbols=["EUR/USD", "USD/JPY"])   → Forex
1963. twelvedata_quote(symbol="XAU/USD")                       → Gold
197```
198