专业的期货CTP量化交易框架


Keywords
futures, trading, quantitative, CTP, backtest, algorithmic-trading
License
NCGL-UK-2.0
Install
pip install ssquant==0.4.1

Documentation

SSQuant - 期货量化交易框架

🐿️ 松鼠Quant | 专业的期货CTP量化交易框架 image

PyPI Python 3.9+ License

GitHub | Gitee(国内推荐)

一次编写,三处运行 - 回测 / SIMNOW模拟 / 实盘CTP


🎯 核心特性

✅ 统一的策略框架

  • 一套代码三处运行 - 同一份策略代码可在回测、SIMNOW模拟、实盘CTP三种环境下运行
  • 完整的数据支持 - K线数据(1m/5m/15m/30m/1h/4h/1d)+ TICK逐笔数据
  • 多品种多周期 - 同时交易多个品种,使用不同周期数据

✅ 强大的交易功能

  • 自动开平仓管理 - 智能识别开平仓、今昨仓
  • 智能算法交易 - 支持限价单排队、超时撤单、追价重发等高级逻辑
  • 实时回调系统 - on_trade/on_order/on_cancel 实时通知
  • TICK流双驱动 - K线驱动 + TICK驱动两种模式

✅ 丰富的策略示例

  • 19个完整策略示例
  • 涵盖趋势、套利、轮动、期权、机器学习等类型
  • 从入门到高级,循序渐进

🖥️ 系统要求

项目 要求
操作系统 Windows 10+(⚠️ 目前仅支持 Windows,Linux 版本待更新)
Python 3.9 ~ 3.14
CTP版本 6.7.7 ~ 6.7.10
内存 4GB+

⚡ 快速开始

1. 安装

从 GitHub/Gitee 源码安装

如果您下载了源码压缩包(通常解压后文件夹名为 ssquant-main),或者通过 git clone 拉取了代码:

  1. 打开终端(CMD/PowerShell),进入该文件夹(确保能看到 setup.py 文件)。
  2. 运行安装命令:
pip install -e .

注意

  • 命令最后有一个点 .,代表当前目录,不要漏掉。
  • 文件夹名字(如 ssquant-main)不影响安装,只要目录结构正确即可。

❓ 常见问题:ModuleNotFoundError: No module named 'ssquant'

如果运行策略时遇到这个错误:

ModuleNotFoundError: No module named 'ssquant'

原因:ssquant 未安装或已被卸载。

解决方法

  1. 检查是否已安装:

    pip list | findstr ssquant   # Windows
  2. 如果没有找到,重新安装:

    # 从源码安装(在项目目录下执行)
    pip install -e .
  3. 验证安装成功:

    python -c "from ssquant.api.strategy_api import StrategyAPI; print('ssquant 导入成功!')"

2. 配置账户

安装完成后,需要配置相关账户信息。编辑 ssquant/config/trading_config.py

📊 数据API配置(回测必需)

框架使用松鼠俱乐部会员远程数据库,会员填入账号密码后,回测和实盘自动预拉取数据到本地:

# ========== 数据API认证 (松鼠俱乐部会员) ==========
API_USERNAME = "你的会员账号"
API_PASSWORD = "你的会员密码"

💡 非会员用户

  • 可自行修改远程服务器地址
  • 或参考 examples/A_工具_导入数据库DB示例.py 导入本地数据

🔐 交易账户配置(模拟/实盘)

# SIMNOW账户(模拟交易)
ACCOUNTS = {
    'simnow_default': {
        'investor_id': '你的SIMNOW账号',
        'password': '你的密码',
        'server_name': '电信1',  # 电信1/电信2/移动/TEST
        # ...
    },
    
    # 实盘账户
    'real_default': {
        'broker_id': '期货公司代码',
        'investor_id': '资金账号',
        'password': '密码',
        'md_server': 'tcp://xxx:port',
        'td_server': 'tcp://xxx:port',
        'app_id': 'AppID',
        'auth_code': '授权码',
        # ...
    },
}

3. 编写策略

from ssquant.api.strategy_api import StrategyAPI
from ssquant.backtest.unified_runner import UnifiedStrategyRunner, RunMode
from ssquant.config.trading_config import get_config

def my_strategy(api: StrategyAPI):
    """双均线策略"""
    close = api.get_close()
    
    if len(close) < 20:
        return
    
    ma5 = close.rolling(5).mean()
    ma20 = close.rolling(20).mean()
    pos = api.get_pos()
    
    # 金叉做多
    if ma5.iloc[-2] <= ma20.iloc[-2] and ma5.iloc[-1] > ma20.iloc[-1]:
        if pos <= 0:
            if pos < 0:
                api.buycover(order_type='next_bar_open')
            api.buy(volume=1, order_type='next_bar_open')
    
    # 死叉做空
    elif ma5.iloc[-2] >= ma20.iloc[-2] and ma5.iloc[-1] < ma20.iloc[-1]:
        if pos >= 0:
            if pos > 0:
                api.sell(order_type='next_bar_open')
            api.sellshort(volume=1, order_type='next_bar_open')

