Cookie settings
We use essential cookies to keep you signed in and secure, and analytics cookies to improve the product. We never use them for ad tracking.Learn more
Cookie settings
We use essential cookies to keep you signed in and secure, and analytics cookies to improve the product. We never use them for ad tracking.Learn more
Building an AI agent? Start with /llms.txt for the full site index.
Overview
把台股官方資料接上你的程式與 AI 助理——REST API 與 MCP 皆已上線,五分鐘上手。
With a single API key you can query official Taiwan-stock data: prices and adjusted prices, monthly revenue, financial statements, valuation, technical indicators, chips and institutional flows, corporate events and announcements.
api.twmarketdata.com) — any language, any program or AI agent that can make HTTP calls can connect.mcp.twmarketdata.com) — let AI assistants like Claude and Cursor connect in one click, ask in natural language, and let them pick the tools to query.Both query the same official data with the same pricing, credits are identical. Which to use depends on your scenario: REST for writing code, MCP if you want an AI assistant to query Taiwan stocks directly.
In the dashboardcreate a key (starting with sk_live_…). The key is bound to your plan and determines which datasets you can query, your rate limit, and usage. Keep it safe; if it leaks, revoke and recreate it in the dashboard (revoked keys are permanently invalid).
Once MCP is connected, your AI assistant auto-detects all tools; ask it in Chinese or English and it picks the tools to query on its own — you never hand-write any API call.
We authenticate with an API key (X-API-Key header). Below are the clients verified to connect today — each notes exactly where to configure it. The server address is always: https://mcp.twmarketdata.com/mcp, and replace sk_live_你的key with your key.
Run in the terminal:
claude mcp add --transport http tw-market-data \ https://mcp.twmarketdata.com/mcp \ --header "X-API-Key: sk_live_你的key"Verify: claude mcp list shows tw-market-data ✓ connected.
Edit the config file ~/.cursor/mcp.json and add:
{ "mcpServers": { "tw-market-data": { "url": "https://mcp.twmarketdata.com/mcp", "headers": { "X-API-Key": "sk_live_你的key" } } }}After saving, confirm the connection on Cursor's MCP settings page.
Edit mcp.json (macOS: ~/Library/Application Support/Code/User/mcp.json; Windows: %APPDATA%\\Code\\User\\mcp.json; Linux: ~/.config/Code/User/mcp.json):
{ "servers": { "tw-market-data": { "type": "http", "url": "https://mcp.twmarketdata.com/mcp", "headers": { "X-API-Key": "sk_live_你的key" } } }}Or use the command palette MCP: Add Server.
Edit ~/.codex/config.toml:
[mcp_servers.tw_market_data]url = "https://mcp.twmarketdata.com/mcp"http_headers = { "X-API-Key" = "sk_live_你的key" }Edit ~/.gemini/settings.json:
{ "mcpServers": { "tw-market-data": { "url": "https://mcp.twmarketdata.com/mcp", "headers": { "X-API-Key": "sk_live_你的key" } } }}Edit ~/.codeium/windsurf/mcp_config.json (note Windsurf uses serverUrl, not url):
{ "mcpServers": { "tw-market-data": { "type": "streamable-http", "serverUrl": "https://mcp.twmarketdata.com/mcp", "headers": { "X-API-Key": "sk_live_你的key" } } }}These all read mcpServers JSON, same structure as Cursor (url + headers). Raycast instead uses an in-app form: Transport: HTTP + URL + header.
Zed's URL form doesn't accept headers, so you need the mcp-remote adapter. Edit ~/.config/zed/settings.json:
{ "context_servers": { "tw-market-data": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.twmarketdata.com/mcp", "--header", "X-API-Key: sk_live_你的key"] } }}Not yet supported: ChatGPT, Claude Desktop / Claude.ai web. These clients connect via OAuth, which doesn't yet accept this service's API-key connection. One-click OAuth is in development; these clients will be able to connect then — stay tuned. Until then, connect with the developer tools above, or use REST directly.
Once connected, just ask in the chat, for example:
Your AI does this automatically: first list_datasets to find the right dataset → query_dataset to fetch clean JSON → then summarize / compare / filter for you.
| Tool | Purpose | Billing |
|---|---|---|
| list_datasets | List all available datasets (filter by category / plan tier) | Free |
| describe_dataset | See a dataset's fields, semantics, and update cadence | Free |
| query_dataset | Fetch actual data rows (supports individual stocks, date ranges, and as_of point-in-time) | Credits per dataset (same price as REST) |
| find_related | Cross-table / supply-chain relationship reasoning (find joinable data, same-supply-chain stocks) | Free |
Billing: onlyquery_datasetfetching the data body consumes credits, priced from the same SSOT as REST;list_datasets/describe_dataset/find_relatedare free.
as_of)For backtests or agent training, pass query_dataset with as_of='YYYY-MM-DD' — non-real-time data such as financial statements and monthly revenue is filtered by disclosure / announcement date, so the agent sees only what was public at that point, with no leakage of the future. Example:
"Get the income statement knowable for 2330 as of 2023-06-30" → the AI passes as_of=2023-06-30.curl -H "X-API-Key: sk_live_你的key" \ "https://api.twmarketdata.com/v2/datasets/twse-daily-price?symbol=2330&limit=5"You get TSMC's daily bars for the last 5 trading days (OHLC, volume, adjustment info) = success.
/v2/datasets/monthly-revenue?symbol=2330 # 月營收/v2/datasets/income-statement?symbol=2330 # 損益表/v2/datasets/institutional-flow?symbol=2330 # 三大法人買賣超import requestsr = requests.get( "https://api.twmarketdata.com/v2/datasets/twse-daily-price", params={"symbol": "2330", "limit": 20}, headers={"X-API-Key": "sk_live_你的key"},)print(r.json()["rows"])const res = await fetch( "https://api.twmarketdata.com/v2/datasets/monthly-revenue?symbol=2330", { headers: { "X-API-Key": "sk_live_你的key" } },);const data = await res.json();Connect to an AI agent — in any framework that can "call an HTTP API" (LangChain, your own tool, etc.), wrap the GET above as a tool and the agent can query Taiwan stocks itself. The response is clean normalized JSON, ready to feed straight to the model.
X-API-Key: sk_live_… (REST via header; MCP via the claude mcp add --header). The key is bound to your plan and determines which datasets you can query, your rate limit, and monthly usage.For the full dataset list and the credits cost per call, see the dashboard cost table. On the MCP side, your AI can also use list_datasets to list all datasets you currently have access to at any time.Market & prices
Individual TWSE / TPEx daily bars (OHLC, volume, adjusted), adjusted prices (for total-return backtests), market and sector indices, advancers/decliners.
Financials & growth
Monthly revenue (with MoM / YoY), the three financial statements (income / balance sheet / cash flow), financial ratios, valuation (PER / PBR / dividend yield).
Chips & capital flows
Institutional net buy/sell (three major investors), margin trading & short selling, securities lending, institutional holdings / TDCC shareholding dispersion, day trading, large-trader open interest.
Derivatives / convertibles
Daily futures and options data (TAIFEX), daily convertible-bond trades.
Events / risk / dividends
Corporate events and announcements, penalty / legal-risk events, dividends / ex-rights & ex-dividend, alert & disposition.
Technicals / factors / macro
Technical indicators (MA / RSI / MACD…), stock-selection factors, interest rates, global macro, FX, security master, supply chains and classifications.
Note: the "all-market individual daily union (TWSE + TPEx)" is being added; until then, use the separate "TWSE daily" and "TPEx daily" datasets.
null, never fabricated.