Building an AI agent? Start with /llms.txt for the full site index.
Overview
Connect official Taiwan market data to your code and your AI assistant — REST API and MCP are both live, and five minutes is enough to start.
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_your_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_your_key"Verify: claude mcp list shows tw-market-data ✓ connected.
Claude Desktop reaches remote MCP servers through the mcp-remote local bridge (it injects the X-API-Key header). Add to claude_desktop_config.json:
{
"mcpServers": {
"tw-market-data": {
"command": "npx",
"args": [
"-y", "mcp-remote", "https://mcp.twmarketdata.com/mcp",
"--transport", "http-only",
"--header", "X-API-Key: sk_live_your_key"
]
}
}
}Restart Claude Desktop; tw-market-data appears in the tools list with its 34 tools.
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_your_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_your_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_your_key" }Edit ~/.gemini/settings.json:
{
"mcpServers": {
"tw-market-data": {
"url": "https://mcp.twmarketdata.com/mcp",
"headers": { "X-API-Key": "sk_live_your_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_your_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_your_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_your_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 # monthly revenue
/v2/datasets/income-statement?symbol=2330 # income statement
/v2/datasets/institutional-flow?symbol=2330 # institutional net buy/sellimport requests
r = requests.get(
"https://api.twmarketdata.com/v2/datasets/twse-daily-price",
params={"symbol": "2330", "limit": 20},
headers={"X-API-Key": "sk_live_your_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_your_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.