Neoapi Python

NeoAPI Python

Overview

本 skill 教導 AI 編程代理使用 Fubon Neo Python SDK 進行台股證券交易與行情資料存取。適用 Python 3.8–3.13、SDK >= 2.x（避免 3.14）。預設 SDK ~2.2.8，除非使用者另外指定。

TL;DR — 三大工作流程：

1. 登入 → sdk.login(ID, PWD, cert, cert_pwd) 取得帳號清單
2. 下單 → 建構 Order(...) → sdk.stock.place_order(acc, order)
3. 行情 → sdk.init_realtime() → sdk.marketdata.rest_client.stock.intraday.*

Shioaji migration routing

When the user asks to migrate or port existing Shioaji code, keep the tone practical and neutral: help them translate working code safely; do not frame the answer as a broker comparison. Load references/migration-shioaji.md first, then add the narrow reference below when needed.

常見錯誤（Common Mistakes）

Public Docs Access

• Base site: https://www.fbs.com.tw/TradeAPI/
• English locale: https://www.fbs.com.tw/TradeAPI/en/
• Build with LLM (zh): https://www.fbs.com.tw/TradeAPI/docs/welcome/build-with-llm
• Build with LLM (en): https://www.fbs.com.tw/TradeAPI/en/docs/welcome/build-with-llm/
• LLM indexes:
  • https://www.fbs.com.tw/TradeAPI/llms.txt
  • https://www.fbs.com.tw/TradeAPI/llms-full.txt
  • https://www.fbs.com.tw/TradeAPI/en/llms.txt
  • https://www.fbs.com.tw/TradeAPI/en/llms-full.txt
