Shioaji is SinoPac's cross-language, cross-platform trading API for Taiwan financial markets (TWSE/TPEX/TAIFEX). It includes Python bindings, a CLI, and an HTTP API server that lets any programming language trade Taiwan markets.
Shioaji is SinoPac Securities'cross-language, cross-platformtrading API, providing Python bindings, a CLI, and an HTTP API server, lettingany programming languagetrade Taiwan markets via the HTTP API.
Three access layers / Three access layers:
- Python — native PyO3 binding (
import shioaji) for best performance, sync and async - CLI —
shioajicommand-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
Reasoning about connections, timeouts, processes, or state? Read CONCEPTS.md first. It is the shared mental model these three layers assume — which timeout applies on which path, why Python needs no server but CLI/HTTP share one daemon, the per-person connection cap, streaming vs request-reply. Answer those questions from CONCEPTS.md instead of guessing. When reasoning about connections, timeouts, processes, or state, first read CONCEPTS.md。 This is the mental model shared by the three access layers — which timeout takes effect on which path, why Python doesn't need a server while CLI/HTTP share one daemon, the per-person connection limit, streaming vs request-reply. Find answers to this kind of question in CONCEPTS.md, don't guess.
How to Use References / How to Use References
Answer users directly from the bundled references. Do not route users to external documentation pages as a substitute for answering. This skill uses Shioaji 1.5 as the baseline; use MIGRATION.md only for legacy/deprecated idioms. Response handling always belongs in the matching functional reference. When an exact command flag, request field, or response schema must be confirmed, use installed CLI --help or the running server's /openapi.json.
First-time-user response / First-time-user response:
- Use this path only when the user says or clearly implies they have not used Shioaji before, are using it for the first time, do not know how to start, or may not have completed SinoPac API onboarding. Do not treat every broad "I want to use Shioaji" request as first-time by default.
- For confirmed/likely first-time users, load PREPARE.md. Treat the first response as an eligibility/onboarding conversation, because they may not even have a SinoPac account or API access yet.
- In a confirmed or likely first-time context, if the user says walk me through, step by step, 一步一步帶我 (guide me step by step), 慢慢來 (go slowly), or similar, continue onboarding from the first unconfirmed external gate. This does not authorize workspace inspection or creation of a local starter project.
- Before the user answers the first onboarding question, do not run commands, inspect files, mention Python versions, mention existing projects, or discuss local environments. The first step is not "check the folder"; it is "check whether the user can open/use SinoPac API at all."
- The first substantive response must check the basic gates before any technical setup: SinoPac securities/futures account, desired market access (stock / futures-options / both), API key/secret, direct API agreement signing, simulation login/order test, CA for production, and production-readiness check.
- Onboarding order matters: after account opening, confirm/create API Key and Secret Key at
https://www.sinotrade.com.tw/newweb/PythonAPIKey/; signing pages do not issue API keys. After signing, do not jump straight to CA; confirm API credentials and run the required simulation login/order tests first. CA download is from the API management page, not the signing pages. - When presenting onboarding steps as a table/list, write the explicit correct URL for each web step. Never use the generic SinoPac home page as the account-opening URL. Open account uses
https://www.sinotrade.com.tw/openact?strProd=0254&strWeb=0684&s=013211&utm_source=shioaji; API Key and CA usehttps://www.sinotrade.com.tw/newweb/PythonAPIKey/; stock signing useshttps://www.sinotrade.com.tw/newweb/signCenter/S_openAPI/; futures/options signing useshttps://www.sinotrade.com.tw/newweb/signCenter/F_openApi/. Never write same page or 同上頁面 (the same page as above) for API Key or CA when the previous row is a signing page. - Never describe the stock/futures signing pages as places to apply for API Key / Secret Key. Those pages are only for agreement signing; key creation happens only on the API management page.
- Never ask the user to paste API Key, Secret Key, CA password, or certificate contents into chat, even "temporarily" or "for this conversation". Ask them to save/edit secrets locally instead.
- Do not move into installation, project setup,
.env,.venv,uv sync, code examples, local file inspection, or order examples until the user confirms the relevant onboarding gates are done or explicitly asks for that technical step. - For a confirmed/likely first-time user, use this first-response shape and stop there until they answer: "Sure, let's take it step by step. Shioaji isn't usable just by installing the package; first you need to confirm the status of your SinoPac account and API activation. First step: do you currently have a SinoPac securities or futures account? What you want to activate is securities, futures/options, or both?"
- For signing, give the direct product page, not the generic signing center: stock https://www.sinotrade.com.tw/newweb/signCenter/S_openAPI/; futures/options https://www.sinotrade.com.tw/newweb/signCenter/F_openApi/.
Only when it is known or clearly inferred that the user has never used Shioaji, is using it for the first time, doesn't know how to start, or has not yet completed SinoPac API activation, should the first-time-user flow be followed. Do not default all broad "I want to use shioaji" cases to zero experience. After confirming/inferring a first-time user, "please walk me through step by step", "take it slow", "start from zero" mean confirming step by step along the activation flow, not permission to inspect the workspace or create a local starter project. Before the user answers the first activation question, do not execute commands, list files, mention the Python version, mention existing projects, or mention the local environment. The first step is eligibility/activation confirmation, not technical setup: first confirm whether they already have a SinoPac securities/futures account, whether they want securities or futures/options, the API Key/Secret, signing the API agreement, simulated login/order testing, the production environment CA, and the production readiness check. After opening an account, first confirm/create the API Key and Secret Key; the signing page does not issue an API Key, and must not be called the key application page. After signing is complete, do not jump directly to CA; first confirm the API certificate and run the simulated login/order test. CA download is on the API management page, not the signing page. When organizing the step table, every row must state the correct URL; account opening must not use the SinoPac homepage, it must use the designated account-opening page; API Key and CA must not be written as "same page" pointing to the signing page. Absolutely never ask the user to paste the API Key, Secret Key, CA password, or certificate contents into the conversation, even if they say it is only temporary. Unless the user confirms the relevant prerequisites are complete or explicitly requests that technical step, do not proceed to installation,.env、.venv、uv sync, code examples, project file inspection, or order examples.
Cross-access-layer response guardrails / Cross-access-layer response guardrails:
- Do not infer HTTP/SSE/CLI fields from Python wrapper attributes.
- Other languages (JS/Go/Rust/C#/C++/Java) use HTTP/SSE response shapes, not Python objects.
- If a response contains
success=false, an error code, or an operation status/message, branch on that field before continuing. - Empty lists and
PendingSubmitare not final failure/success signals; check the matching functional reference before deciding the next step.
Token-efficient lookup / Token-efficient lookup:
- Choose the functional reference first; search inside it for endpoint, method, error text, response type, or headings like
Response and Decision Summary,Prerequisites. - Read the smallest matching section before loading long examples.
- Load CLI/HTTP/language references only when implementation details (transport setup, SSE parser, auth/error handling, OpenAPI generation) are needed; keep endpoint-specific payload and response decisions in the functional reference.
Task Routing — "I want to..." / Task Routing
For most tasks, load only 1-2 files. Use both axes: what (task) + how (access method).
Routing rule: choose the functional reference first, then add the access-method reference only when needed. Functional references own the workflow, payload rules, response shapes, and decision logic for that task. Language references explain how to send requests, receive responses, stream SSE, add auth headers, handle errors, and generate typed clients; they must not restate endpoint-specific business rules. Use HTTP_API.md for endpoint inventory and /openapi.json for exact installed-server schemas.
Axis 1: What do you want to do? / Task
| Task | Load File |
|---|---|
| Understand the architecture: process model, connections, timeout layering, streaming vs request-reply, state | CONCEPTS.md |
| Migrate legacy code or fix deprecated Shioaji idioms | MIGRATION.md |
| Install, login, API keys, CA cert, simulation, env vars, constants | PREPARE.md |
| Install this Shioaji plugin/skill into Claude, Codex, or another agent environment | AGENTS.md |
| Look up contract codes, attributes, security types | CONTRACTS.md |
Place, modify, cancel orders; combos; order_deal_event active order/deal reports (Python callbacks, HTTP order-event SSE) |
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? / Language or 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 | HTTP/SSE client patterns |
| Go | GO.md | HTTP/SSE client patterns |
| C/C++ | CPP.md | HTTP/SSE client patterns |
| C# | CSHARP.md | HTTP/SSE client patterns |
| Rust | RUST.md | HTTP/SSE client patterns |
| Java/Kotlin | JAVA.md | HTTP/SSE client patterns |
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. For example, "use JS to place an order" means load ORDERS.md for payload and Trade decision logic, plus JAVASCRIPT.md for fetch/SSE implementation patterns.
For installation, first-use setup, API keys, signing, CA, login, and readiness checks, load PREPARE.md. For installation, first-time activation, API Key, signing, CA, login and readiness checks, please read PREPARE.md。
Simulation vs Production Safety / Simulation vs Production Safety
WARNING WARNING: Always verify the server mode before placing orders. Production mode executes real trades with real money. 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) orGET /api/v1/info(HTTP — returnssimulationfield) - Switch to production Switch to production:
shioaji server start --productionorSJ_PRODUCTION=true - Switch back to simulation Switch back to simulation:
shioaji server stopthenshioaji server start(without--production)
Rate Limits / 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 / Error Handling
HTTP API returns JSON errors: {"code": 400, "message": "...", "details": "..."}
Check the task reference before retrying. For example, empty market-data responses, PendingSubmit order status, and success=false subscription responses each require different next steps.
Logout / Logout
api.logout()
For task examples, see the functional reference (Axis 1). For transport and client patterns, see the language reference (Axis 2). For task examples, see the functional reference (Axis 1). For transport and client patterns, see the language reference (Axis 2).