API 文件

Tickers & Corporate Action API

台股（TWSE / TPEx）標的資訊、日線歷史（含還原權值）與公司行動事件的唯讀 REST API。回應格式統一、支援游標分頁，並提供 MCP 封裝，讓 Claude 等 LLM 用戶端可以直接呼叫，不需要自己組 HTTP 請求。

Base URL （載入中…） 目前版本 v1 回應格式 JSON 驗證方式 Bearer Token

Getting Started

快速開始

三個步驟：確認服務存活、帶上 API Key、打第一支請求。以下範例可直接複製到終端機執行——網址已自動換成這個頁面目前的網域。

確認服務存活

/healthz 不需要 API Key，回傳純文字 ok，適合當作連線測試或容器健康檢查。
shell
```
curl https://mcp.example.com/healthz
```
準備 API Key

訂閱後由我們核發一把個人專屬的 sk_live_... 金鑰（不是共用金鑰）。所有 /v1/* 端點都需要用 Authorization: Bearer <api_key> 帶上。
shell
```
# PowerShell
$headers = @{ Authorization = "Bearer sk_live_<你的金鑰>" }
```
打第一支請求

查詢台積電（2330.TW）的標的資訊，確認金鑰與服務都正常運作。
shell
```
curl -H "Authorization: Bearer sk_live_<你的金鑰>" \
  https://mcp.example.com/v1/tickers/2330.TW
```

Authentication

身分驗證

每個 /v1/* 請求的 Authorization header 都必須是 Bearer <api_key> 格式。

項目	值	說明
Header	`Authorization`	格式為 `Bearer <api_key>`，缺少或格式錯誤回傳 401。
金鑰格式	`sk_live_...`	訂閱時由我們核發，每位使用者一把，不共用；請妥善保管，外洩請立刻通知我們換發。
限流上限	`50,000` 次 / 日	依金鑰計算，見下方「錯誤與限流」的 `x-ratelimit-*` headers。

金鑰目前是明碼存放、逐一比對（見服務條款），沒有自助簽發/輪替/撤銷入口——需要新金鑰或懷疑外洩，請直接聯絡我們處理，不要自己重複使用同一把金鑰在多個不受信任的環境。

REST API

端點參考

回應一律是 { meta, data, pagination } 的統一結構；meta 帶有 request_id、source、data_as_of，方便追蹤與快取判斷。

GET /v1/tickers 需要 API Key

列出 TWSE／TPEx 標的清單，支援關鍵字搜尋與游標分頁。

參數	型別	說明
q	string	對代號／本地代碼／中英日文名稱做模糊搜尋選填
board	string	`TWSE` 或 `TPEx` 選填
limit	int	單頁筆數，1–1000，預設 100 選填
cursor	string	上一頁回傳的 `pagination.next_cursor` 選填

請求

shell

curl -H "Authorization: Bearer sk_live_..." \
  https://mcp.example.com/v1/tickers?limit=2

回應 200

json

{
  "meta": {
    "request_id": "req_90a649eb...",
    "schema_version": "1.0",
    "source": "TWSE/TPEx",
    "data_as_of": "2026-08-16T23:20:57Z"
  },
  "data": [
    {
      "symbol": "2317.TW",
      "local_code": "2317",
      "board": "TWSE",
      "currency": "TWD",
      "name": { "zh-TW": "鴻海精密工業股份有限公司", "en": "Hon Hai Precision Industry Co., Ltd." }
    },
    { "symbol": "2330.TW", "… 台積電 …" }
  ],
  "pagination": { "next_cursor": "eyJzeW1ib2wi...", "count": 2 }
}

GET /v1/tickers/{symbol} 需要 API Key

取得單一標的 metadata。symbol 格式為 {代碼}.TW（上市）或 {代碼}.TWO（上櫃）。

展開範例

請求

shell

curl -H "Authorization: Bearer sk_live_..." \
  https://mcp.example.com/v1/tickers/2330.TW

回應 200

json

{
  "data": {
    "symbol": "2330.TW",
    "local_code": "2330",
    "board": "TWSE",
    "mic": "XTAI",
    "isin": "TW0002330008",
    "currency": "TWD",
    "name": { "zh-TW": "台灣積體電路製造股份有限公司" }
  }
}

GET /v1/tickers/{symbol}/bars/daily 需要 API Key

單一標的日線歷史。adjusted=true（預設）回傳依公司行動反算的還原權值價格。

參數	型別	說明
from / to	date	YYYY-MM-DD，不填預設近 90 天選填
adjusted	bool	是否回傳還原權值價格，預設 `true` 選填
limit / cursor	int / string	分頁，同上選填

請求

shell

curl -H "Authorization: Bearer sk_live_..." \
  https://mcp.example.com/v1/tickers/2330.TW/bars/daily?from=2024-06-01&to=2024-06-05

回應 200（節錄一筆）

json

{
  "data": [
    {
      "date": "2024-06-03",
      "open": 839.0, "high": 853.0, "low": 837.0, "close": 846.0,
      "volume": 29629706, "trades": 25935030,
      "adj_open": 836.27, "adj_close": 843.24, "adj_factor": 0.996743
    }
  ],
  "pagination": { "count": 3, "next_cursor": null }
}

GET /v1/bars/daily/grouped 需要 API Key

取得某一個交易日「全市場」的日線快照，一次查完當天所有標的。

參數	型別	說明
date	date	YYYY-MM-DD，必填
board	string	`TWSE` / `TPEx` 選填
adjusted / limit / cursor	—	同「日線歷史」，`limit` 上限 5000、預設 500

展開範例

shell

curl -H "Authorization: Bearer sk_live_..." \
  https://mcp.example.com/v1/bars/daily/grouped?date=2024-06-18

GET /v1/bars/daily/bulk-export 需要 API Key

大量匯出日線資料為 CSV 檔（Content-Type: text/csv），適合離線分析或匯入試算表，不建議透過 MCP 呼叫（輸出量大）。

參數	型別	說明
from / to	date	YYYY-MM-DD，預設近 90 天選填
symbol	string	不填則匯出全市場選填
format	string	目前僅支援 `csv`（`parquet` 規劃中）

展開範例

shell

curl -H "Authorization: Bearer sk_live_..." \
  https://mcp.example.com/v1/bars/daily/bulk-export?symbol=2330.TW&from=2024-01-01&to=2024-07-18 \
  -o bars.csv

GET /v1/tickers/{symbol}/corporate-actions 需要 API Key

公司行動事件（現金股利、股票股利、增資、減資、股票分割）。全市場版本 GET /v1/corporate-actions（可用 board 篩選）用法相同。

參數	型別	說明
from / to	date	依 `ex_date` 篩選，預設近 90 天選填
type	string	`CASH_DIVIDEND` / `STOCK_DIVIDEND` / `RIGHTS_OFFERING` / `CAPITAL_REDUCTION` / `STOCK_SPLIT` 選填
limit / cursor	int / string	分頁，同上選填

請求

shell

curl -H "Authorization: Bearer sk_live_..." \
  https://mcp.example.com/v1/tickers/2330.TW/corporate-actions?from=2024-01-01&to=2024-12-31

回應 200

json

{
  "data": [{
    "action_id": "ca_2330_20240618_cashdiv",
    "symbol": "2330.TW",
    "type": "CASH_DIVIDEND",
    "ex_date": "2024-06-18",
    "record_date": "2024-06-24",
    "pay_date": "2024-07-15",
    "cash_dividend_per_share": 3.0
  }],
  "pagination": { "count": 1, "next_cursor": null }
}

Reference

錯誤與限流

錯誤採 Stripe 風格的結構化物件；限流資訊透過每個 /v1/* 回應的 header 回傳。

未帶 API Key 401

json

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Missing Authorization header...",
    "request_id": "req_da76c7f8..."
  }
}

限流回應 headers

headers

x-ratelimit-limit: 50000
x-ratelimit-remaining: 49995
x-ratelimit-reset: 1786924800

HTTP 狀態	`error.type`	常見原因
400	`invalid_request_error`	參數格式錯誤，例如 `board` 不是 `TWSE`/`TPEx`、日期區間顛倒
401	`authentication_error`	缺少、格式錯誤或已失效的 API Key
404	`invalid_request_error`	查無此標的（`code: not_found`）
429	`rate_limit_error`	超過每日 50,000 次上限，需等到 `x-ratelimit-reset` 之後
500	`api_error`	伺服器內部錯誤，帶 `request_id` 方便回報

MCP Integration

接上 LLM：MCP 封裝

MCP（Model Context Protocol）是讓 LLM 用戶端（Claude、Claude Code 等）呼叫外部工具的開放標準。這個 API 有兩種接法：遠端連線（直接在自己的 LLM 用戶端填一個網址 + 金鑰，不用裝任何東西）或 本機 stdio（在自己電腦上跑一支 Python 程式，給不支援遠端 MCP 的用戶端用）。兩條路徑背後打到的是同一份資料。

Recommended

遠端連線（免安裝）

支援「自訂連接器／Remote MCP」的用戶端（例如 Claude.ai 的 Connectors 設定）可以直接填網址，不需要在自己電腦上安裝 Python 或執行任何程式。

設定項目	值
MCP 伺服器網址	`https://mcp.example.com/mcp`
Transport	`streamable-http`
驗證	`Authorization: Bearer <你的 MCP 存取金鑰>`（訂閱時另外核發，跟上面 REST API 的 `sk_live_...` 是不同的一把）

這把 MCP 存取金鑰只保護「誰能連上這個 MCP 端點」，不是 OAuth 帳號系統——妥善保管，不要放進會被公開的程式碼或設定檔。

Alternative

本機連線（stdio）

用戶端不支援遠端 MCP 時的替代方案：在自己電腦上跑 services/mcp-server/server.py，由它代為呼叫上方的遠端 API。

下載並安裝依賴

原始碼倉庫是私有的，訂閱時我們會另外把 services/mcp-server/（server.py + requirements.txt）寄給你——如果還沒收到，直接跟我們要即可。
shell
```
cd services/mcp-server
pip install -r requirements.txt
```
設定連線資訊

指向這個部署，帶上你的 REST API 金鑰（sk_live_...，不是 MCP 存取金鑰）。
.env
```
TICKERS_API_BASE_URL=https://mcp.example.com
TICKERS_API_KEY=sk_live_<你的金鑰>
```

在 LLM 用戶端註冊這個 MCP server

Claude Desktop／Claude Code 都用同一種 mcpServers 設定格式（command 的路徑要換成本機的絕對路徑）。

claude_desktop_config.json

{
  "mcpServers": {
    "tickers-api": {
      "command": "python",
      "args": ["/path/to/services/mcp-server/server.py"],
      "env": {
        "TICKERS_API_KEY": "sk_live_<你的金鑰>"
      }
    }
  }
}

重新啟動用戶端

重啟後即可在對話裡直接問「幫我查 2330.TW 最近的股利紀錄」——模型會自動挑選並呼叫下方對應的工具。

Tools

可用工具

每個工具對應一個 REST 端點，兩種連線方式共用同一份工具清單；get_corporate_actions 合併了「單一標的」與「全市場」兩個端點，靠是否給 symbol 判斷。

check_health()

→ GET /healthz

檢查 tickers-api 是否存活，不需要 API Key。

list_tickers(q, board, limit, cursor)

→ GET /v1/tickers

依關鍵字或板別列出標的清單。

get_ticker(symbol)

→ GET /v1/tickers/{symbol}

取得單一標的 metadata。

get_daily_bars(symbol, from_date, to_date, adjusted, limit, cursor)

→ GET /v1/tickers/{symbol}/bars/daily

單一標的日線歷史，可選是否還原權值。

get_grouped_daily_bars(date, board, adjusted, limit, cursor)

→ GET /v1/bars/daily/grouped

某一交易日全市場快照。

get_corporate_actions(symbol, from_date, to_date, action_type, board, limit, cursor)

→ GET /v1/tickers/{symbol}/corporate-actions 或 /v1/corporate-actions

公司行動事件；不給 symbol 即查全市場。

bulk-export（CSV 批次匯出）刻意沒有對應 MCP 工具——單次輸出量大，不適合塞進模型的上下文，需要大量資料仍建議直接呼叫 REST 端點。

Try it

測試範例

三條驗證路徑：直接打 REST API、透過官方 MCP SDK 呼叫遠端 streamable-http 端點，或本機 stdio 模式。背後打到的都是同一個服務。

REST：完整驗證流程

shell

# 1. 服務存活
curl https://mcp.example.com/healthz

# 2. 沒帶 Key 應該回 401
curl -i https://mcp.example.com/v1/tickers

# 3. 帶 Key 查標的
$headers = @{ Authorization = "Bearer sk_live_<你的金鑰>" }
curl -Headers $headers https://mcp.example.com/v1/tickers/2330.TW

# 4. 還原權值驗證：adjusted=false 時 adj_* 欄位應消失，
#    adjusted=true（預設）在除息日前 adj_close 應小於 close
curl -Headers $headers "https://mcp.example.com/v1/tickers/2330.TW/bars/daily?from=2024-06-01&to=2024-06-30&adjusted=false"

# 5. 限流 headers 應出現在每個 /v1/* 回應中
curl -Headers $headers -i https://mcp.example.com/v1/tickers/2330.TW | Select-String "x-ratelimit"

MCP：官方 Python SDK 呼叫遠端端點

test_mcp_remote.py

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    url = "https://mcp.example.com/mcp"
    headers = {"Authorization": "Bearer <你的 MCP 存取金鑰>"}
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "get_daily_bars",
                {"symbol": "2330.TW", "from_date": "2024-06-01", "to_date": "2024-06-05"},
            )
            print(result.content[0].text)

asyncio.run(main())

MCP：本機 stdio 快速手動測試

shell

pip install "mcp[cli]"
mcp dev services/mcp-server/server.py
# 開啟瀏覽器版 Inspector，可直接點選、填參數、呼叫每個 tool

快速開始

確認服務存活

準備 API Key

打第一支請求

身分驗證

端點參考

錯誤與限流

接上 LLM：MCP 封裝

遠端連線（免安裝）

本機連線（stdio）

下載並安裝依賴

設定連線資訊

在 LLM 用戶端註冊這個 MCP server

重新啟動用戶端

可用工具

測試範例