Overview
用 2 分鐘建立第一個 TW Market Data API request，完成認證、查詢台股資料，並理解 response 結構。
你可以先從左側導覽查看所有資料集，也可以從本頁直接建立第一個 request。若要讓 agent 或內部工具讀取文件，後續可提供 llms.txt、OpenAPI spec 或 MCP tools 作為入口。
在 TW Market Data 建立帳號後，進入儀表板建立 API key。所有正式 API request 都會使用X-API-Keyheader 進行認證。
目前 access 採 controlled rollout。不同方案會影響可用 dataset、rate limit 與月用量上限。
平台使用輕量 product analytics（非廣告 tracking）來改善登入、API onboarding 與文件體驗；可於網站 analytics 提示選擇關閉。
我們已提供 Python 與 JavaScript SDK skeleton，讓你不需要手寫 fetch/curl。此階段僅為 local/dev preview，尚未發布到 PyPI 或 npm。
相關文件：Python SDK、JavaScript / TypeScript SDK。
SDK / MCP 目前為 preview，完整狀態請看Release Status。
Python SDK
from twmarketdata import TWMarketDataClient client = TWMarketDataClient(api_key="twmd_live_xxx")result = client.twse_daily_price(symbol="2330", limit=1) print(result.meta.request_id)print(result.meta.dry_run)print(result.meta.credits_cost)print(result.data)JavaScript / TypeScript SDK
import { TWMarketDataClient } from "@twmarketdata/sdk"; const client = new TWMarketDataClient({ apiKey: "twmd_live_xxx", baseUrl: "https://twmarketdata.com", timeoutMs: 10000,}); const result = await client.twseDailyPrice({ symbol: "2330", limit: 1 });console.log(result.meta.requestId, result.meta.creditsCost, result.meta.dryRun);console.log(result.data);錯誤處理範例
import { TWMarketDataClient, AuthenticationError, EntitlementError, InsufficientCreditsError, DatasetNotFoundError, UpstreamError,} from "@twmarketdata/sdk"; const client = new TWMarketDataClient({ apiKey: "twmd_live_xxx" }); try { await client.monthlyRevenue({ symbol: "2330", limit: 12 });} catch (error) { if (error instanceof AuthenticationError) console.error("API key 無效"); else if (error instanceof EntitlementError) console.error("方案未開通"); else if (error instanceof InsufficientCreditsError) console.error("credits 不足"); else if (error instanceof DatasetNotFoundError) console.error("dataset 不存在"); else if (error instanceof UpstreamError) console.error("上游異常");}TW Market Data 提供 MCP server skeleton、tool manifest 與 agent workflow 範例，方便你把資料能力接到 Claude、Cursor 或自建 agent tools。
相關文件：MCP Server Preview、Tool Manifest、Agent Workflow Examples。
packages/mcp-serverai-tools/twmd_tools.jsonexamples/agentsMCP skeleton example
cd packages/mcp-servernpm install --ignore-scriptsnpm run build TWMD_API_KEY=twmd_live_xxx \node dist/index.js get_twse_daily_price '{"symbol":"2330","limit":1}'Agent workflow example
# TypeScriptTWMD_API_KEY=twmd_live_xxx node examples/agents/simple_research_agent.ts # PythonTWMD_API_KEY=twmd_live_xxx python3 examples/agents/simple_research_agent.py此區塊為 preview，僅供 local/dev 驗證，未發布為正式套件或託管 MCP service，且不依賴 LLM API key。
Release status matrix：/docs/sdk/release-status
第一個請求建議使用 TWSE 日線價格。這個 endpoint 可查詢上市股票的日線價格、成交量與交易日資料。
Endpoint：GET /v2/datasets/twse-daily-price
X-API-Key headersymbol，例如 2330limitimport requestsbase_url = "https://api.twmarketdata.com"headers = { "X-API-Key": "your_api_key_here",}params = { "symbol": "2330", "limit": 5,}response = requests.get( f"{base_url}/v2/datasets/twse-daily-price", headers=headers, params=params,)data = response.json()print("status:", response.status_code)print("requestId:", response.headers.get("X-Request-Id"))print("dryRun:", response.headers.get("X-TWMD-Dry-Run"))print("creditsCost:", response.headers.get("X-TWMD-Credits-Cost"))print("creditsCharged:", response.headers.get("X-TWMD-Credits-Charged"))print(data)Response example
{ "dataset": "twse_daily_price", "rows": [ { "symbol": "2330", "date": "2026-05-06", "open": 884, "high": 895, "low": 878, "close": 892, "volume": 42168000 } ], "count": 1}回應通常包含 dataset、rows 與 count。不同 dataset 會有不同欄位，但 response pattern 會盡量保持一致。
Gateway dry-run（Beta）
目前可透過官網路徑測試 gateway skeleton：GET /v2/datasets/:dataset。 此階段僅做 entitlement 與成本試算，不會實際扣除 credits。
請使用 Dashboard 建立的 customer API key 放在 X-API-Key。 Gateway 與 backend 溝通使用的是網站伺服器端 internal token（例如 BACKEND_API_TOKEN），與 customer key 不同。
curl \ -H "X-API-Key: twmd_live_xxx" \ "https://twmarketdata.com/v2/datasets/twse-daily-price?symbol=2330&limit=5"dry-run 回應 headers 會包含 X-TWMD-Plan、X-TWMD-Credits-Cost、X-TWMD-Dry-Run=true 與 X-Request-Id。
啟用扣點模式後，回應會包含 X-TWMD-Credits-Charged；credits 不足會回 402 insufficient_credits。X-Request-Id 可提供客服追查。
常見錯誤格式
{ "error": { "code": "invalid_api_key", "message": "Invalid API key." }, "requestId": "..."}常見 code：`401 invalid_api_key`、`403 plan_not_entitled`、`402 insufficient_credits`、`404 dataset_not_found`、`502 upstream_error`、`504 upstream_timeout`。
完成第一個 request 後，可以改查其他常用資料。
Endpoint：GET /v2/datasets/monthly-revenue
import requestsbase_url = "https://api.twmarketdata.com"headers = { "X-API-Key": "your_api_key_here",}response = requests.get( f"{base_url}/v2/datasets/monthly-revenue", headers=headers, params={ "symbol": "2330", "limit": 12, },)data = response.json()print(data)Endpoint：GET /v2/datasets/issuer-profile
import requestsbase_url = "https://api.twmarketdata.com"headers = { "X-API-Key": "your_api_key_here",}response = requests.get( f"{base_url}/v2/datasets/issuer-profile", headers=headers, params={ "symbol": "2330", },)data = response.json()print(data)Endpoint：GET /v2/datasets/technical-indicators
import requestsbase_url = "https://api.twmarketdata.com"headers = { "X-API-Key": "your_api_key_here",}response = requests.get( f"{base_url}/v2/datasets/technical-indicators", headers=headers, params={ "symbol": "2330", "limit": 20, },)data = response.json()print(data)Endpoint：POST /v2/datasets/screener
import requestsbase_url = "https://api.twmarketdata.com"headers = { "X-API-Key": "your_api_key_here",}body = { "filters": [ { "field": "yoy_growth_pct", "operator": "gt", "value": 20, } ], "limit": 10,}response = requests.post( f"{base_url}/v2/datasets/screener", headers=headers, json=body,)data = response.json()print(data)