Building an AI agent? Start with /llms.txt for the full site index.

Docs

股票主檔 / Security Master

Security Master read-only API，提供 AI-friendly 身分、覆蓋、血緣與資料缺口上下文。

This documentation page is currently available in Chinese only; English versions are coming soon.

公司主檔

GET/v2/datasets/security-master

Overview

Security Master 提供股票身分主檔（ticker/market/security_type）與 AI context packet，支援 research assistant、agent orchestration 與 dataset coverage 決策。

此頁同步兩個 read-only endpoint：`/v2/datasets/security-master`（列表）與 `/v2/securities/{ticker}`（單一查詢）。

Coverage

Instruments	Start year	Update timing	Includes delisted
Not yet available (coming)	Not yet available (coming)	Not yet available (coming)	coming

Figures are measured from the DB; unlisted fields defer to docs coverage (coming) — we don't fabricate cell by cell.

Status / Scope

Dataset status: private_beta
Source policy: official-first
TWSE official issuer profile: available
TPEx: held for official enrichment

Request

此 endpoint 常見使用情境：

建立 ticker→market/security_type 的 deterministic identity lookup。
在 pipeline 內先判斷 coverage/data_gaps，再決定是否查詢下游 dataset。
提供 agent 以 `source_lineage` 與 `survivorship_bias_warning` 做回答風險約束。

建議接入步驟：

1. 先呼叫 `/v2/datasets/security-master?market=TWSE&active_only=true&limit=50` 查看主檔與 coverage 概況。
2. 再用 `/v2/securities/{ticker}` 拉單一標的 AI context。
3. TPEx 若為 held/unavailable，請依 `data_gaps` 與 `source_lineage` 顯示限制，不要假裝 official 覆蓋。

curl -G "https://api.twmarketdata.com/v2/datasets/security-master" \  -H "X-API-Key: your_api_key_here" \  --data-urlencode "market=TWSE" \  --data-urlencode "active_only=true" \  --data-urlencode "limit=20" \  --data-urlencode "include_ai_context=true"

欄位	型別	Required	說明
market	string	no	市場別篩選（TWSE / TPEx）。可用於列表與單一 ticker 查詢。
symbol	string	no	列表 route 的 symbol 篩選條件（單一查詢 lookup route 用 path ticker）。
active_only	boolean	no	僅回傳 active 標的，預設 true（dataset route）。
limit	integer	no	dataset route 回傳筆數上限。
include_ai_context	boolean	no	dataset route 是否回傳 AI context packet（預設 true）。
include_coverage	boolean	no	lookup route 是否包含 dataset_coverage（預設 true）。
include_data_gaps	boolean	no	lookup route 是否包含 data_gaps（預設 true）。

Response

回應重點 section：`security_identity`、`market_identity`、`dataset_coverage`、`source_lineage`、`data_gaps`。

同時提供 `safe_usage_notes`、`survivorship_bias_warning`、`available_tools_or_endpoints`。

{  "dataset_id": "security-master",  "items": [    {      "security_identity": {"ticker": "2330", "name_zh": "台灣積體電路製造股份有限公司", "market": "TWSE"},      "market_identity": {"market": "TWSE", "source_provider": "twse_official", "source_role": "official_twse_issuer_profile"},      "dataset_coverage": {"price": "available", "technical_indicators": "available"},      "source_lineage": {"source_policy": "official_first"},      "data_gaps": [],      "safe_usage_notes": ["not_investment_advice"],      "survivorship_bias_warning": {"enabled": true}    }  ],  "available_tools_or_endpoints": [    {"name": "security_master_lookup", "contract": "security_master_lookup(ticker, market?, include_coverage?, include_data_gaps?)"}  ]}

Field 說明

欄位路徑	型別	說明
items[].security_identity	object	ticker/name/security_type/is_active 等主體識別欄位。
items[].market_identity	object	market/source_provider/source_role/source_confidence。
items[].dataset_coverage	object	各資料家族可用性（available/held/unknown/partial）。
items[].source_lineage	object	official-first lineage 與來源選擇上下文。
items[].data_gaps	array	缺口與限制（如 TPEx official source 未整合）。
items[].safe_usage_notes	array	安全使用註記（含 not_investment_advice）。
survivorship_bias_warning	object	回測使用風險提示（非完整 PIT lifecycle）。
available_tools_or_endpoints	array	可用工具/route（含 MCP tool plan 提示）。

使用建議

current_master_v1：目前不是完整歷史 PIT master。
not_survivorship_safe_for_historical_backtests：不可直接宣稱回測無生存者偏誤。
TPEx official issuer profile 尚未整合，部分 row 應標示 held/unavailable。
FinMind 僅作 benchmark，不是 production source of truth。
非投資建議（not investment advice）。

錯誤與邊界情況

查無 ticker（controlled not found）
資料來源或表不可用（controlled unavailable）

Limitations & notes

Coverage is not the full market or full history; the actual range is defined by the coverage table above and the data_gaps in the response.
Missing data is flagged honestly — we don't fill gaps with estimated values.
The platform focuses on daily-frequency and fundamental data; it does not provide real-time quotes, intraday bars, or cryptocurrencies.
TWSE is the verified baseline; TPEx history depth and adjusted prices are currently beta / deferred, flagged per dataset.

此 API 屬於 TW Market Data 資料集目錄。查看資料集總覽

請求與回應

Request example

curl -G "https://api.twmarketdata.com/v2/datasets/security-master" \  -H "X-API-Key: your_api_key_here" \  --data-urlencode "market=TWSE" \  --data-urlencode "active_only=true" \  --data-urlencode "limit=20" \  --data-urlencode "include_ai_context=true"

Status codes

成功回傳 Security Master AI context

JSON

{  "dataset_id": "security-master",  "items": [    {      "security_identity": {"ticker": "2330", "name_zh": "台灣積體電路製造股份有限公司", "market": "TWSE"},      "market_identity": {"market": "TWSE", "source_provider": "twse_official", "source_role": "official_twse_issuer_profile"},      "dataset_coverage": {"price": "available", "technical_indicators": "available"},      "source_lineage": {"source_policy": "official_first"},      "data_gaps": [],      "safe_usage_notes": ["not_investment_advice"],      "survivorship_bias_warning": {"enabled": true}    }  ],  "available_tools_or_endpoints": [    {"name": "security_master_lookup", "contract": "security_master_lookup(ticker, market?, include_coverage?, include_data_gaps?)"}  ]}