# uv (recommended)
uv add shioaji

# pip
pip install shioaji

To pin a version, lock the release line, for example uv add "shioaji==1.7.*". PyPI keeps only the latest two patch releases of each line. Releases with the same first two version parts never make incompatible changes, so a line pin is always safe to upgrade within.

uv tool install shioaji
# or only the CLI, on any Python version:
uv tool install shioaji-cli
shioaji --help

The CLI ships in the regular wheels; free-threaded Python 3.14t wheels do not include it, so install the CLI with a regular Python (the uv tool install default).

Linux / macOS:

# Stable
curl -fsSL https://github.com/Sinotrade/Shioaji/releases/latest/download/install.sh | sh

# Pre-release
curl -fsSL https://github.com/Sinotrade/Shioaji/releases/latest/download/install.sh | CHANNEL=prerelease sh

# Specific version
curl -fsSL https://github.com/Sinotrade/Shioaji/releases/latest/download/install.sh | VERSION=v1.5.6 sh

Windows (PowerShell):

# Stable
irm https://github.com/Sinotrade/Shioaji/releases/latest/download/install.ps1 | iex

# Pre-release
$env:CHANNEL="prerelease"; irm https://github.com/Sinotrade/Shioaji/releases/latest/download/install.ps1 | iex

Initialization (login + activate certificate)

import shioaji as sj

api = sj.Shioaji()
accounts = api.login(api_key="YOUR_KEY", secret_key="YOUR_SECRET")
api.activate_ca(
    ca_path="/c/your/ca/path/Sinopac.pfx",
    ca_passwd="YOUR_CA_PASSWORD",
)

Just import the API library like other popular Python packages and create the instance to start using it. After logging in, the API is ready for market data queries; once the certificate is activated, order placement is enabled.

Subscribe to Streaming Market Data

api.subscribe(api.Contracts.Stocks["2330"], quote_type="tick")
api.subscribe(api.Contracts.Stocks["2330"], quote_type="bid_ask")
api.subscribe(api.Contracts.Futures["TXFC0"], quote_type="tick")

Subscribe to real-time market data. Pass a contract into the subscribe function and specify a quote_type to begin receiving streaming data.

Place Order

contract = api.Contracts.Stocks["2890"]
order = sj.StockOrder(
    price=9.6,
    quantity=1,
    action=sj.Action.Buy,
    price_type=sj.StockPriceType.LMT,
    time_in_force=sj.TimeInForce.ROD,
    order_lot=sj.StockOrderLot.Common,
    account=api.stock_account,
)
trade = api.place_order(contract, order)

As with subscribing to market data using a contract, an order must first be defined and then passed alongside the contract into the place_order function. The function returns a trade object representing the order's status.

Start the Server

shioaji server start

Once the server is running, all trading capabilities are exposed as RESTful endpoints accessible from any HTTP-capable language (JavaScript, Go, C#, Java, Rust, C/C++, etc.).

Verify that the server has started successfully:

curl http://localhost:8080/api/v1/health

Getting Started

Once the server is running, the following entry points are available:

Open /docs to browse all endpoints, inspect request/response schemas, generate code samples in multiple languages, and test directly from the browser.

Custom Web Apps

Custom web apps can be uploaded from the Dashboard's Custom Apps card and run alongside the Dashboard; once uploaded, an app is served at http://localhost:8080/apps/<name>/.

• Supported formats: a single HTML file, or a build output folder from frontend frameworks such as Vite / React / Vue (containing index.html).
• Upload steps: log in to the Dashboard → click Custom Apps → Upload → select the file or folder → set the application name <name>.
• Project template: @sinotrade/create-shioaji-app — scaffolds a Shioaji frontend project with one command.

The shioaji CLI provides direct server management, market data queries, and order placement.

shioaji --help        # list all commands
shioaji tree --all    # show full command tree (with parameters and descriptions)

Server Management