shioaji Documentation

The shioaji binary is a dual-purpose tool that functions as both a command-line client and a daemon server.

• Command-line client: Used for querying market data, placing orders, and managing portfolios.
• Daemon server: Started via shioaji server start, it hosts the HTTP API.

All data-path commands (such as auth, data, order, etc.) communicate with the daemon via HTTP. On Unix systems, the CLI prefers using Unix Domain Sockets (UDS) for communication. If no daemon is currently running, the CLI will attempt to auto-start one using the ensure_daemon mechanism.

shioaji [OPTIONS] <COMMAND>

Reserve orders allow users to reserve shares or earmark funds for stocks under disposition, attention, or warning status. All reserve operations belong to the order domain.

Service Hours: 8:00 - 14:30 on trading days.

Key Operations:

• Stock Reserve Summary: Query available stocks for reserve and current reserved amounts.
• Stock Reserve Detail: Query details of already-reserved stocks.
• Reserve Stock: Reserve a specific number of shares for a disposition stock.
• Earmarking Detail: Query details of earmarked funds.
• Reserve Earmarking: Reserve specific funds for a stock.

The Shioaji HTTP API allows any language or platform to trade Taiwan markets via REST endpoints and real-time SSE streaming. It is started using the shioaji server start command.

Key features include:

• RESTful JSON endpoints: For all trading operations.
• Server-Sent Events (SSE): For real-time market data and order events.
• OpenAPI 3.0: Includes a Scalar documentation UI and an openapi.json schema.
• Built-in Dashboard: For monitoring.
• Custom App Hosting: Ability to upload and host your own web applications.
• Standard features: CORS support, gzip compression, request logging, and panic recovery.

Default Base URL: http://127.0.0.1:8080
API Prefix: /api/v1/

Shioaji provides real-time market data through two primary mechanisms:

1. Python callbacks: Direct function callbacks used with Shioaji (synchronous) and ShioajiAsync (asynchronous) instances.
2. SSE (Server-Sent Events): HTTP streaming via a built-in server, which allows access from any programming language.

Available Quote Types:

• Tick: Trade-by-trade data.
• BidAsk: Order book data (5 levels).
• Quote: Aggregated quote data.
• KBar: Real-time 1-minute bars (available for stocks only).

Shioaji is a cross-language, cross-platform trading API for Taiwan financial markets (TWSE/TPEX/TAIFEX). It provides three distinct access layers depending on your programming language and performance requirements:

1. Python: Native PyO3 bindings (import shioaji) providing both synchronous and asynchronous support for maximum performance.
2. CLI: A command-line tool (shioaji) used for server management, executing trades, and querying market data.
3. HTTP API + SSE: A RESTful API and Server-Sent Events (SSE) streaming service running at localhost:8080. This layer allows any language (JS/TS, Go, C/C++, C#, Rust, Java/Kotlin) to interact with the markets via standard HTTP requests and real-time streams.

When organizing a Go project that consumes the Shioaji HTTP API, the following structure is recommended to separate transport logic from trading strategies:

my-trading-app/
├── cmd/app/main.go               # Entry point
├── pkg/shioaji/
│   ├── client.go                  # API client implementation
│   ├── types.go                   # Type definitions (structs)
│   └── stream.go                  # SSE streaming logic
├── strategies/
│   └── example.go                 # User trading logic/strategies
└── go.mod

Pre-market reservation orders do not trigger order or deal callbacks immediately. They are released at 08:30 on each trading day, at which point callbacks are triggered.

If you do not receive a callback before 08:30, do not assume failure. Instead, verify the order/trade state using list_trades() or the /api/v1/order/trades endpoint. For HTTP clients in production, ensure POST /api/v1/auth/subscribe_trade has been called for the specific account.

When implementing Shioaji, follow these rules to ensure technical accuracy:

• Use Functional References: For specific endpoint payloads, request fields, or response schemas, always consult the matching functional reference.
• Avoid Cross-Layer Inference: Do not assume that Python attribute names match HTTP/SSE field names. Other languages (JS, Go, Rust, etc.) must use the specific HTTP/SSE response shapes defined in the API documentation, not the Python object structures.
• Handle Errors Correctly: If an HTTP response contains success=false, an error code, or an operation status/message, you must branch your logic based on that field. Note that empty lists or PendingSubmit statuses are not necessarily final failure or success signals; check the functional reference for the specific state machine logic.