if __name__ == "__main__":
    # 回测配置
    config = get_config(
        mode=RunMode.BACKTEST,
        symbol='rb888',
        start_date='2025-01-01',
        end_date='2025-11-30',
        kline_period='1h',
        price_tick=1.0,
        contract_multiplier=10,
    )
    
    # 运行
    runner = UnifiedStrategyRunner(mode=RunMode.BACKTEST)
    runner.set_config(config)
    results = runner.run(strategy=my_strategy)

4. 切换模式只需改配置

# ===== 回测模式 =====
config = get_config(
    mode=RunMode.BACKTEST,
    symbol='rb888',
    start_date='2025-01-01',
    end_date='2025-11-30',
    kline_period='1h',
)

# ===== SIMNOW模拟 =====
config = get_config(
    mode=RunMode.SIMNOW,
    account='simnow_default',      # 使用预配置的账户
    symbol='rb2601',               # 具体合约月份
    kline_period='1m',
)

# ===== 实盘交易 =====
config = get_config(
    mode=RunMode.REAL_TRADING,
    account='real_default',        # 使用预配置的账户
    symbol='rb2601',
    kline_period='1m',
)

策略代码完全不用改!


📚 文档导航

文档 说明 适合
用户手册.md 📖 完整使用教程 新手必读
API参考手册.md 📚 详细API说明 开发查询
文档导航.md 📑 所有文档索引 查找文档

🎓 示例策略

所有示例在 examples/ 目录(共19个):

工具类 (A_开头)

文件 说明
A_工具_导入数据库DB示例.py 数据导入数据库
A_工具_数据库管理_查看与删除.py 数据库管理
A_撤单重发示例.py 订单撤单重发机制
A_穿透式测试脚本.py CTP穿透式认证测试

策略类 (B_开头)

文件 说明
B_双均线策略.py ⭐ 经典均线交叉,入门推荐
B_海龟交易策略.py 唐奇安通道突破
B_十大经典策略之Aberration.py 布林带突破
B_日内交易策略.py 日内交易
B_网格交易策略.py 网格交易
B_强弱截面轮动策略.py 多品种强弱轮动
B_跨周期过滤策略.py 多周期信号过滤
B_跨品种套利策略.py 品种间价差套利
B_跨期套利策略.py 同品种跨期套利
B_多品种多周期交易策略.py 多品种多周期
B_多品种多周期交易策略_参数优化.py 参数优化示例
B_机器学习策略_随机森林.py ML机器学习预测

高级类 (C_开头)

文件 说明
C_期权交易策略.py 期权交易
C_期货期权组合策略.py 期货期权组合
C_纯Tick高频交易策略.py TICK流高频交易

🤖 AI-Agent 智能助手

项目内置 AI 量化策略编写助手,帮助你快速生成、调试和优化交易策略。

功能特性

  • 💬 智能对话 - 用自然语言描述策略需求,AI 自动生成代码
  • 📝 代码生成 - 一键生成符合 ssquant 框架规范的策略代码
  • 🔧 一键回测 - 直接运行策略,实时查看回测输出和报告
  • 🔄 自动迭代 - AUTO模式下 AI 自动分析报告并优化策略

使用方法

⚠️ 重要提示

  • AI-Agent 不包含在 pip install ssquant,需要 clone 仓库使用
  • ai_agent 目录必须位于项目根目录下,依赖 ssquant 框架运行
# 1. 克隆仓库
git clone https://github.com/songshuquant/ssquant.git
cd ssquant

# 2. 确保目录结构正确
# ssquant/          ← 项目根目录
# ├── ai_agent/     ← AI Agent
# ├── ssquant/      ← 核心框架(必需)
# └── examples/     ← 示例策略

# 3. 进入 ai_agent 目录并安装依赖
cd ai_agent
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 4. 启动服务
python app.py

# 5. 打开浏览器访问 http://localhost:5000
# 6. 点击右上角 ⚙️ 配置 AI 模型 API Key

详细使用说明请查看 ai_agent/README.md


🏗️ 项目结构

ssquant-main/                   # 📁 项目根目录
├── ssquant/                    # 核心框架
│   ├── api/                    # 策略API
│   │   └── strategy_api.py     # 核心API类
│   ├── backtest/               # 回测引擎
│   │   ├── unified_runner.py   # 统一运行器
│   │   ├── backtest_core.py    # 回测核心
│   │   └── live_trading_adapter.py  # 实盘适配器
│   ├── config/                 # 配置管理
│   │   └── trading_config.py   # 配置生成(账户配置在此)
│   ├── data/                   # 数据管理
│   │   ├── api_data_fetcher.py # API数据获取
│   │   └── local_data_loader.py # 本地数据加载
│   ├── ctp/                    # CTP二进制文件
│   │   ├── py39/ ~ py314/      # 各Python版本的CTP文件
│   │   └── loader.py           # CTP加载器
│   ├── pyctp/                  # CTP封装
│   │   ├── simnow_client.py    # SIMNOW客户端
│   │   └── real_trading_client.py  # 实盘客户端
│   └── indicators/             # 技术指标
│       └── tech_indicators.py
│
├── ai_agent/                   # 🤖 AI智能助手(独立工具)
│   ├── app.py                  # Flask Web应用
│   ├── templates/index.html    # 前端界面
│   ├── settings.json           # 配置文件
│   ├── requirements.txt        # 依赖清单
│   └── README.md               # 使用说明
│
├── examples/                   # 📚 策略示例(19个)
├── backtest_results/           # 📊 回测报告输出
├── backtest_logs/              # 📝 回测日志
└── data_cache/                 # 💾 数据缓存

