shioaji

Shioaji Trading API

Shioaji is SinoPac's cross-language, cross-platform trading API for Taiwan financial markets (TWSE/TPEX/TAIFEX). The Rust reimplementation (rshioaji) transforms Shioaji from a Python-only library into a universal trading platform — any programming language can now trade Taiwan markets through the HTTP API server.

Shioaji 是永豐金證券的跨語言、跨平台交易 API。Rust 重新實作（rshioaji）將 Shioaji 從 Python 專屬函式庫轉變為通用交易平台 — 任何程式語言都能透過 HTTP API 伺服器交易台灣市場。

Three access layers:

• Python — native PyO3 binding (import shioaji) for best performance, sync and async
• CLI — shioaji command-line tool for server management, trading, and data queries
• HTTP API + SSE — REST endpoints + real-time streaming at localhost:8080, accessible from JS/TS, Go, C/C++, C#, Rust, Java/Kotlin, or any HTTP client

Install: claude plugin marketplace add Sinotrade/rshioaji → claude plugin install rshioaji This can coexist with the old Sinotrade/Shioaji plugin (different name). At production release, plugin name changes to shioaji.

Official Docs: https://sinotrade.github.io/

---

Task Routing — "I want to..."

For most tasks, load only 1-2 files. Use both axes: what (task) + how (access method).

Axis 1: What do you want to do?

Task	Load File
Install, login, API keys, CA cert, simulation, env vars, constants	PREPARE.md
Look up contract codes, attributes, security types	CONTRACTS.md
Place, modify, cancel orders; combos; order events	ORDERS.md
Reserve shares for disposition/attention stocks	RESERVE.md
Subscribe real-time quotes, tick/bidask/quote callbacks, SSE streams	STREAMING.md
Historical ticks, K-bars, snapshots, scanners, credit enquiry	MARKET_DATA.md
Account balance, margin, positions, P&L, settlements, limits	ACCOUNTING.md
Manage watchlists (CRUD, add/remove contracts)	WATCHLIST.md
Non-blocking mode, quote binding, stop orders, advanced patterns	ADVANCED.md
Errors, connection issues, troubleshooting	TROUBLESHOOTING.md

Axis 2: What language/access method?

Access Method	Additional File	Notes
Python (sync or async)	None — task refs include Python examples	Default path
CLI (shioaji command)	CLI.md	Task ref (concept) + CLI.md (commands)
HTTP API (any language)	HTTP_API.md	Canonical endpoint inventory
JavaScript/TypeScript	JAVASCRIPT.md	Complete project guide
Go	GO.md	Complete project guide
C/C++	CPP.md	Complete project guide
C#	CSHARP.md	Complete project guide
Rust	RUST.md	HTTP client guide
Java/Kotlin	JAVA.md	Complete project guide

Python users: load only the task reference (Axis 1). CLI users: load the task reference + CLI.md. Other languages: load the task reference + language reference (which covers HTTP setup).

---

Quick Start

Python

import shioaji as sj
api = sj.Shioaji()
api.login(api_key="YOUR_KEY", secret_key="YOUR_SECRET")

CLI

uv tool install rshioaji
export SJ_API_KEY=YOUR_KEY SJ_SEC_KEY=YOUR_SECRET
shioaji server start           # start HTTP server (simulation)
shioaji order place --code 2330 --action Buy --price 580 --quantity 1

HTTP API (any language)

# Server must be running first (see CLI above)
curl http://localhost:8080/api/v1/auth/accounts
curl -X POST http://localhost:8080/api/v1/data/snapshots \
  -H "Content-Type: application/json" \
  -d '{"contracts":[{"security_type":"STK","exchange":"TSE","code":"2330"}]}'

See PREPARE.md for full installation and setup.

---

Simulation vs Production Safety / 模擬與正式環境安全

WARNING 警告: Always verify the server mode before placing orders. Production mode executes real trades with real money. 下單前務必確認伺服器模式。正式環境會使用真實資金進行真實交易。

• Default: simulation mode (no flag needed)
• Check mode: shioaji server check (CLI) or GET /api/v1/info (HTTP — returns simulation field)
• Switch to production 切換至正式環境: shioaji server start --production or SJ_PRODUCTION=true
• Switch back to simulation 切回模擬環境: shioaji server stop then shioaji server start (without --production)

---

Rate Limits

Category	Limit
Daily Traffic	500MB–10GB (based on trading volume)
Quote Query	50 requests / 5 sec
Accounting Query	25 requests / 5 sec
Connections	5 per person ID
Daily Logins	1000 times

---

Error Handling

try:
    trade = api.place_order(contract, order)
except Exception as e:
    print(f"Order failed: {e}")

HTTP API returns JSON errors: {"code": 400, "message": "...", "details": "..."}

---

Logout

api.logout()