Content
# guling-trader
[](https://github.com/Guling-Pro/guling-trader/blob/main/LICENSE)
[](https://python.org)
[](#)
[](#)
[](https://github.com/Guling-Pro/guling-trader/releases/latest)
[](#)
> **[Download Latest Version](https://github.com/Guling-Pro/guling-trader/releases/latest/download/guling-trader.exe)** · **[Official Website guling.pro](https://guling.pro)**
---
**Make Agent Trading as Easy as Mobile Payments, Making it Accessible to Every Ordinary Investor.**
guling-trader is an open-source trading execution client running on Windows. It connects your independent Tonghua Shun (xiadan.exe) login client to any AI assistant (Claude / Cursor / openclaw, etc.) through the MCP (Model Context Protocol) protocol, exposing 9 trading tools - market/ limit buy/sell, check positions, check funds, check entrustments/orders, check settlement statements, read selected stocks, etc. - allowing AI to directly help you research, monitor, and place orders, while keeping your account password secure and within the official Tonghua Shun software.
After integration, you can say to AI:
> "Help me buy 100 shares of Guizhou Maotai at the current market price."
> "Check my current positions and profits."
> "Cancel the unfilled buy order for China Merchants Bank."
---
## What is Agent Trading?
**Agent Trading** refers to an AI assistant directly connecting to your real trading account, executing buy/sell operations through natural language instructions. Compared to traditional quantitative trading (programming + backtesting) or manual operation, Agent Trading skips coding and complex configurations, allowing any stock investor to instruct AI to place orders instantly.
guling-trader, combined with Tonghua Shun and MCP, is an open-source paradigm for A-share trading. Whether you use Claude for chatting, Cursor for coding, or openclaw for analysis, with guling-trader installed, AI can help you research, analyze, and generate trading suggestions - **ultimately, trading decisions and execution remain in your hands**.
---
## How to Let AI Trade A-Shares for Me?
Two paths lead to the same goal; choose one based on your technical comfort:
| Scenario | Path | Data Flow | Difficulty |
|------|------|--------|------|
| Easiest, with existing guling.pro invite code | [**A · Hosted Version**](#path-a--hosted-version) | Via guling.pro cloud | ★ |
| Using Claude / Cursor / openclaw, etc. | [**B · Self-Service with Cloud**](#path-b--self-service-with-cloud) | Via mcp.guling.pro cloud | ★★ |
> **The first step is the same for all paths**: Start the Windows trading terminal.
---
## Step 1: Launch the Windows Trading Terminal (Common to All Paths)
You need a **24/7 running Windows machine** (physical machine, cloud VPS, or Mac virtual machine like Parallels Desktop).
1. **Log in to Tonghua Shun**: Open the independent Tonghua Shun client (xiadan.exe), log in with your securities account, and stay on the order page. **New/old skin versions are acceptable** - v0.5.0 automatically adapts controls without manual switching to "old version". Do not minimize.
- **Recommended: Disable order confirmation pop-ups** (faster and more stable): In xiadan's system settings, disable options related to "confirmation before entrustment/order confirmation". Ignore pop-ups that cannot be disabled (verification codes, invalid orders, risk warnings, etc.) - the assistant will handle and record them.
2. **Run the Trading Assistant**: Download `guling-trader.exe` from [GitHub Releases](https://github.com/Guling-Pro/guling-trader/releases/latest/download/guling-trader.exe) (single-file, no installation required), and double-click to run.
- The first launch will automatically install Tesseract OCR (graphical recognition environment) silently.
- After startup, a **6-digit pairing code** (e.g., `482-739`, valid for 5 minutes) will be displayed on the screen. Remember this code for the next step.
3. **Adjust screen scaling**: Ensure Windows display settings have DPI scaling set to **100%**. 125% or 150% scaling may cause the assistant to click incorrectly.
✅ The trading terminal is now online and waiting for pairing. Choose your path to continue.
---
## Path A · Hosted Version
> ⚠️ Currently in internal testing; requires an invite code. **Send a private message to get qualification**.
Log in to guling.pro and send the **6-digit pairing code** along with a message to the hosting assistant:
> "Help me bind the trading assistant; the pairing code is 482-739."
After successful binding, you can trade directly using natural language. You don't need to configure any MCP client - the hosting assistant has set everything up.
---
## Path B · Self-Service with Cloud
Applicable to Claude Desktop, Cursor, openclaw, and any AI client supporting MCP.
**Send the following message and URL to your AI assistant:**
> URL: `https://mcp.guling.pro`
> Your message: "Follow this document to help me connect to guling-trader."
The AI will automatically fetch the installation guide from the URL and complete the pairing and connection - **using the 6-digit code for a permanent credential → mounting the MCP server → verification**.
**Principle in one sentence**: Use the 6-digit code to exchange a permanent `agent_token` at `https://mcp.guling.pro/pair`, then use the `Authorization: Bearer <token>` request header to mount the MCP server.
**Why go through mcp.guling.pro?** Your Windows terminal and AI client are usually in different networks and cannot find each other - a public server is needed as a "meeting point". guling.pro provides this relay tunnel for free, encrypting and forwarding your instructions, making it easy to use and secure.
---
## How to Ensure Trading Security?
| Feature | Description |
|------|------|
| 🔑 **No password exposure** | You log in through the official Tonghua Shun software; the assistant only simulates keyboard and mouse operations, without accessing any account passwords. |
| 🛡️ **Pure outbound connection** | No port listening or forwarding is required; like a browser, it establishes an encrypted connection outward, preventing intrusion. |
| ⏹️ **One-click disconnection** | Close Tonghua Shun or the assistant, or right-click the tray icon and select "Unpair" to disconnect the AI control completely. |
---
## Frequently Asked Questions
<details>
<summary><b>Failed to recognize verification code?</b></summary>
Automatically install Tesseract OCR during the first launch. If the automatic installation fails due to network issues, execute the following in PowerShell (Administrator):
```powershell
winget install UB-Mannheim.TesseractOCR
```
Then restart the trading assistant.
</details>
<details>
<summary><b>I'm on macOS or Linux; how can I use guling-trader?</b></summary>
guling-trader trading terminal only supports Windows. However:
- **Mac + Parallels Desktop** (recommended): Install Windows in a virtual machine and keep it running 24/7 at home or office.
- **Windows Cloud VPS**: Rent a cloud server from Alibaba Cloud, Tencent Cloud, etc., which is naturally 24/7 and doesn't require self-prepared hardware.
The AI assistant part (Claude, Cursor, etc.) can run on any system; ensure your Windows trading terminal remains online.
</details>
<details>
<summary><b>After issuing a trading command, Tonghua Shun doesn't respond?</b></summary>
Confirm that Windows **DPI scaling is set to 100%**. Scaling at 125% or 150% may cause the assistant to click incorrectly.
</details>
<details>
<summary><b>I'm using Remote Desktop (RDP); can I lock the screen or minimize the window?</b></summary>
No. Closing or minimizing the RDP window will cause Windows to stop rendering the screen, and the assistant cannot take screenshots or click.
</details>
<details>
<summary><b>Do I need to re-pair after restarting the AI client?</b></summary>
No. Your `agent_token` has been correctly written to the client configuration (via the `Authorization: Bearer` request header). If it fails to persist after each restart, check if the token is complete in the configuration file.
</details>
<details>
<summary><b>The AI says the Windows trading terminal is offline; what should I do?</b></summary>
1. Confirm `guling-trader.exe` is still running (check Task Manager or system tray).
2. Confirm Tonghua Shun is logged in and the interface is visible (not minimized).
3. If using Path B (self-service with cloud), check network connectivity.
4. Restart guling-trader.exe and try again.
</details>
<details>
<summary><b>The AI issues a trading command, but there's no response for half a minute; why?</b></summary>
Usually due to network delay or Tonghua Shun response timeout. Check:
1. Network connection stability.
2. Tonghua Shun for lag (high CPU usage, slow interface response).
3. Try again after a while, or restart the trading assistant.
If the issue persists, submit diagnostic logs to GitHub Issues (see Developer Appendix below).
</details>
---
## MCP Tool Interface Quick Reference
9 trading tools unlocked after successful pairing. Complete schema in [`docs/tools_schema.json`](docs/tools_schema.json).
| Tool | Purpose | Key Parameters |
|------|------|---------|
| `balance` | Query funds balance | — |
| `position` | Get positions list | — |
| `orders_active` | Today’s unfilled entrustments | — |
| `orders_filled` | Today’s filled orders | — |
| `settlement` | Settlement statement query | `date_range`: recent week/month/3 months/1 year |
| `watchlist` | Read Tonghua Shun selected stocks (new version) | — (top first screen, latest at top) |
| `buy` | Buy (real trading) | `stock_no`, `amount`, `price`(not set=market order with 5-level price matching/trans=limit order), `client_order_id`(optional) |
| `sell` | Sell (real trading) | `stock_no`, `amount`, `price`(not set=market order with 5-level price matching/trans=limit order), `client_order_id`(optional) |
| `cancel` | Cancel unfilled order | `entrust_no` |
> Only `pair_with_code` is exposed before pairing; complete protocol (handshake, call, reply, reject, heartbeat) in [`docs/PROTOCOL.md`](docs/PROTOCOL.md).
---
<details>
<summary>💻 Developer Appendix (click to expand)</summary>
### Local Compilation and Packaging
```powershell
# Install dependencies (including build extras)
pip install -e .[build]
# Compile into single-file exe
pyinstaller --onefile --windowed --name guling-trader -m trader
# Output path: dist\guling-trader.exe
```
### Diagnosis and Debugging
Add `--diagnose` flag during startup to output detailed logs (including screenshots, click coordinates, OCR results):
```powershell
guling-trader.exe --diagnose
```
Diagnostic logs are saved in `guling-trader-data\trader.log`; please attach relevant logs when submitting issues.
### Project Structure
```
guling-trader/
├── src/trader/
│ ├── __init__.py # Version definition
│ ├── main.py # Application entry & --diagnose flag handling
│ ├── main_window.py # Main UI (tkinter)
│ ├── tray.py # System tray menu
│ ├── bootstrap.py # Startup guide
│ ├── brand.py # Brand/version management
│ ├── config.py # Configuration loading
│ ├── dispatcher.py # 9 trading tool definitions (FALLBACK_TOOLS_SCHEMA)
│ ├── handshake.py # WebSocket handshake logic
│ ├── ws_client.py # WebSocket client
│ ├── ui_dialogs.py # UI dialogs
│ ├── installer/ # OCR dependency auto-installation
│ ├── ths/
│ │ ├── const.py # Tonghua Shun constants
│ │ └── win.py # Tonghua Shun xiadan.exe control + OCR recognition (core)
│ └── ...
├── docs/
│ ├── PROTOCOL.md # MCP frame protocol documentation
│ ├── tools_schema.json # Tool schema
│ ├── local_only_stdio_mcp_setup.md # Local private access design draft (not open yet)
│ └── specs/ # Specification documents
├── pyproject.toml # Project metadata and dependencies
├── LICENSE # GPL-3.0
└── guling-trader-data/ # Runtime data directory
└── trader.log # Diagnostic log output location
```
</details>
---
## Open-Source License
Licensed under **AGPL-3.0-or-later** - even if you modify and provide this project as a network service (SaaS), you must also make your modifications public.
## Trademark and Branding
The code is open-sourced under AGPL-3.0, but **‘Guling’, ‘Guling’, and ‘guling.pro’ are trademarks**. When secondary development or distribution is done based on this project, please keep the original link; **unauthorized use of the brand is not allowed**.
---
## ⚠️ Risk Disclaimer
**This software is an open-source tool and does not constitute any investment advice or trading guarantee**. Users are fully responsible for any asset loss caused by improper configuration, DPI scaling offset, network delay, or large model hallucinations. **The author and open-source contributors bear no responsibility**.
**Before real trading**:
1. Use the `--diagnose` command to self-check the trading process (ensure screen recognition and click accuracy).
2. Complete sufficient testing with a small account to confirm everything works correctly before using a larger account.
---
## Name Meaning
‘Gǔ’ is A-shares, and ‘Líng’ comes from Alan Turing - the source of intelligence. Bring Turing intelligence to every ordinary investor.
---
## Related Resources
- **Official Website**: https://guling.pro
- **Organization**: https://github.com/Guling-Pro
- **MCP Access Guide**: https://mcp.guling.pro
- **Issue Feedback**: [GitHub Issues](https://github.com/Guling-Pro/guling-trader/issues)
---
<div align="right">
**Guling Pro · Open Source, Honest, Serving Every Investor**
</div>