💡 核心API

数据获取

api.get_close()      # 收盘价序列
api.get_open()       # 开盘价序列
api.get_high()       # 最高价序列
api.get_low()        # 最低价序列
api.get_volume()     # 成交量序列
api.get_klines()     # 完整K线DataFrame
api.get_tick()       # 当前TICK数据(实盘)

持仓查询

api.get_pos()        # 净持仓(正=多,负=空)
api.get_long_pos()   # 多头持仓
api.get_short_pos()  # 空头持仓
api.get_position_detail()  # 详细持仓(今昨仓)

交易操作

api.buy(volume=1)         # 买入开仓
api.sell()                # 卖出平仓
api.sellshort(volume=1)   # 卖出开仓
api.buycover()            # 买入平仓
api.close_all()           # 全部平仓
api.reverse_pos()         # 反手

多数据源

# 访问第2个数据源(index=1)
close = api.get_close(index=1)
api.buy(volume=1, index=1)

详见 API参考手册.md


🔧 系统要求

  • Python: 3.9 ~ 3.14
  • 系统: Windows 10+(⚠️ 目前仅支持 Windows,Linux 版本待更新)
  • 内存: 4GB+
  • 网络: 稳定连接(实盘/SIMNOW)

CTP版本支持

框架内置 CTP 6.7.7 ~ 6.7.10 版本,位于 ssquant/ctp/pyXXX/ 目录:

Python版本 目录 状态
3.9 py39/ ✅ 已包含
3.10 py310/ ✅ 已包含
3.11 py311/ ✅ 已包含
3.12 py312/ ✅ 已包含
3.13 py313/ ✅ 已包含
3.14 py314/ ✅ 已包含

⚠️ 风险提示

本框架仅供学习和研究使用。期货交易有风险,入市需谨慎。

  • ⚠️ 请先在SIMNOW充分测试(至少1周)
  • ⚠️ 实盘前用小资金验证
  • ⚠️ 做好风险管理和止损
  • ⚠️ 不要使用高杠杆

📖 快速链接


📝 更新日志

v0.4.0 (2026-01) 🎯 合约参数自动获取

更新项 改进内容 效果
📦 合约信息服务 新增 contract_info.py 自动获取合约参数 无需手动填写乘数、跳动、保证金率
⚙️ 配置升级 get_config() 新增 auto_params 参数 只需合约代码,其他自动获取
💰 账户查询 新增 api.get_balance() 等账户方法 回测/实盘统一查询接口
🔧 数据库优化 线程安全写入 + 快速追加 K线 多线程并发稳定性提升
🔄 实盘适配器 K线聚合逻辑修复 + 代码重构 历史数据预加载后状态一致性

详细更新内容请查看 更新日志_v0.4.0.md

v0.3.9 (2026-01) 🚀 重大升级

本次更新涵盖回测引擎优化报告系统重构AI智能助手三大核心模块:

更新项 改进内容 效果
🤖 AI-Agent 新增 AI 量化策略编写助手 自然语言生成策略代码
数据对齐函数 完善 align_data 多数据源时间对齐机制 多周期/多品种策略数据同步
数据窗口控制 新增 lookback_bars 滑动窗口参数 内存占用降低 90%+
回测速度提升 修复数据累积导致的性能下降问题 速度稳定,不再逐步下降
报告生成速度 Plotly 替换 matplotlib 生成速度提升 5-10 倍
报告系统重制 全新交互式 HTML 报告 支持缩放、拖拽、多图对比

详细更新内容请查看 更新日志_2026-01-06.md

v0.3.7 (2025-12)

  • 🔄 移除构建脚本和冗余文件
  • ✅ 修复 CTP 登录报错乱码问题
  • ✅ 优化项目结构

v0.3.6 (2025-12)

  • ✅ 修复 CTP 登录报错乱码问题 (Windows下GBK/GB18030解码)
  • ✅ 优化 SIMNOW 和实盘客户端的错误信息显示

v0.3.0 (2025-12)

  • ✅ 完整的TICK流双驱动模式
  • ✅ 多品种多周期支持
  • ✅ 订单撤单重发机制
  • ✅ 实时回调系统(on_trade/on_order/on_cancel)
  • ✅ 动态price_tick和offset_ticks
  • ✅ 统一的API接口
  • ✅ 19个策略示例

开始你的量化交易之旅! 🚀

查看 用户手册.md 了解详细使用方法。