SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsa-share-paper-trading

a-share-paper-trading

General & other

View repository

Updated 10-16 09:34

About this skill

A-share Paper Trading

A standalone paper trading skill. The trading service, CLI, accounts, matching, and market data adapters are all within this directory and do not depend on other skill scripts.

When to Use

  • Start or check the paper trading service
  • Create/reset accounts
  • Limit buy/sell, market buy/sell, cancel orders
  • Query accounts, positions, orders, fills
  • Verify limit-up/limit-down, T+1, end-of-day expiry
  • Run simple backtests

Startup

SKILL_DIR="<本skill绝对路径>"
python3 "$SKILL_DIR/scripts/paper_trading_service.py" --host 127.0.0.1 --port 18765

Listens by default on http://127.0.0.1:18765. By default, the database no longer resides in the skill directory but in the user-level data directory:

  • macOS: ~/Library/Application Support/a-share-paper-trading/paper_trading.db
  • Linux: ${XDG_DATA_HOME:-~/.local/share}/a-share-paper-trading/paper_trading.db

If a paper trading process isalreadyrunning on this port on the local machine,do notstart a second instance: it will report Address already in use, and multiple processes may contend for the same SQLite database file. Before starting, you can first check whether the port is listening, for example:

lsof -iTCP:18765 -sTCP:LISTEN

Or send http://127.0.0.1:18765/accounts to GET(the CLI default --base-url is consistent with this). If a service already exists, simply use paper_trade_cli.py .

It is more recommended to use the control script to run it persistently:

python3 "$SKILL_DIR/scripts/paper_trading_ctl.py" start
python3 "$SKILL_DIR/scripts/paper_trading_ctl.py" status
python3 "$SKILL_DIR/scripts/paper_trading_ctl.py" stop

On macOS, if you need continuous auto-start, you can install launchd:

python3 "$SKILL_DIR/scripts/paper_trading_ctl.py" install-launchd

The service will:

  • Periodically match pending orders during trading hours
  • Stop matching during non-trading hours
  • Expire the day's unfilled orders after market close
  • Periodically write account net value snapshots

Available startup parameters:

  • --host
  • --port
  • --db-path
  • --match-interval
  • --valuation-interval
  • --idle-valuation-interval

The default port and CLI base URL have been changed to 18765, to avoid conflicts with common local development services.

CLI

python3 "$SKILL_DIR/scripts/paper_trade_cli.py" create-account alpha --cash 500000
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" list-accounts
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" show-default-account
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" set-default-account alpha
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" reset-account alpha --cash 300000
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" add-cash alpha 50000 --note 入金
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" deduct-cash alpha 10000 --note 出金
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" buy alpha 600519 100 --market
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" sell alpha 600519 100 --price 1450
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" orders alpha
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" positions alpha
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" show-account alpha
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" trades alpha
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" cancel <order_id>
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" process-orders
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" run-snapshots
python3 "$SKILL_DIR/scripts/paper_trade_cli.py" backtest 600519 --strategy sma_cross --start 2025-01-01 --end 2026-03-31 --cash 200000

Supported CLI subcommands:

  • create-account
  • show-default-account
  • set-default-account
  • reset-account
  • list-accounts
  • show-account
  • positions
  • orders
  • trades
  • buy
  • sell
  • cancel
  • add-cash
  • deduct-cash
  • process-orders
  • run-snapshots
  • backtest

Agent Execution Rules (Account Routing)

  • Before creating a paper account for the first time, you must first confirm the initial fund amount with the user.
  • If multiple accounts exist in the system and the user has not specified an account, first ask back "Which account is this operation for?" before continuing.
  • If there is only one account and that account already exists, use that account directly by default.
  • If a default account exists (show-default-account can be queried) and the user has not specified an account, use the default account first.
  • When you need to switch the default account, use set-default-account。

