永豐金 Shioaji API 程式交易入門：從申請到串接即時股價 (Python)

你是否也想踏入程式交易的領域，用程式碼來自動化你的投資策略？永豐金 Shioaji 提供了強大的 API，讓開發者可以用 Python 輕鬆串接台灣股市的即時行情與下單功能。

這篇文章將帶你從零開始，一步步完成 Shioaji API 的申請、環境設定，並撰寫第一支 Python 程式來訂閱台積電 (2330) 的即時股價。讓我們開始吧！

事前準備

在開始之前，請確保你已經具備以下條件：

擁有永豐金證券帳戶。
你的電腦已安裝 Python 3.8 或以上版本。

步驟一：申請 API 金鑰與憑證

要使用 Shioaji API，你必須先取得 API Key、Secret Key 以及交易憑證。

參考官方教學：首先，請詳細閱讀官方的憑證申請教學頁面，了解整個流程。
線上申請 API：前往永豐金 API 管理頁面按下「新增 API Key」。

完成申請後，畫面會顯示你的 API_Key 與 Secret_Key。請務必妥善保存這兩組金鑰。同時，點擊「下載憑證」，將憑證檔案 Sinopac.pfx 下載下來。

步驟二：準備你的 Python 專案

接下來，我們要設定我們的開發環境。

建立一個新的專案資料夾，例如 ShioajiTest。
將剛剛下載的憑證檔案 Sinopac.pfx 放到這個資料夾底下。
在同一個資料夾中，建立一個名為 .env 的檔案。這個檔案將用來存放你的敏感資訊，避免直接寫在程式碼裡。

打開 .env 檔案，並填入以下內容，記得將 YOUR_API_KEY 和 YOUR_SECRET_KEY 換成你自己的金鑰，並填寫你的身分證字號。
```
SHIOAJI_API_KEY=YOUR_API_KEY
SHIOAJI_SECRET_KEY=YOUR_SECRET_KEY
CA_PASSWD=你的身份證字號
PERSON_ID=你的身份證字號
```

步驟三：設定 Python 環境與安裝套件

為了保持專案環境的乾淨，我們將使用虛擬環境 (venv)。

建立 requirements.txt

在專案資料夾中建立 requirements.txt 檔案，並寫入 Shioaji 所需的套件：
```
shioaji
python-dotenv
```

建立並啟用虛擬環境

打開你的終端機 (Terminal)，切換到專案資料夾，然後執行以下指令：

# 建立虛擬環境
python3 -m venv .venv

# 啟用虛擬環境 (macOS / Linux)
source ./.venv/bin/activate

# 如果你使用 Windows，請用這個指令
# .\.venv\Scripts\activate

啟用後，你會看到終端機提示符號前面多了 (.venv)。

安裝套件

執行以下指令，安裝我們在 requirements.txt 中定義的套件。
```
pip install -r requirements.txt
```

步驟四：撰寫並執行測試程式

萬事俱備，只欠東風！現在我們可以來寫第一支測試程式了。

在專案資料夾中建立一個 test.py 檔案，並貼上以下程式碼。

import shioaji as sj
from shioaji import TickSTKv1, Exchange
import time
import os
import threading
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Initialize Shioaji API
api = sj.Shioaji()

# Login with credentials from environment variables
api_key = os.getenv('SHIOAJI_API_KEY')
secret_key = os.getenv('SHIOAJI_SECRET_KEY')
accounts = api.login(api_key, secret_key)

# Activate CA certificate with credentials from environment variables
ca_passwd = os.getenv('CA_PASSWD')
person_id = os.getenv('PERSON_ID')
api.activate_ca(
    ca_path="./Sinopac.pfx",
    ca_passwd=ca_passwd,
    person_id=person_id,
)

print("Login and activate CA success")

# Define callback function for real-time quotes
@api.on_tick_stk_v1()
def quote_callback(exchange: Exchange, tick: TickSTKv1):
    print(f"Exchange: {exchange}")
    print(f"Code: {tick.code}")
    print(f"Price: {tick.close}")
    print(f"Volume: {tick.volume}")
    print(f"Time: {tick.datetime}")
    print("-" * 50)

# Subscribe to 2330 (TSMC) real-time quotes
api.quote.subscribe(
    api.Contracts.Stocks["2330"], 
    quote_type=sj.constant.QuoteType.Tick,
    version=sj.constant.QuoteVersion.v1
)

print("Starting to receive 2330 real-time quotes...")
print("Press Ctrl+C to stop")

# Keep the program running to receive real-time data
# Using threading.Event for efficient CPU usage
stop_event = threading.Event()

try:
    # This blocks until interrupted, using almost no CPU
    stop_event.wait()
except KeyboardInterrupt:
    print("\nStopping quote reception")
    api.logout()
    print("Logged out successfully")

這段程式碼做了幾件事：

load_dotenv()：從 .env 檔案讀取你的金鑰和密碼。
api.login()：使用 API Key 和 Secret Key 登入 Shioaji。
api.activate_ca()：使用憑證檔案和密碼（身分證字號）啟用 CA 憑證，這是下單交易的必要步驟。
quote_callback()：這是一個回呼函式 (Callback)，當 Shioaji API 收到新的報價時，就會自動執行這個函式內的程式碼。
api.quote.subscribe()：告訴 Shioaji API 我們要訂閱台積電 (2330) 的即時逐筆報價 (Tick)。
while True：讓程式保持執行狀態，才能持續接收報價。

步驟五：查看執行結果

在終端機中，確保你的虛擬環境是啟用的狀態，然後執行程式：

python3 test.py

如果一切順利，你會先看到登入成功的訊息，接著在台股開盤時間，你會開始看到台積電 (2330) 的即時股價資訊不斷地被印出來！

(.venv) user@machine:~/test/ShioajiTest$ python3 test.py

Login and activate CA success
Starting to receive 2330 real-time quotes...
Press Ctrl+C to stop
Response Code: 200 | Event Code: 16 | Info: APISUB/V1/SYS/CONTRACT | Event: Subscribe or Unsubscribe ok
Response Code: 200 | Event Code: 16 | Info: TIC/v1/STK/*/TSE/2330 | Event: Subscribe or Unsubscribe ok
Exchange: Exchange.TSE
Code: 2330
Price: 1125
Volume: 1
Time: 2025-07-16 11:07:56.091517
--------------------------------------------------
Exchange: Exchange.TSE
Code: 2330
Price: 1125
Volume: 1
Time: 2025-07-16 11:08:01.009811
--------------------------------------------------

當你想要停止程式時，只要在終端機按下 Ctrl + C 即可。

總結

恭喜你！你已經成功完成了 Shioaji API 的設定，並撰寫了第一支可以接收台股即時報價的 Python 程式。這只是程式交易的第一步，接下來你可以基於這個基礎，去開發更複雜的功能，例如：

將股價資料儲存到資料庫。
計算各種技術指標 (KD, MACD, RSI)。
根據你設定的策略條件，自動觸發下單。

希望這篇教學對你有幫助，祝你在量化交易的路上一切順利！