AiyoPerps

1# AiyoPerps
2 
3[繁體中文](./Readme_zh.md)
4 
5AiyoPerps is a perpetual futures desktop terminal that supports both CEX (centralized) and DEX (decentralized) trading. It provides a full desktop UI, an MCP server for AI agents, and a local REST API.<br>
6With AiyoPerps, you can trade crypto perpetual futures **manually**, **with AI collaboration**, or **fully driven by AI**.
7 
8![Software interface](./images/main-en-01.jpg)
9 
10## Support Us
11If you think this project is cool, feel free to [**buy us a coffee**](https://utunote.com/AiyoPerps/donate)!<br>
12**When you sponsor us, you’ll also get a chance to join Taiwan’s receipt lottery.**<br>
13That’s because [Chen-Si Studio](https://utunote.com) is a team that pays taxes properly. We issue an official receipt/invoice for every bit of income, and those invoice numbers can be checked for prizes every two months.<br>
14Even if you don’t live in Taiwan, if your invoice wins, just let us know. We’ll claim the prize for you and then send you the money (after deducting any necessary handling fees).
15 
16## 0. Supported trading platform
17- CEX: [BitMEX](https://www.bitmex.com/)
18- DEX: [Hyperliquid](https://app.hyperliquid.xyz/)、[Aster](https://www.asterdex.com/)、[Grvt](https://grvt.io/)
19 
20## 1. Requirements
21- Windows, Linux, or macOS (via Docker).
22- .NET 10 Runtime (included in release builds).
23- A perpetual futures exchange account. Current supported venues are `Hyperliquid`, `BitMEX`, and `Aster`.
24 
25## 2. Run the Desktop App
26### Use a release build
271. Download the latest package from [GitHub Releases](https://github.com/phidiassj/AiyoPerps/releases/latest).
282. Extract it.
293. Run:
30   - Windows: `AiyoPerps.exe`
31   - Linux: `./AiyoPerps`
32 
33### Build and run from source
341. Clone this repo or download the full source code.<br>
35   `git clone https://github.com/phidiassj/AiyoPerps.git`
362. Build it with [Visual Studio 2026](https://visualstudio.microsoft.com/insiders).
37 
38## 3. Enable the Local MCP Server and API
391. Start the desktop app.
402. In the top toolbar, set the `HTTP API` port (default `5078`).
413. Turn the API switch `ON`.
424. Open:
43   - OpenAPI UI: `http://127.0.0.1:5078/scalar`
44   - MCP endpoint: `http://127.0.0.1:5078/mcp`
45 
46## 4. Headless Mode
47Use this when you only need REST or MCP.
48 
49### Local headless
50Start the app with `-- headless --port 5078`.<br>
51```bash
52Windows:
53AiyoPerps.exe -- headless --port 5078
54```
55```bash
56Linux:
57./AiyoPerps -- headless --port 5078
58```
59 
60### Docker
61macOS is currently supported through Docker only.<br>
62```bash
63docker run --rm --name aiyoperps -p 5078:5078 phidiassj/aiyoperps:latest
64```
65The container starts automatically in headless mode and enables the HTTP API automatically.
66 
67## 5. Connect an AI Agent
68### Recommended: use the installer to auto-register with supported AI agents
69```bash
70npx -y @phidiassj/aiyoperps-mcp-installer
71```
72This registers AiyoPerps with supported AI agents such as Codex, Claude Desktop, Claude Code CLI, and OpenClaw.<br>
73<br>
74![Installer Interface](./images/installer.jpg)
75 
76### Manual stdio bridge
77```bash
78npx -y @phidiassj/aiyoperps-mcp-bridge --quiet --url http://127.0.0.1:5078/mcp
79```
80If the installer does not support your AI agent, try this manual method.
81 
82## 6. Quick UI Workflow
831. Open `Account Manager` and add an account.
842. Create or select a tab.
853. Choose the account, then click `Enable`.
864. Set `Symbol` and `Interval`.
875. Use the right-side tabs for `Order`, `Positions`, `Orders`, and `Balances`.
88 
89## 7. More Details
90- Full API and MCP guide: [API.md](./API.md)
91- 繁體中文 API guide: [API_zh.md](./API_zh.md)
92