快速入門

登入¶

只需像使用其他流行的套件一樣，匯入後新建實例即可開始使用 Shioaji。

PythonCLI / HTTP

import shioaji as sj

# 建立 Shioaji 實例。
api = sj.Shioaji()

# 登入
accounts = api.login(
    api_key="YOUR_API_KEY", 
    secret_key="YOUR_SECRET_KEY", 
    subscribe_trade=True
)

# 啟用憑證（正式環境下單前必須）
api.activate_ca(
    ca_path="your/ca/path/Sinopac.pfx",
    ca_passwd="YOUR_CA_PASSWORD",
    person_id="Person of this Ca",
)

# .env（放在執行目錄）應包含：
#   SJ_API_KEY=YOUR_API_KEY
#   SJ_SEC_KEY=YOUR_SECRET_KEY
#   SJ_CA_PATH=your/ca/path/Sinopac.pfx
#   SJ_CA_PASSWD=YOUR_CA_PASSWORD

# 啟動 server（自動讀取 .env，完成登入與憑證載入）
shioaji server start

注意

在開始前請還需完成前置作業，包含開戶、服務條款及 Token。

Windows環境下複製文件路徑時用\分隔文件，需要用/替換。

確認狀態¶

CLIHTTP

# 確認狀態
shioaji server check

# 確認帳戶（驗證已登入）
curl http://localhost:8080/api/v1/auth/accounts

訂閱委託/成交回報¶

PythonCLIHTTP

我們提供 2 個方式讓您可以調整訂閱委託/成交回報。首先是於 login 的參數 subscribe_trade，預設值為 True，會自動為您訂閱所有帳號的委託/成交回報。另一個方式是，對特定帳號使用 API subscribe_trade 及 unsubscribe_trade，即可訂閱或取消訂閱委託/成交回報。

subscribe trade

api.subscribe_trade(account)

unsubscribe trade

api.unsubscribe_trade(account)

server 啟動時不自動訂閱，需逐帳號動態訂閱。

subscribe trade

shioaji auth subscribe-trade --account-type F

unsubscribe trade

shioaji auth unsubscribe-trade --account-type F

Parameters

--account-type: 選填，S（證券，預設）或 F（期貨/選擇權）
--account:      選填，BROKER_ID-ACCOUNT_ID 格式；未填時使用該類型的預設帳號

Out

account:
  account_type: F
  person_id: YOUR_PERSON_ID
  broker_id: F002000
  account_id: "YOUR_ACCOUNT_ID"
  signed: true
  username: ""
subscribe_trade: true
ts: 20260612021106

注意

subscribe-trade 只負責向 server 登記訂閱，執行完即結束。實際接收委託/成交回報請使用 shioaji order events（SSE 串流，Ctrl+C 停止），詳見委託回報。

server 啟動時不自動訂閱，需逐帳號動態訂閱。

subscribe trade

curl -X POST http://localhost:8080/api/v1/auth/subscribe_trade \
  -H "Content-Type: application/json" \
  -d '{"broker_id": "YOUR_BROKER_ID", "account_id": "YOUR_ACCOUNT_ID"}'

unsubscribe trade

curl -X POST http://localhost:8080/api/v1/auth/unsubscribe_trade \
  -H "Content-Type: application/json" \
  -d '{"broker_id": "YOUR_BROKER_ID", "account_id": "YOUR_ACCOUNT_ID"}'

訂閱行情¶

訂閱行情需將合約帶入 subscribe 功能，並指定行情類型，就可以接收資料。目前支援 tick / bid_ask / quote 三種行情類型。

PythonCLIHTTP

contract = api.contracts.get("2330")
api.subscribe(contract, quote_type="tick")
api.subscribe(contract, quote_type="bid_ask")

shioaji data stream --code 2330 --quote-type tick
shioaji data stream --code 2330 --quote-type bid_ask

# 訂閱
curl -X POST http://localhost:8080/api/v1/stream/subscribe \
  -H "Content-Type: application/json" \
  -d '{"security_type":"STK","exchange":"TSE","code":"2330","quote_type":"Tick"}'

curl -X POST http://localhost:8080/api/v1/stream/subscribe \
  -H "Content-Type: application/json" \
  -d '{"security_type":"STK","exchange":"TSE","code":"2330","quote_type":"BidAsk"}'

# 連接 SSE 接收串流（Ctrl+C 停止）
curl -N http://localhost:8080/api/v1/stream/data

跨語言用戶注意

Python / CLI 使用 contract 物件或代號即可訂閱。其他語言需自行填寫 security_type / exchange / code 等欄位，可呼叫 GET /api/v1/data/contracts/{code}?security_type=... 查詢。

下單¶

下單需指定合約與委託內容（買賣方向、價格、數量等），送出後會回傳該筆交易的狀態。

PythonCLIHTTP

contract = api.contracts.get("2890")
order = sj.StockOrder(
    action=sj.Action.Buy,
    price=28,
    quantity=1,
    price_type=sj.StockPriceType.LMT,
    order_type=sj.OrderType.ROD,
    order_lot=sj.StockOrderLot.Common,
    order_cond=sj.StockOrderCond.Cash,
)
trade = api.place_order(contract, order)

shioaji order place --code 2890 --action buy --price 28 --quantity 1 \
    --price-type lmt --order-type rod --order-lot common --order-cond cash

curl -X POST http://localhost:8080/api/v1/order/place_order \
  -H "Content-Type: application/json" \
  -d '{
    "contract": {"security_type": "STK", "exchange": "TSE", "code": "2890"},
    "stock_order": {
      "price": 28,
      "quantity": 1,
      "action": "Buy",
      "price_type": "LMT",
      "order_type": "ROD",
      "order_lot": "Common",
      "order_cond": "Cash"
    }
  }'

總結¶

這份快速入門展示了 Shioaji 的核心操作。無論是 Python、CLI 或 HTTP API（含 JS、Go、C++、C# 等），皆能以相同邏輯完成登入、訂閱與下單。