CryptoTrade Swift — Full reference CryptoTrade Swift 使用指南

If this is your first trading bot, read this section first. The rest of the page is a reference you can come back to when you need details.

如果你第一次接触量化软件，先看这一段就够了。后面的内容像工具箱，需要查参数、查问题时再回来翻。

常见词白话解释

第一次使用建议只看三段：五分钟跑通、交易所 API 配置、智能网格。其它章节等真正遇到问题再看。

The fastest path from "nothing" to "first strategy running":

1. Pick an Ubuntu 22.04+ Linux VPS (Hetzner / DigitalOcean / Vultr / Linode / Tencent Lighthouse / AliCloud ECS all work). Minimum: 1 vCPU, 1 GB RAM, 10 GB disk.
2. SSH in. Run: curl -fsSL https://ch-license-server.cts-jz.workers.dev/install.sh | bash
3. The installer prints an access URL + a one-time Setup Token. Copy them.
4. In your cloud provider's console, open port 3000 in the security group (the OS firewall is opened automatically).
5. Open the URL in a browser → paste the Setup Token → choose a login password.
6. After login you'll see the Activation page. Paste the license key from the email we sent you. Click Activate.
7. Settings → Exchange API → add your exchange key. Then sidebar → Strategy · Spot (or Strategy · Futures) → + Add pair → fill the strategy → Start.

Everything runs on your own server. SQLite holds all state. We never upload your strategies or balances anywhere. Stop the container, your data is intact in the Docker volume.

下面是从零开始到第一条策略跑起来的最短路径。遇到看不懂的词，可以先回到上面的“常见词白话解释”。

1. 准备一台 Ubuntu 22.04+ 的云服务器。最低配置：1 核 CPU、1 GB 内存、10 GB 硬盘。
2. 用 SSH 登录服务器，运行安装命令：curl -fsSL https://ch-license-server.cts-jz.workers.dev/install.sh | bash
3. 安装结束后，记下页面里打印的访问地址和一次性 Setup Token。
4. 到云服务商控制台开放 3000 端口。这个端口可以理解成“让浏览器能访问软件的门”。
5. 浏览器打开访问地址，粘贴 Setup Token，然后设置登录密码。
6. 登录后进入激活页，粘贴邮箱收到的 license_key，点激活。
7. 进入设置，添加交易所 API；再到策略页添加交易对，保存参数后启动。

先跑通流程，比一次看懂所有参数更重要。第一次建议小金额测试，确认余额、订单、日志都正常后再加资金。

VPS