• Note: The .md URL trick is no longer supported; use .txt instead. Every page under /TradeAPI/docs/ or /TradeAPI/en/docs/ can be accessed as plain text by appending .txt (e.g., https://www.fbs.com.tw/TradeAPI/docs/trading/introduction.txt). Use llms.txt to find the page paths.

Usage Cheat Sheet

Quickstart (Trading)

from fubon_neo.sdk import FubonSDK, Order, Mode
from fubon_neo.constant import BSAction, MarketType, PriceType, TimeInForce, OrderType

# Init & Login
sdk = FubonSDK()  # Use FubonSDK(30, 2) if on SDK 2.2.1+
accounts = sdk.login("ID", "PWD", "C:/path/to/cert.pfx", "CertPWD")
acc = accounts.data[0]  # Pick stock account

# Place Order (Buy 1000 shares of 2330 at Limit 580)
# Keyword form recommended (matches official docs); positional form also works.
order = Order(
    buy_sell=BSAction.Buy,
    symbol="2330",
    quantity=1000,
    market_type=MarketType.Common,
    price_type=PriceType.Limit,
    time_in_force=TimeInForce.ROD,
    order_type=OrderType.Stock,
    price="580"
)
res = sdk.stock.place_order(acc, order)
print(f"Order: {res.data.order_no}")

Certificate Password Login

# Certificate with a user-defined password
accounts = sdk.login(user_id, login_password, cert_path, cert_password)

# Certificate using the official default-password mode (SDK >= 1.3.2)
# Omit the fourth argument entirely; do not pass "" or None.
accounts = sdk.login(user_id, login_password, cert_path)

若程式從環境變數讀取自訂憑證密碼，請在缺值時直接報錯，不要用 os.getenv("CERT_PASSWORD", "") 靜默退回空字串。測試環境的憑證密碼則依官方測試包為 12345678。

官方依據：https://www.fbs.com.tw/TradeAPI/docs/trading/quickstart.txt。

Critical Constants

Validating Prices

Real-time quotes (intraday.quote) may differ from valid order prices (especially in Test Env).

• For Orders: Always check sdk.stock.query_symbol_quote(acc, symbol).
  • Use limit_up_price / limit_down_price from this result for placing limit orders.
  • This source reflects the order system's view of validity.
• For Display: Use sdk.marketdata.rest_client.stock.intraday.quote(symbol).

Rate Limits (Summary)

• REST: 300 req/min (IP-based).
• WebSocket: 200 subscriptions per connection.

SDK 版本相容性（Version Compatibility）

測試環境一律加 url="wss://neoapitest.fbs.com.tw/TASP/XCPXWS" 參數。

工作流程決策樹（Workflow Decision Tree）

需求是什麼？
├── 交易（Trading）
│   ├── 下單 / 改單 / 刪單
│   │   ├── 測試環境？→ FubonSDK(30, 2, url=test_url) + query_symbol_quote 取價格
│   │   └── 正式環境？→ FubonSDK(30, 2) + intraday.ticker 取漲跌停
│   ├── 查詢帳務 → sdk.stock.get_order_results / get_inventories
│   └── 當沖（Day Trade）→ 見下方「當沖」章節
├── 行情（Market Data）
│   ├── 即時快照 → HTTP: intraday.quote（成交）/ intraday.ticker（參考價/漲跌停）
│   ├── 歷史資料 → HTTP: historical
│   └── 即時串流 → WebSocket: sdk.init_realtime() + subscribe
└── 環境確認
    ├── SDK 版本 → 見上方「版本相容性」
    ├── 安裝方式 → 官方 .whl（非 PyPI）
    └── 文件查詢 → references/doc-index.md

Trading Workflow

• Start from docs/trading/prepare and docs/trading/quickstart for setup.
• Use Python library references under docs/trading/library/python/ for exact function names, parameters, and return types.
• Typical flow: login (password or API key) → place/modify/cancel order → query order/account info → logout.
• Always mention rate limits when relevant (docs/trading/trade-rate-limit).

Market Data Workflow

• Decide on HTTP vs WebSocket:
  • HTTP API for snapshots, intraday, historical.
  • WebSocket API for real-time streams.
• Use docs/market-data/http-api/getting-started and docs/market-data/websocket-api/getting-started.
• Mention connection setup and rate limits when relevant.
• To use sdk.marketdata.rest_client, call sdk.init_realtime() after login.
• For limit-up/limit-down prices in market data, use intraday.ticker (not intraday.quote).
• Raw WebSocket JSON uses camelCase flags such as isLimitUpPrice and isLimitDownAsk; these booleans may be omitted when the condition is false, so read them with data.get(flag, False).
• WebSocket price / bid / ask are numeric. If a price is 0, decode it together with the matching field-specific limit flags; never compare it to the string "市價", and do not claim the public quote reveals the original order type.
• Trading hours reference (Taiwan cash equities): references/twse-trading-hours.md (Asia/Taipei)

Official field definitions: docs/market-data/websocket-api/market-data-channels/trades.txt and aggregates.txt.

def decode_ws_price_state(data: dict, field: str = "price") -> dict:
    flag_names = {
        "price": ("isLimitUpPrice", "isLimitDownPrice"),
        "bid": ("isLimitUpBid", "isLimitDownBid"),
        "ask": ("isLimitUpAsk", "isLimitDownAsk"),
    }
    if field not in flag_names:
        raise ValueError(f"Unsupported WebSocket price field: {field}")
    up_flag, down_flag = flag_names[field]
    value = data.get(field)
    if value is not None and (
        not isinstance(value, (int, float)) or isinstance(value, bool)
    ):
        raise TypeError(f"WebSocket {field} must be numeric")
    is_limit_up = bool(data.get(up_flag, False))
    is_limit_down = bool(data.get(down_flag, False))
    return {
        "value": value,
        "is_zero_encoded": value == 0,
        "is_limit_up": is_limit_up,
        "is_limit_down": is_limit_down,
        "has_limit_marker": is_limit_up or is_limit_down,
    }

可直接重用並測試的完整版本在 references/guardrail_patterns.py。

當沖（Day Trading）

台股當沖分為：

• 先買後賣（現股當沖-買）：先以 BSAction.Buy 下單，同日再以 BSAction.Sell 賣出。使用 OrderType.Stock。
• 先賣後買（現股當沖-賣/融券當沖）：先以融券賣出，同日再買回。使用 OrderType.ShortSelling。

關鍵判斷

• 使用 intraday.ticker 回傳的 canDayTrade / canBuyDayTrade 欄位確認標的可否當沖（行情端的快速旗標）。
• 若你要更精確地判斷「先買後賣」vs「先賣後買」能不能做，建議查交易端的 status bitmask：
  • 來源常見於：
    • sdk.stock.query_symbol_quote(acc, symbol) 回傳的 data.status
    • sdk.stock.daytrade_and_stock_info(acc, symbol) 回傳的 data.status（有些 wrapper 會叫 disposition_status）
  • bitmask 定義（加總）：
    • 1：平盤下可融券賣出
    • 2：平盤下可借券賣出
    • 4：可先買後賣當沖（buy-first daytrade）
    • 8：可先賣後買當沖（sell-first daytrade / daytrade short）
  • 判斷請用 位元運算，不要用 >=：

def decode_daytrade_status(status: int) -> dict[str, bool]:
    return {
        "can_short_sell_below_flat": bool(status & 1),
        "can_borrow_sell_below_flat": bool(status & 2),
        "can_daytrade_buy_first": bool(status & 4),
        "can_daytrade_sell_first": bool(status & 8),
    }

# examples
# status=15 -> all True (1+2+4+8)
# status=3  -> only the first two True (1+2)
# status=8  -> sell-first daytrade only

• 部位平倉（沖銷）：在收盤前以反向委託等量股數沖銷。

條件單當沖

SDK >= 2.2.4 支援條件單當沖（搜尋 llms-full.txt 中 ConditionDayTrade 或「當沖條件單」），可設定停損停利自動回補。

參考實作

• StrategyExecutor_feather：現股當沖先賣的自動化策略範例。

期貨 / 選擇權（Futures & Options）

本 skill 目前以**證券（Stock）**交易與行情為主要範圍。SDK 支援期貨/選擇權帳號（account_type == "futopt"），但本 skill 尚未涵蓋對應的下單/行情 API。期貨條件單說明可搜尋 llms-full.txt 中「期貨條件單」。歡迎社群補充期貨/選擇權工作流程。

Examples

• Use references/examples-guidance.md to map SDK calls to docs and avoid common modification pitfalls.

Testing / Sandbox

• Official test bundle: https://www.fbs.com.tw/TradeAPI_SDK/sample_code/test_environment.zip

• Use SDK v1.3.1+ and the test URL wss://neoapitest.fbs.com.tw/TASP/XCPXWS.

• SDK v2.2.0 and earlier: FubonSDK(url=...)

• SDK v2.2.1 and later: FubonSDK(30, 2, url=...) (30/2 are reference values).

• Test credentials: ID from certificate; login password and cert password are 12345678.

• See references/test-environment.md for operational notes (trading hours, shared account caveats).

• Python SDK is downloaded from the official site (not PyPI); install the wheel locally.

• Skill validation checklist: references/skill-tests.md.

• Local integrated runner (maintainer-only; may be absent in some distributed skill copies): .test/test_runner.py

  • If present, it can run:
    • --suite smoke: basic login + market/trade sanity checks
    • --suite complex: multi-symbol marketdata + dual-order lifecycle + callback coverage
    • --suite all: full coverage (includes complex checks)
  • If it is missing, use the minimal smoke snippet below (login → logout; no orders).

Minimal smoke (test env, no orders):

from fubon_neo.sdk import FubonSDK
import os

URL = os.getenv("NEOAPI_TEST_URL", "wss://neoapitest.fbs.com.tw/TASP/XCPXWS")
# SDK v2.2.1+: use FubonSDK(30, 2, url=...)
sdk = FubonSDK(30, 2, url=URL)

accounts = sdk.login(
    os.getenv("NEOAPI_TEST_ID"),
    os.getenv("NEOAPI_TEST_PASSWORD"),
    os.getenv("NEOAPI_TEST_CERT_PATH"),
    os.getenv("NEOAPI_TEST_CERT_PASSWORD"),
)
print("login_ok=", bool(getattr(accounts, "is_success", True)))

sdk.logout()

• For limit-down/limit-up in test env, prefer sdk.stock.query_symbol_quote (test environment data). intraday.quote uses market data (prod) and may differ.

SDK Install (Quick Note)

• Python SDK is not on PyPI. Download the wheel from the official page and install locally.
• SDK >= v2 works on Python 3.8–3.13 (avoid 3.14 for now).

即時成交回報 + Safe-net Readback

For live or latency-sensitive trading systems, treat filled callbacks as the primary fill source and get_order_results as a periodic reconciliation safe-net.

• Register callbacks before login/re-login when possible:
  • sdk.set_on_order(on_order) for order acknowledgements (OrderResult)
  • sdk.set_on_order_changed(on_order_changed) for modify/cancel reports (OrderResult)
  • sdk.set_on_filled(on_filled) for execution fills (FilledData)
  • sdk.set_on_event(on_event) for connection/re-login events
• Compute entry/exit average from execution data, not from submitted order price:
  • preferred: FilledData.filled_avg_price
  • otherwise aggregate filled_price * filled_qty across fills
  • reconciliation fallback: OrderResult.filled_money / filled_qty from sdk.stock.get_order_results(acc)
• Never use submitted limit price (price, after_price, limit-up/down) as P/L entry price fallback. If fill price is missing, mark the position as unresolved and reconcile.
• Run get_order_results periodically (for example every ~30 seconds) to detect missed callbacks and reconcile filled_qty, filled_money, and status.
• Reconcile records by order_no + seq_no when available; include filled_no for idempotent fill dedupe.
• Record a fill_source in receipts/state, such as active_filled_callback or order_results_readback, so operators can tell whether the low-latency path or the safe-net supplied the fill.

Implementation Patterns

For production-tested patterns, see references/implementation-practices.md. Key topics:

• SDK Manager: Connection lifecycle, auto-reconnect, graceful termination
• WebSocket: Multi-connection load balancing (200 symbols/connection limit)
• Async Patterns: ThreadPoolExecutor for blocking calls, per-symbol locking
• Error Handling: FugleAPIError compatibility for old/new SDK versions
• Order Placement: Order creation, placement, and fill handling
• Strategy Patterns: Tick-to-decision pipeline, stop loss, position sizing
• Error & Status Codes: Order status codes, HTTP errors, common rejection reasons

References

• Doc index: references/doc-index.md
• Implementation practices: references/implementation-practices.md
• Response shapes: references/response-shapes.md
• Source docs (maintainers): docs/ and i18n/en/docusaurus-plugin-content-docs/current

When code or docs need updating, mirror changes in the English localization if the content is user-facing.