First-Time Initialization Fund Rules (default 100w)

  • When the user wants to trade for the first time but has not yet initialized the account funds, first ask back for confirmation and do not execute directly.
  • The default suggested initial fund is 1000000(100w). The suggested question template is:
    • "The paper account is currently not initialized. By default it will start with 100w. Confirm? If you need to change it, please provide the amount directly."
  • Only after the user explicitly confirms, execute the creation of the default account.
  • If the user provides another amount, create with the user's amount and continue with subsequent operations.

CLI Parameter Constraints (Agent Must Read)

  • buy/sell：
    • Limit orders must include --price。
    • Market orders use --marketand should not pass --price。
  • orders --status Available values:open / filled / cancelled / expired / rejected。
  • add-cash / deduct-cash The amount must be a positive number, in RMB yuan.
  • By default, prefer using --json output, to facilitate subsequent structured parsing and decision-making.

Pre-execution checks (three fixed steps before placing an order)

  1. First confirm the account route:show-default-account or list-accounts。
  2. Then confirm the funds:show-account <account_id>。
  3. Before placing an order, confirm positions and open orders:positions <account_id> and orders <account_id> --status open。

Fund adjustment rules (adding or subtracting available funds)

  • Use add-cash <account_id> <amount>for deposits, and use deduct-cash <account_id> <amount>。
  • Deposit/withdrawal amounts must be positive numbers.
  • Withdrawals can only reduce available funds and must not penetrate frozen funds; if available funds are insufficient, inform the user before adjusting.

Common errors and handling actions

  • Address already in use: Do not start the service repeatedly; use the existing service address directly.
  • default account not set: Trigger the first-time initialization clarification flow, and create a default account after confirming the amount.
  • insufficient available cash: Prompt the current available funds, and suggest depositing funds or reducing the order quantity/price.
  • insufficient sellable qty: Prompt the sellable quantity, and explain that it may be affected by T+1 or that the position is insufficient.
  • order is not open: First query the order status (it may already be filled/canceled/expired), then decide the next step.
  • market orders are only accepted during trading hours: Switch to a limit order or wait for the trading session.

Rule summary

  • Only A-shares long-only are supported
  • Buy quantity must be an integer multiple of 100 shares
  • Selling follows T+1
  • Limit order prices must conform to the 0.01 yuan minimum price tick
  • Board price limit fallback rules:
    • Main board ordinary shares 10%
    • ChiNext/STAR Market 20%
    • Main board ST 5%
  • Limit order prices must not exceed the day's price limit up/down
  • Touching the limit-up price means by default the order cannot be bought (including limit-up at the opening price)
  • Touching the limit-down price means by default the order cannot be sold (including limit-down at the opening price)
  • Market orders are accepted only during continuous auction sessions
  • No automatic matching is performed during the opening/closing call auction and lunch break periods
  • If the market data timestamp is not for the current day, it is treated as stale market data and market orders will not be filled
  • The fee model includes minimum commission, sell-side stamp duty, and Shanghai market transfer fee
  • Same-day orders expire after market close

Structure

  • scripts/paper_trading_service.py: Start the HTTP service
  • scripts/paper_trade_cli.py: CLI
  • scripts/paper_trading_ctl.py: start/stop, status, launchd installation
  • scripts/paper_trading_runtime.py: runtime default directory, port, path
  • scripts/paper_trading/: accounts, matching, valuation, data adaptation

Service interfaces

By default, these HTTP routes are exposed:

  • GET /accounts
  • GET /accounts/default
  • POST /accounts
  • POST /accounts/default
  • GET /accounts/{account_id}
  • POST /accounts/{account_id}/reset
  • POST /accounts/{account_id}/cash-adjust
  • GET /accounts/{account_id}/positions
  • GET /accounts/{account_id}/orders
  • GET /accounts/{account_id}/trades
  • POST /orders
  • POST /orders/{order_id}/cancel
  • POST /orders/process
  • POST /snapshots/run
  • POST /backtest
  • GET /health

Reference