• OS: Ubuntu 22.04 LTS or newer · Debian 12 · CentOS 9 (other modern Linux distros work as long as Docker 20.10+ runs)
• CPU: 1 vCPU minimum, 2 vCPU comfortable
• RAM: 1 GB minimum, 2 GB if you run many pairs / strategies simultaneously
• Disk: 10 GB minimum — SQLite database + Docker image + a few weeks of kline cache
• Network: stable connection to your exchanges. For Binance/OKX-heavy use, a VPS in Tokyo, Singapore, or AWS ap-east is ideal (low latency to the exchange's matching engine).

Browser

Modern desktop browser — Chrome / Edge / Firefox / Safari latest two versions. The UI uses WebSocket for live price pushes, so corporate networks that block WebSocket will see the dashboard but no real-time prices.

Exchanges supported

Spot: OKX, Binance, Binance US, Bybit, Coinbase, Kraken. Futures (perpetual): OKX, Binance (more coming).

VPS 要求

• 系统：Ubuntu 22.04 LTS 及更新版本、Debian 12、CentOS 9（其它现代 Linux 发行版只要能跑 Docker 20.10+ 也行）
• CPU：1 核起步，2 核更舒服
• 内存：1 GB 起步；同时跑多交易对/多策略建议 2 GB
• 硬盘：10 GB 起步 —— SQLite + Docker 镜像 + 几周 K 线缓存
• 网络：到交易所稳定即可。重度跑 Binance/OKX 时，东京 / 新加坡 / AWS 香港的 VPS 延迟最低

浏览器要求

现代桌面浏览器：Chrome / Edge / Firefox / Safari 近两个版本。前端用 WebSocket 推实时价，公司内网封 WS 的话能看到面板但价格不会动。

支持的交易所

现货：OKX、Binance、Binance US、Bybit、Coinbase、Kraken。永续合约：OKX、Binance（更多在加）。

Step 1 — one-line installer

SSH into your VPS as a user that can sudo. Run:

curl -fsSL https://ch-license-server.cts-jz.workers.dev/install.sh | bash

The installer (now bilingual: English on the left, Chinese on the right of each line) does:

1. Checks / installs Docker + Docker Compose v2
2. Auto-configures Docker Hub China mirror if it detects slow access to docker.io (helpful for VPS in China)
3. Opens TCP port 3000 in the OS firewall (ufw / firewalld / iptables)
4. Pulls the ctszz/cts-web:latest Docker image
5. Generates a one-time Setup Token (format XXXX-XXXX-XXXX-XXXX, valid 1 hour, single use)
6. Starts the container, prints the access URL + Setup Token, and saves them to ~/cts-web/SETUP-INFO.txt

Step 2 — open the cloud firewall

The OS firewall on your VPS is opened automatically, but your cloud provider has a separate security group / firewall that you must open by hand. Find "Inbound rule" / "Security group" in:

• Tencent Lighthouse: console.cloud.tencent.com/lighthouse/firewall
• Tencent CVM: console.cloud.tencent.com/cvm/securitygroup
• AliCloud ECS: ecs.console.aliyun.com/securityGroup
• AWS EC2: console.aws.amazon.com/ec2/v2/home#SecurityGroups

Add an inbound rule: TCP / port 3000 / source 0.0.0.0/0 (or restrict to your home IP for stricter security).

Step 3 — first-time setup in the browser

Open http://<VPS-IP>:3000. The page auto-detects browser language (EN/ZH); a toggle is in the top-right.

1. Paste the Setup Token from the install output
2. Choose a login password (8+ chars; we show a strength meter)
3. Click Finish setup → the page shows a green "redirecting…" indicator and auto-logs you in

The Setup Token expires 1 hour after install and can only be used once. If you miss it, run cat ~/cts-web/SETUP-INFO.txt on the VPS to recover. If the token has already expired, cd ~/cts-web && sudo docker compose down && sudo docker volume rm cts-web_cts_data && bash install.sh resets everything.

第 1 步 —— 一行命令安装

SSH 登录 VPS（要有 sudo 权限），跑：

curl -fsSL https://ch-license-server.cts-jz.workers.dev/install.sh | bash

脚本会（输出双语，英文在左、中文在右）：

1. 检查 / 自动装 Docker + Docker Compose v2
2. 自动检测到 docker.io 访问慢就配置国内 mirror（国内 VPS 友好）
3. 开放 OS 防火墙的 TCP 3000 端口（ufw / firewalld / iptables 全覆盖）
4. 拉取镜像 ctszz/cts-web:latest
5. 生成一次性 Setup Token（XXXX-XXXX-XXXX-XXXX，1 小时有效、仅可使用一次）
6. 启动容器，打印访问地址 + Setup Token；同时保存到 ~/cts-web/SETUP-INFO.txt

第 2 步 —— 开云防火墙

VPS 的 OS 防火墙脚本已自动开，但云服务商的安全组 / 防火墙是另一回事，必须手动开。在云控制台找到"入站规则" / "安全组"：

• 腾讯轻量：console.cloud.tencent.com/lighthouse/firewall
• 腾讯 CVM：console.cloud.tencent.com/cvm/securitygroup
• 阿里云 ECS：ecs.console.aliyun.com/securityGroup
• AWS EC2：console.aws.amazon.com/ec2/v2/home#SecurityGroups

添加入站规则：TCP / 端口 3000 / 来源 0.0.0.0/0（要更严就限制为你家 IP）。

第 3 步 —— 浏览器首次设置

打开 http://<VPS-IP>:3000。页面根据浏览器语言自动判断 EN/ZH，右上角可切。

1. 粘贴安装时打印的 Setup Token
2. 设置登录密码（≥ 8 位，下方有强度指示）
3. 点完成设置 → 出现绿色"跳转中…"，自动登录

Setup Token 安装后 1 小时过期、仅使用 1 次。错过了？SSH 到 VPS 跑 cat ~/cts-web/SETUP-INFO.txt 找回。如果 token 已过期，cd ~/cts-web && sudo docker compose down && sudo docker volume rm cts-web_cts_data && bash install.sh 重置整个部署。

After login, you land on the Activation page. The license key (format QB4-XXXX-XXXX-XXXX-XXXX) is in the email we sent at purchase.

1. Paste the key into the field, click Activate
2. The server binds the license to this device — using a hardware-derived fingerprint, so the license stays bound even if you change your hostname or IP
3. Activation status appears at the top of the page. You're now ready to trade.

Device migration

Each license binds to one device at a time. To move to a new server:

1. On the old server: Settings → Activation → Release this device
2. On the new server: paste the same license key

If you've already lost access to the old server (hardware died, instance deleted), email [email protected] for a force-unbind. We allow two free force-unbinds per year per license.

Validity

• Forever license: no expiration. Activation persists as long as the license server runs (commitments in our forever-license commitments).
• Monthly / Annual: license expires at now + 30 days / now + 365 days after each purchase. Renewal: pay again from the pricing page; the system extends your validity.

登录后进入激活页。激活码（格式 QB4-XXXX-XXXX-XXXX-XXXX）在你购买后收到的邮件里。

1. 把 key 粘到输入框，点激活
2. 服务端按这台机器的硬件指纹跟 license 绑定（改主机名 / 改 IP 都不影响绑定）
3. 页面顶部显示激活状态，开始交易

换设备

每个 license 同时只能绑一台设备。换服务器的话：

1. 在旧机器上：设置 → 激活 → 解绑当前设备
2. 在新机器上：粘贴同一个 license key

旧机器已经登不上（硬件挂了 / 实例删了），发邮件 [email protected] 申请强制解绑。每个 license 每年免费两次。

有效期

• 永久 license：不过期；只要 license server 还在运行就有效（具体承诺见永久 license 承诺）
• 月度 / 年度：每次购买后有效期是 当前时间 + 30 / 365 天。续费：在定价页再付一次，系统会延长有效期
• 7 天试用：功能全开，时间到自动失效

One-line upgrade. The script (also bilingual) auto-backups → pulls the new image → restarts → health-checks → tells you the rollback command if anything goes wrong.

bash ~/cts-web/upgrade.sh

Or, equivalently:

curl -fsSL https://ch-license-server.cts-jz.workers.dev/upgrade.sh | bash

Backups

Each upgrade snapshots the data volume to ~/cts-web/backups/cts-pre-upgrade-<timestamp>.tar.gz before pulling. List all backups:

bash ~/cts-web/upgrade.sh --list

Rollback

If the new version misbehaves within 5–10 minutes, one command restores everything:

bash ~/cts-web/upgrade.sh --rollback ~/cts-web/backups/cts-pre-upgrade-20260512_180000.tar.gz

Confirms with yes, restores the volume from the tar.gz, restarts. Strategy configs, order history, API keys all come back exactly as they were before the upgrade.

一行命令升级。脚本（也是双语）自动备份 → 拉新镜像 → 重启 → 健康检查 → 出错时直接告诉你回滚命令。

bash ~/cts-web/upgrade.sh

或者直接：

curl -fsSL https://ch-license-server.cts-jz.workers.dev/upgrade.sh | bash

自动备份

每次升级在拉镜像前会把数据 volume 打包到 ~/cts-web/backups/cts-pre-upgrade-<时间戳>.tar.gz。列出所有备份：

bash ~/cts-web/upgrade.sh --list

回滚

新版本 5–10 分钟内发现问题，一条命令全恢复：

bash ~/cts-web/upgrade.sh --rollback ~/cts-web/backups/cts-pre-upgrade-20260512_180000.tar.gz

输入 yes 确认，从 tar.gz 恢复 volume，重启容器。策略配置、订单历史、API key 全部回到升级前的状态。

Settings → Exchange API → + Add Exchange. Pick the exchange, fill three fields:

API key:    your read + spot/futures trade-enabled key
Secret:     the matching secret
Passphrase: OKX only

Keys are encrypted with industry-standard authenticated encryption before being written to disk. Plaintext never appears in any log, never leaves your server.

Permissions on the exchange side

Critical: enable only Read and Trade permissions. Never enable Withdraw. If a key with Withdraw permission leaks, the attacker can drain your account; without Withdraw, the worst case is they trade your balance into bad fills.

OKX

1. OKX → top-right avatar → API → Create V5 API Key
2. Permissions: ✓ Read, ✓ Trade, ✗ Withdraw
3. IP whitelist: paste your VPS public IP (run curl ifconfig.me on the VPS)
4. Set a passphrase. Save the key + secret + passphrase right away (OKX shows them once).

Binance

1. Binance → Profile → API Management → Create API
2. Choose System generated
3. Edit restrictions: ✓ Enable Spot & Margin Trading, ✓ Enable Futures (if you'll trade perpetuals), ✗ Enable Withdrawals
4. Restrict access to trusted IPs only → add your VPS IP
5. Save key + secret immediately

Test the connection

After saving, click Test. The app makes a real read-only call to the exchange to fetch your account balance — if your balance shows up, your key, secret, and IP whitelist are all correct. If you see Invalid API-key, IP, or permissions, 9 times out of 10 the IP whitelist is the culprit.

For backup / restore of API keys, see Preferences → API backup & restore.

设置 → 交易所 API → + 添加交易所。选交易所，填三个字段：

API key:    带"读取"+"现货/合约交易"权限的 key
Secret:     对应的 secret
Passphrase: 仅 OKX 需要

Key 入库前用业界标准的认证加密算法加密。明文不进日志、不出服务器。

交易所侧权限

关键：只开读取和交易权限，绝对不要开"提现"。带提现权限的 key 泄露 = 资产被掏空；不带提现，最差情况是被人乱下单亏一点。

OKX

1. OKX → 右上角头像 → API → 创建 V5 API Key
2. 权限：✓ 查看、✓ 交易、✗ 提币
3. IP 白名单：填 VPS 公网 IP（VPS 上跑 curl ifconfig.me 拿）
4. 设 passphrase，立即保存 key + secret + passphrase（OKX 只显示一次）

Binance

1. Binance → 个人中心 → API 管理 → 创建 API
2. 类型选 系统生成
3. 编辑限制：✓ 启用现货和保证金交易、✓ 启用合约（要跑永续才开）、✗ 启用提现
4. 限制 IP → 加 VPS IP
5. 立即保存 key + secret

测试连通

保存完点 测试。app 会向交易所做一次只读的余额查询 —— 能看到你的余额，就说明 key、secret、IP 白名单都对。看到 Invalid API-key, IP, or permissions，十有八九是 IP 白名单的问题。

API key 备份与恢复见偏好设置 → API 备份与恢复。

Profit calculations and backtests use the taker fee rate. By default the app uses each exchange's standard rate (e.g. 0.1% for Binance spot, 0.08% for OKX). If you're a VIP, have a rebate, or pay fees in BNB, the default is wrong and your P&L numbers will be off.

Override per exchange

Settings → Trading Fees → click Set Fee on the exchange row. Three sources are shown:

• Manual — what you enter here
• Auto-derived — calculated from your actual fills over time
• Default — the exchange's published rate

Priority: Manual > Auto > Default > 0.1% fallback. Enter your real rate as a percent (e.g. 0.08 = 0.08%) and save. The new rate applies everywhere the app calculates P&L.

Backtest fee

The backtest engine uses a global backtest.takerFeeRate (default 0.001 = 0.1%). Set it independently from live fees in the Backtest config screen — useful for stress-testing under conservative assumptions.

盈亏计算和回测都用 taker 手续费率。默认引擎用各交易所的标准费率（Binance 现货 0.1%、OKX 0.08% 等）。你是 VIP、有返佣、或用 BNB 抵扣手续费时，默认值就错了，盈亏算不准。

按交易所覆盖

设置 → 交易手续费 → 在交易所那一行点设置费率。会显示三个来源：

• 手动 —— 你这里填的值
• 自动推导 —— 根据你历史成交反推得到的实际费率
• 默认 —— 交易所公开费率

优先级：手动 > 自动 > 默认 > 0.1% 兜底。输入实际费率（如 0.08 表示 0.08%）保存。新费率立刻应用到所有盈亏计算的地方。

回测专用费率

回测引擎用全局 backtest.takerFeeRate（默认 0.001 = 0.1%），跟实盘费率独立设置 —— 用更保守的费率压测策略。

Smart grid is the default and most-used spot strategy. It ladders into a position on the way down (DCA) and exits the entire position on a rebound past your take-profit. Designed for ranging or mildly-down markets.

Add a pair & start trading

Adding a trading pair lives inside the strategy page (not a separate menu):

1. Sidebar → Strategy · Spot
2. Click + Add pair at the top
3. Pick exchange (from your saved API keys), enter symbol in BTC/USDT form, save → the pair appears as Stopped
4. Click the pair → strategy editor opens. Fill the parameters below.
5. Save → click Start. The bot subscribes to live prices and begins acting.

Per-pair runtime modifiers (on the pair card):

• Sell-only mode: only sell orders are placed; lets you exit gracefully
• Take-profit stop: stop the bot the next time TP triggers (used to ramp down a strategy)

How it works

1. The bot waits near the current price. When price drops by the distance you set for the first level, it places the first buy.
2. If price keeps falling, the next level can buy again. How much each level buys depends on your selected sizing method.
3. Once a position is held, the overall take-profit watches the average entry price. When price rebounds to your target, the bot exits the whole position.
4. If price keeps falling and stop-loss is enabled, the bot exits when the loss reaches your limit.

Settings explained

Name in the app	What it means	Beginner reference
Max buy orders	The most times this strategy can buy into the position. More orders spread the capital out, but require more total capital.	5–10 orders
First order amount	How much USDT the first buy uses.	5–10% of allocated capital
Sizing method	Whether later buys stay the same size or get larger as price drops.	Double for moderate volatility
Spacing type	Whether the next buy is triggered by a percentage drop or by a fixed USDT price gap.	Percentage
Base spacing	How far price must move from the previous buy before the next buy can trigger.	1.5–3% for BTC; wider for altcoins
Trailing buy / bounce ratio	After price reaches a buy level, wait for a small bounce before buying. This can reduce buying too early during a fast drop.	0 means buy immediately
Per-order take-profit	Allows each buy order to sell independently once that order is profitable.	Optional; off for first run
Per-order TP / pullback	The profit target for one order, plus how much price can pull back after reaching the target before selling.	0.5% / 0.3%
Overall take-profit	Closes the whole position once the combined position reaches the profit target.	On
Overall TP ratio	The profit percentage needed before the whole position exits.	1.5–3%
Overall trailing TP / pullback	After the profit target is reached, keep following the high and sell after price pulls back.	0.5% / 0.3%
Stop-loss	Exits when the loss reaches your limit, so the loss does not keep expanding.	On if unattended
Stop-loss mode / ratio	Controls what price or loss percentage triggers the exit.	Use average-entry drawdown first

Suggested starting config

First-time users on BTC/USDT: 5 buy orders · double sizing · 2% base spacing · overall TP 1.5%. Backtest on the past 30 days first. Treat this as a starting point, not advice.

智能网格是现货最常用的默认策略：跌下来阶梯买入（DCA），整体反弹超过止盈后一次性全卖。设计目标是震荡 / 轻微下跌行情。

添加交易对 & 启动

加交易对在策略页里完成（没有单独的菜单）：

1. 侧边栏 → 策略 · 现货
2. 顶部点 + 添加交易对
3. 选交易所（从已保存的 API key 里挑），符号填 BTC/USDT 写法，保存 → 列表里出现，状态已停止
4. 点这个交易对 → 进入策略编辑器，填下面的参数
5. 保存 → 点启动。机器人订阅实时价开始干活。

每个交易对卡片上的运行时控制：

• 只卖模式：只挂卖单，用于优雅退出
• 止盈即停：下一次整体止盈触发后策略自停（逐步减仓时用）

工作原理

1. 机器人在当前价位等。价格跌到你设置的第一档距离，就下第一笔买单。
2. 继续下跌时，下一档继续买入；每档买多少钱，由你选择的“加仓方式”决定。
3. 有持仓后，整体止盈会盯着持仓均价。价格反弹到你设置的目标，就一次性卖出。
4. 如果价格继续下跌，并且你开启了止损，亏损到设定比例时会退出。

页面设置说明

页面上看到的名称	怎么理解	新手参考
最大买入单数	这条策略最多分几次买入。单数越多，资金分得越散，抗下跌能力更强，但需要更多本金。	5–10 单
首单金额	第一笔买入用多少 USDT。	分配资金的 5%–10%
加仓方式	后面的单子是每次一样大，还是越跌买得越多。	中等波动选“翻倍”
间隔类型	用百分比距离补仓，还是用固定 USDT 价差补仓。	新手选“百分比”
基础间隔	价格比上一单跌多少，才触发下一笔买入。	BTC 1.5%–3%；小币种更宽
追踪买入 / 反弹比例	价格跌到目标后，不立刻买，等它反弹一点再买，减少接飞刀的概率。	0 表示触达就买
逐单止盈	每一笔买单单独赚钱后，可以单独卖出。	新手可先关闭
逐单止盈比例 / 回撤比例	单笔盈利到目标后卖出；如果开启追踪，会等价格从高点回落后再卖。	0.5% / 0.3%
整体止盈	整组持仓达到盈利目标后，一次性全部卖出。	建议开启
整体止盈比例	整组持仓赚多少百分比后卖出。	1.5%–3%
整体追踪止盈 / 回撤比例	达到止盈目标后继续观察高点，回落到设定比例再卖出。	0.5% / 0.3%
止损	亏损达到底线时退出，防止亏损继续扩大。	无人值守建议开启
止损方式 / 止损比例	按整体持仓亏损比例触发，或按你选择的基准价格触发。	先用整体均价回撤

建议起步配置

首次 BTC/USDT 上手：5 单 · 翻倍加仓 · 基础间隔 2% · 整体止盈 1.5%。先用过去 30 天数据回测一遍。这是起点不是建议，请自行调整。

Custom levels gives you full control over each buy level: amount, spacing, take-profit, and pullback. Use it when you have a specific view of the chart, such as buying more heavily near a known support zone.

Structure

A custom strategy is a list of buy levels. Each level can set:

• Level amount — how much USDT this level will use
• Spacing type — percentage spacing or fixed price spacing
• Spacing value — how far from the previous level before this level buys
• Level take-profit — how much this level should earn before it can sell
• Pullback trigger — after the target is reached, how much price can pull back before selling

Each leg's TP fires independently. Combine with overall TP / cut-loss the same way as Smart grid.

When to use vs Smart

Use Smart when: you want a uniform, formula-driven ladder. Use Custom when: you've manually mapped support / resistance and want different sizing or spacing at different levels (e.g., heavier buys at a major support).

自定义档位给你每一档完全独立的控制：每档可以独立设金额、档距类型、基础间距、网格止盈%、网格回撤%。适合对图表结构有明确判断的场景（比如知道某个关键支撑想加密买入）。

结构

自定义策略就是一组“买入档位”。每一档都可以单独设置：

• 本档金额 —— 这一档准备用多少 USDT 买入
• 间隔类型 —— 按百分比间隔，或按固定价格间隔
• 间隔值 —— 距离上一档多远才买入；第一档是相对当前价
• 本档止盈 —— 这一档单独赚多少后可以卖出
• 回撤触发 —— 达到止盈后，如果要追踪高点，回落多少再卖

每档止盈独立触发。整体止盈 / 斩仓的搭配方式跟智能网格一样。

什么时候用 Custom 而不是 Smart

用 Smart：想要一套公式驱动的、均匀的阶梯加仓。用 Custom：手动标好了支撑/压力，想在不同档位用不同的金额和间距（比如关键支撑加大金额）。

Within a price range you've identified, the bot ladders into a perpetual futures position and exits when take-profit or stop-loss fires. Direction (long or short) is set when you create the pair. TP and SL are placed exchange-side — they trigger even if the bot crashes or the server reboots.

Add a futures pair

1. Sidebar → Strategy · Futures
2. Click + Add pair; pick exchange + symbol (e.g. BTC/USDT) + direction (long / short) + leverage → save
3. Click the pair → fill the parameters below → save → Start

Core settings

Name in the app	What it means
Contract type	The current guide describes perpetual futures.
Margin mode	Cross or isolated margin. Understand liquidation risk before using futures.
Leverage	How many times your exposure is amplified. Higher leverage increases both profit and loss, and liquidation comes faster.
Price range	The upper and lower price area where you expect price to move back and forth.
Grid count	How many levels the price range is divided into.
Total position size	The maximum position size this futures strategy can use.
Allocation method	Whether each level uses equal size or a custom distribution.
Spacing type	Whether levels are evenly spaced or spaced by percentage/log scale.

Take-profit / stop-loss

• Take-profit switch + ratio: close the position after the profit reaches your target.
• Trailing take-profit: after the target is reached, keep following the high and close after a pullback.
• Stop-loss switch + mode + value: exit when the loss reaches your limit, based on percentage, fixed price, or leaving the range.
• Trailing stop-loss: lets the stop-loss line move as price changes.

Advanced flags

• Trend exit: exit early if the larger trend turns against your position.
• Liquidation protection: emergency-close before the exchange liquidation engine takes over.
• Auto restart: after one cycle closes, start the next cycle with the same settings.

在你判断的价格区间内，机器人阶梯加仓永续合约，触发止盈/止损时离场。方向（多/空）在创建交易对时定。TP 和 SL 都挂在交易所侧 —— 机器人崩溃或服务器重启都不影响触发。

添加合约交易对

1. 侧边栏 → 策略 · 合约
2. 点 + 添加交易对；选交易所 + 符号（如 BTC/USDT）+ 方向（多 / 空）+ 杠杆 → 保存
3. 点交易对 → 填下面的参数 → 保存 → 启动

核心设置

页面上看到的名称	怎么理解
合约类型	当前只说明永续合约。
保证金模式	使用全仓或逐仓。新手需要先理解爆仓风险，再使用合约。
杠杆倍数	用几倍杠杆交易。倍数越高，盈利和亏损都会被放大，爆仓也更快。
价格区间	你认为价格会来回震荡的上限和下限。
网格数量	把价格区间分成多少档交易。
总仓位	这条合约策略最多使用多少仓位。
每档分配方式	每一档是平均分配，还是按你设置的方式分配。
档距类型	每一档之间是等距离，还是按比例拉开。

止盈 / 止损

• 止盈开关 + 止盈比例：盈利达到多少百分比后平仓。
• 跟踪止盈：盈利达到目标后继续跟踪高点，价格回落后再卖。
• 止损开关 + 止损方式 + 止损值：亏损达到底线就退出，可按均价百分比、固定价格、跌出区间来触发。
• 跟踪止损：止损线可以随着价格变化动态移动。

高级开关

• 趋势反向退出：大趋势变得不利时提前离场。
• 爆仓保护：接近爆仓前主动平仓，尽量避免被交易所强平。
• 自动重开：一轮交易结束后，用同样参数自动开始下一轮。

Futures high-risk warning: Perpetuals use leverage. In a volatile move, positions can be liquidated in seconds, resulting in total loss of margin. Use only capital you can afford to lose entirely. Read the full risk disclosure before trading.

Three built-in guardrails

The futures module runs three background workers, separate from the strategy itself:

• Position reconciler (every 15s) — detects orphan trade cycles (exchange shows 0 position but the local record says a cycle is still open) and auto-cleans. Triggers after restarts / network blips.
• Avg-entry corrector (every 60s) — if the local avg-entry price drifts from the exchange's actual value by > 0.1%, snaps to the exchange value and re-places TP/SL orders to match.
• Health monitor (every 15s) — circuit breaker: if position size, avg entry, or stop-order count drift from expected for > 2 minutes, the strategy is auto-paused and you get a UI notification. Manual investigation required to resume.

Cycle state machine

Every futures cycle goes through an explicit state machine — illegal transitions are rejected and logged:

CREATED → OPENING_FIRST → POSITION_HELD → CLOSED
              ↘    ↗            ↘
               FAILED (soft reject / verify failure / breaker)

What's logged

Every call the bot makes to the exchange (placing / cancelling orders, fetching positions, etc.) is recorded in a request log, kept for 7 days. If a critical write operation fails — for example a take-profit order didn't actually land on the exchange — a critical entry shows up in the Logs page.

合约高风险警告：永续合约带杠杆，剧烈行情中持仓可能秒级被强平，保证金全损。请只用能完全亏损的资金交易。详细见风险披露。

三道内置防护

合约模块在策略本身之外，跑三个后台 worker：

• 仓位对账器（每 15 秒）—— 检测幽灵周期（交易所显示 0 仓位但本地记录里周期还开着），自动清理。重启 / 网络抖动后触发。
• 均价校正器（每 60 秒）—— 本地均价跟交易所真实均价漂移 > 0.1%，强制对齐到交易所值并重新挂 TP/SL。
• 健康监控（每 15 秒）—— 熔断器：仓位、均价、止损单数 偏离预期 > 2 分钟，策略自动暂停并弹通知。需要手动排查后才能恢复。

周期状态机

每个合约周期都走显式状态机，非法转移会被拒绝并记录：

CREATED → OPENING_FIRST → POSITION_HELD → CLOSED
              ↘    ↗            ↘
               FAILED（软拒绝 / 验证失败 / 熔断）

日志记录

机器人调用交易所的每一次（下单、撤单、查仓 等）都会记录到请求日志，保留 7 天。关键写操作失败（比如某笔止盈单实际没挂到交易所）会在日志页出现一条 critical 级别记录。

The backtest engine replays historical K-lines through the same strategy code path the live engine uses — so what you see in backtest is exactly what would have happened (modulo slippage). Currently the spot strategies are exposed in the UI; the futures backtest path exists internally but isn't surfaced as a menu yet — that one is coming.

Data preparation

1. Backtest page → Data dir → pick a folder on the VPS for cached K-line data (default ~/cts-web/backtest-data)
2. Available range shows the date range you currently have cached
3. To fetch new data: choose the pair + interval + range → Fetch; the engine pulls from the exchange and caches as CSV

Running a backtest

1. Pick the strategy config (clone an existing live config or build from scratch)
2. Pick the date range + symbol + initial balance
3. Click Start; speed multiplier (1× / 10× / 100× / max) controls replay rate
4. The Orders / Profit panels update in real time as the simulation runs

What's accurate vs approximated

• Accurate: order fills at K-line OHLC bands, strategy decision logic, fees, P&L
• Approximated: slippage (limit orders are assumed to fill at the limit price if the bar touches it), partial fills (assumed full), maker / taker mix (always taker)

For aggressive strategies (very tight spreads, scalping), backtest results overstate performance by 0.05–0.15% per trade. Bake in a buffer.

回测引擎用跟实盘同一份策略代码跑历史 K 线 —— 所以回测看到的就是当时真实会发生的事（滑点除外）。目前 UI 暴露的是现货回测；合约回测的内部能力已有，但还没在菜单里开放，后续会加。

数据准备

1. 回测页 → 数据目录 → 选 VPS 上一个文件夹存 K 线缓存（默认 ~/cts-web/backtest-data）
2. 可用区间显示当前缓存覆盖的时间范围
3. 拉新数据：选交易对 + 周期 + 时间段 → 下载；引擎从交易所拉并存为 CSV

跑回测

1. 选策略配置（克隆实盘配置或新建）
2. 选时间段 + 交易对 + 初始余额
3. 点开始；速度倍率（1× / 10× / 100× / 最大）控制重放速度
4. 订单 / 收益面板会跟着模拟实时刷新

哪些精确哪些近似

• 精确：K 线 OHLC 范围内的撮合、策略决策逻辑、手续费、盈亏
• 近似：滑点（限价单假设 bar 触碰即按限价成交）、部分成交（按全成交处理）、maker/taker 区分（统一按 taker）

激进策略（极小价差、超短线）回测会高估 0.05%–0.15% / 笔。请预留缓冲。

Dashboard

Live overview of balance, open positions, today's P&L, active strategies. Prices are pushed over WebSocket every few seconds — if the dashboard freezes, see the Troubleshooting section.

Orders

Sidebar has two views: Orders · Spot and Orders · Futures. Each row uses a "plan / truth" data model — the price + amount columns are what the strategy planned; avgFillPrice + filledAmount are what the exchange actually filled. P&L is always computed from the truth side.

Profit details

From the Dashboard, click Details on the P&L card to open the Profit page — aggregated realized + unrealized P&L per pair, per cycle, per day. Export to CSV for tax / accounting.

Logs

Sidebar → Logs. Filterable error log with severity info / warning / error / critical. The critical level is the one to watch — it indicates an op that failed verification (e.g., a TP/SL order didn't actually land on the exchange).

The reconciler / avg-entry corrector / health monitor run automatically in the background (see futures guardrails). You don't need a manual button — anomalies surface as critical log entries and auto-pause notifications.

Dashboard

实时总览：余额、持仓、今日盈亏、运行中的策略。价格通过 WebSocket 几秒一次推送 —— 面板卡住的话看下面"故障排查"。

订单

侧边栏有两个视图：订单 · 现货 和 订单 · 合约。每行用 "plan/truth" 数据模型 —— price + amount 列是策略计划的值；avgFillPrice + filledAmount 是交易所实际成交。盈亏永远按 truth 算。

收益详情

从 Dashboard 的盈亏卡片点详情进入收益页 —— 按交易对 / 周期 / 日聚合的已实现 + 未实现盈亏。可导出 CSV 给税务 / 财务。

日志

侧边栏 → 日志。可筛选错误日志，级别 info / warning / error / critical。重点盯 critical —— 表示某个操作验证失败（比如 TP/SL 单实际没挂到交易所）。

对账器 / 均价校正器 / 健康监控都在后台自动跑（见合约风险与防护），无需手动按钮 —— 异常会进 critical 日志 + 自动暂停通知。

Pipe critical strategy events and a daily P&L summary to your phone via a Telegram bot — no email noise.

Setup

1. Create a bot: open Telegram → message @BotFather → /newbot → name it → BotFather hands you a Bot Token (looks like 1234567890:AAFx…). Save it.
2. Get your Chat ID: send any message to your new bot first (otherwise the bot can't message you), then forward a message of yours to @userinfobot — it replies with a numeric ID like 123456789. That's your Chat ID.
3. Open the app → Settings → Telegram Notifications → enable, paste Bot Token + Chat ID, save.

What you'll receive

• Daily P&L summary — a brief once-a-day digest of yesterday's realized P&L per pair
• Critical alerts — strategy auto-pause, TP/SL hang verification failure, API key invalidation, license issues. Same severity as the in-app critical log entries.

Routine events (every fill, every minor warning) are intentionally NOT sent — to keep your phone usable.

通过 Telegram bot 把关键策略事件和每日盈亏汇总推到手机 —— 不被邮件刷屏。

设置步骤

1. 建一个 bot：Telegram 里给 @BotFather 发 /newbot → 取名 → BotFather 给你一个 Bot Token（形如 1234567890:AAFx…），存好。
2. 拿你的 Chat ID：先给新 bot 发条任意消息（否则 bot 无法主动找你），然后把你自己的一条消息转发给 @userinfobot，它会回一个数字 ID 如 123456789，就是 Chat ID。
3. App 里 → 设置 → Telegram 通知 → 启用，粘贴 Bot Token + Chat ID，保存。

会收到什么

• 每日盈亏汇总 —— 每天一次，简短回顾昨日各交易对已实现盈亏
• 关键告警 —— 策略自动暂停、TP/SL 挂单验证失败、API key 失效、license 问题。跟应用内 critical 日志级别一致。

日常事件（每笔成交、轻微警告）有意不推送 —— 保护你手机的使用体验。

Settings → Preferences hosts small tweaks that don't affect trading logic:

• Theme: Light / Dark / Follow system. Persists per device.
• Auto-resume strategies on startup: if the container restarts (upgrade, host reboot), strategies that were running before automatically come back up. Default: on. Turn off if you want a manual re-confirmation before any live trading after a restart.
• Price precision: how many decimal places to display in tables and tickers. Auto follows the market's tick size; or pick a fixed digit count for consistency.
• UI language: English.

API backup & restore

Settings → API Backup & Restore:

• Backup Now — downloads a TXT file with all your encrypted API keys (still readable JSON; store offline)
• Restore From File — uploads a previously-saved file and re-creates the exchange entries
• Clear All Data — wipes everything (strategies, pairs, orders, API keys, logs). Before wiping, it auto-exports your API keys to a TXT file so you can re-import them after a fresh install.

设置 → 偏好 里是几个不影响交易逻辑的小开关：

• 主题：明色 / 暗色 / 跟随系统，按设备保存
• 启动自动恢复策略：容器重启（升级、宿主重启）后，之前运行的策略自动恢复。默认开。重启后想手动确认再上实盘的话关掉
• 价格精度：表格 / ticker 显示几位小数。自动跟随市场 tick size；或固定位数保持视觉一致
• UI 语言：English / 中文，每页右上角可切，也可在设置里切

API 备份与恢复

设置 → API 备份 / 恢复：

• 立即备份 —— 下载一个 TXT 文件，里面是你所有加密 API key（JSON 可读，请离线存放）
• 从文件恢复 —— 上传之前的备份，重建交易所配置
• 清除所有数据 —— 抹掉一切（策略、交易对、订单、API key、日志）。清除之前会自动把 API key 导成 TXT，方便重装后恢复

Can I run multiple pairs at the same time?

Yes. Each pair is an independent strategy instance with its own WebSocket subscription and execution loop. Practical limit on a 2 GB VPS: 20–30 pairs running simultaneously.

Can I use the same exchange account on multiple pairs?

Yes, completely unlimited. One Binance / OKX account can serve dozens of pairs in the bot — the connections are pooled internally so adding more pairs doesn't multiply your API request count.

Can I run different exchanges in parallel?

Yes. Add separate API keys per exchange in Settings, then assign pairs to each. Strategies are independent across exchanges.

Does it work in mainland China?

Yes. The installer auto-detects slow access to Docker Hub and configures a China mirror automatically. Most exchange APIs (Binance, OKX, Bybit) work fine from China-based VPS — but you may need a Hong Kong / Singapore VPS for stable connections to global exchanges. Some exchanges block China IPs entirely (Coinbase, Kraken).

What data is stored, and where?

Everything is in a SQLite database inside the Docker volume cts-web_cts_data, on your own VPS at /var/lib/docker/volumes/cts-web_cts_data/_data/. Includes: strategy configs, order history, API keys (encrypted), license activation, error logs. We never send any of this off your server.

Can I export my data?

Yes. Orders → Export (CSV); API keys → Export (encrypted JSON); the SQLite file itself can be copied directly from the volume.

What happens if my VPS dies?

Strategy positions are safe — they live on the exchange, not in the bot. Open orders (limits, TP/SL on futures) stay live and trigger normally. Once you restore the bot on a new VPS (install + restore data from backup), it reconciles with the exchange and resumes.

Will updates break my strategies?

Strategy schemas are forward-compatible — new fields default to safe values, removed fields are tolerated as unknown. Major breaking changes are rare and called out in the release notes. The upgrade.sh script auto-backs up before every upgrade, so rollback is one command away.

Do you have any access to my funds?

No. Your API keys live encrypted on your VPS. We don't have a copy. We strongly recommend you create the API keys without Withdraw permission, so even if the bot were ever compromised, the worst case is trades on your behalf — not withdrawals.

能同时跑几个交易对？

能，不限。每个 pair 是独立的策略实例，自己的 WebSocket 订阅、自己的执行循环。2 GB VPS 实测可同时跑 20–30 个 pair。

同一个交易所账号可以挂多个交易对吗？

可以，完全不限。一个 Binance / OKX 账号能服务机器人里几十个交易对 —— 连接内部共享，加交易对不会让 API 请求量翻倍。

能同时跑多个交易所吗？

能。设置里每个交易所加各自的 API key，然后给 pair 分配对应交易所。各交易所策略相互独立。

中国大陆能用吗？

能。安装脚本检测到 Docker Hub 访问慢会自动配国内 mirror。多数交易所 API（Binance、OKX、Bybit）在国内 VPS 跑没问题，但稳定连接全球交易所可能需要香港 / 新加坡 VPS。少数交易所完全封 IP（Coinbase、Kraken）。

数据存哪里？

全部在你 VPS 的 SQLite 数据库，位于 Docker volume cts-web_cts_data，物理路径 /var/lib/docker/volumes/cts-web_cts_data/_data/。包括：策略配置、订单历史、API key（加密）、激活状态、错误日志。任何内容都不会上传。

怎么导出数据？

订单 → 导出（CSV）；API key → 导出（加密 JSON）；SQLite 文件本身也可以直接从 volume 复制走。

VPS 挂了怎么办？

仓位是安全的 —— 它在交易所，不在机器人里。挂单（限价单、合约 TP/SL）都还在交易所正常工作。新 VPS 上重装 + 恢复备份后，机器人跟交易所重新对账，继续跑。

升级会不会让现有策略炸掉？

策略 schema 向前兼容 —— 新字段默认安全值，废弃字段当未知容忍。大版本破坏性变更很少，发布说明会明确标出。upgrade.sh 升级前自动备份，回滚就一条命令。

你们能动我的钱吗？

不能。API key 加密存在你 VPS，我们没有副本。强烈建议你创建 API key 时不要开提现，这样即使机器人被攻破，最坏情况也只是被人乱交易，不会被提走。

"Cannot connect" / blank page in the browser

Ports. Run curl http://localhost:3000 on the VPS — if you get HTML, the container is up and your cloud firewall is the culprit (re-check the security group). If you don't get HTML, run cd ~/cts-web && sudo docker compose ps and check the container status.

Setup Token doesn't work

Tokens expire 1 hour after install and can only be used once. Re-print: cat ~/cts-web/SETUP-INFO.txt. If you already used it (e.g., clicked submit twice), the second attempt errors out as "setup already completed" — that's the new safety net; just refresh and you should be logged in already.

API test fails: Invalid API-key, IP, or permissions

9/10 times: IP whitelist on the exchange side is missing your VPS IP. Run curl ifconfig.me on the VPS to get the current public IP and add it to the exchange's API restriction. If the IP changed (e.g., AWS Elastic IP re-assigned), the old whitelist entry is stale.

"License key invalid" / "Device limit reached"

License is bound to a previous machine. Settings → Activation → Release this device on the old machine, or email support for force-unbind.

Strategies stop firing after a few hours

Live-price connection dropped. The engine auto-reconnects, but rare network conditions can break the reconnect loop. From the Strategy page, stop and re-start the affected pair. If the problem recurs, open the Logs page and look for critical-level entries; if you see repeated connection-died errors, restart the container: cd ~/cts-web && sudo docker compose restart.

Futures TP/SL didn't trigger

TP/SL on futures are exchange-side algo orders. Three things to check:

1. Strategy → check TP/SL is actually enabled
2. Logs → look for the TP/SL placement attempt (search the cycle ID); a critical-level entry means the order failed verification
3. Exchange UI → open the perpetuals positions page, check "conditional / algo orders" tab — should see your TP/SL there

If a TP/SL order disappeared (you cancelled it on the exchange side, or your account was paused and reactivated), the health monitor will auto-pause the strategy within 2 minutes. Then it's safe to manually inspect and resume.

Update broke something

One command rollback: bash ~/cts-web/upgrade.sh --rollback ~/cts-web/backups/<latest backup>.tar.gz. List backups with bash ~/cts-web/upgrade.sh --list. The backup captures the data volume as it was right before the upgrade.

I see a "critical" entry in the logs

A write operation didn't verify (e.g., a TP/SL order placement succeeded but a follow-up check on the exchange didn't see it). The log message shows the cycle ID and the operation. The health monitor will likely auto-pause the affected pair within 2 minutes. Once you've found and resolved the cause, manually resume the strategy.

Help, my VPS public IP changed

Update the IP whitelist on the exchange API key. The bot doesn't need any reconfiguration — it doesn't care what IP it has.

Still stuck? Email [email protected] with: VPS provider + OS, container status output (sudo docker compose ps), and the last 50 lines of logs (sudo docker logs --tail 50 crypto-trade-swift-web).

"无法连接" / 浏览器空白页

端口问题。在 VPS 上跑 curl http://localhost:3000 —— 能拿到 HTML 说明容器正常，问题在云防火墙（再检查安全组）。拿不到 HTML，跑 cd ~/cts-web && sudo docker compose ps 看容器状态。

Setup Token 失效

Token 安装后 1 小时过期、仅可用 1 次。重新看：cat ~/cts-web/SETUP-INFO.txt。如果已经用过（比如点了两次提交），第二次会报 "setup already completed" —— 这是新加的安全网，刷新一下其实你已经登录了。

API 测试失败：Invalid API-key, IP, or permissions

十有八九：交易所侧 IP 白名单没加你 VPS IP。在 VPS 跑 curl ifconfig.me 拿当前公网 IP 加到交易所 API 限制里。IP 变了（比如 AWS 弹性 IP 重新分配），老白名单就失效。

"License key invalid" / "设备数达上限"

License 绑在旧机器上了。旧机器 设置 → 激活 → 解绑当前设备，或发邮件 support 申请强制解绑。

策略跑几小时后停止下单

实时价连接断了。引擎会自动重连，但极少数网络条件下重连不上。到策略页把对应交易对停了再启。重复出问题就看日志 critical 级别，反复出现"连接断开"错误就重启容器：cd ~/cts-web && sudo docker compose restart。

合约 TP/SL 没触发

合约 TP/SL 是挂在交易所的 algo 单。三步排查：

1. 策略 → 确认 TP/SL 实际开了
2. 日志 → 找 TP/SL 挂单尝试（按 cycle ID 搜）；critical 级别说明挂单验证失败
3. 交易所 UI → 永续仓位页，看"条件单 / algo 单"标签 —— 应能看到你的 TP/SL

如果 TP/SL 单消失了（你在交易所侧撤了，或账户被暂停后恢复），健康监控会在 2 分钟内自动暂停策略。然后再人工查看 + 恢复。

升级后坏掉了

一行回滚：bash ~/cts-web/upgrade.sh --rollback ~/cts-web/backups/<最新备份>.tar.gz。列备份：bash ~/cts-web/upgrade.sh --list。备份是升级前一刻 volume 的完整快照。

日志里看到 "critical" 级别

某个写操作没通过验证（比如 TP/SL 下单成功但接下来查仓时交易所没看见）。日志里会写明 cycle ID 和操作。健康监控大概率会在 2 分钟内自动暂停该交易对。排查清楚原因后再手动恢复。

VPS 公网 IP 变了

到交易所 API key 设置里更新 IP 白名单。机器人本身不用动 —— 它不关心自己 IP 是什么。

还是搞不定？发邮件给 [email protected]，附上：VPS 厂商 + 系统、容器状态（sudo docker compose ps），以及最近 50 行日志（sudo docker logs --tail 50 crypto-trade-swift-web）。