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