# hyperliquid_trade_bot

**Repository Path**: xpp/hyperliquid_trade_bot

## Basic Information

- **Project Name**: hyperliquid_trade_bot
- **Description**: hyperliquid_trade_bot
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-20
- **Last Updated**: 2025-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hyperliquid Trading Bot - Hummingbot Framework

基于 Hummingbot 框架开发的 Hyperliquid 现货和永续合约自动化交易策略。

## 项目概述

本项目使用 Hummingbot 开源框架为 Hyperliquid 交易所开发了专用的连接器和交易策略，支持：

- **现货交易**：支持 Hyperliquid 现货市场交易
- **永续合约交易**：支持 Hyperliquid 永续合约交易
- **网格交易策略**：自动化网格交易策略
- **资金费率套利策略**：现货与永续合约之间的资金费率套利

## 项目结构

```
hyperliquid_trade_bot/
├── config/                     # 配置文件目录
│   ├── settings.py             # 主配置文件
│   └── api_config.py           # API配置文件
├── connectors/                 # Hummingbot连接器
│   └── hyperliquid/
│       ├── hyperliquid_spot_connector.py      # 现货连接器
│       └── hyperliquid_perpetual_connector.py # 永续合约连接器
├── strategies/                 # 交易策略
│   ├── hyperliquid_grid_strategy.py          # 网格交易策略
│   ├── hyperliquid_funding_arbitrage.py      # 资金费率套利策略
│   └── strategy_config.py                    # 策略配置
├── utils/                      # 工具模块
│   ├── hyperliquid_api.py      # Hyperliquid API客户端
│   └── helpers.py              # 通用工具函数
├── main.py                     # 主程序入口
├── requirements.txt            # 依赖包列表
└── README.md                   # 项目说明文档
```

## 功能特性

### 1. Hyperliquid 连接器

- **现货连接器**：实现 Hummingbot 标准接口，支持现货交易
- **永续合约连接器**：实现 Hummingbot 标准接口，支持永续合约交易
- **实时数据**：WebSocket 实时价格和订单簿数据
- **订单管理**：下单、撤单、查询订单状态
- **账户管理**：余额查询、持仓管理

### 2. 交易策略

#### 网格交易策略
- 在指定价格区间内放置买卖网格订单
- 自动调整网格间距和订单数量
- 支持动态重新平衡
- 风险控制和止损机制

#### 资金费率套利策略
- 监控现货与永续合约之间的资金费率
- 自动执行套利交易
- 动态对冲管理
- PnL 跟踪和风险控制

### 3. 风险管理

- **最大回撤控制**：设置最大回撤限制
- **仓位大小管理**：基于风险百分比计算仓位
- **止损止盈**：可配置的止损止盈机制
- **实时监控**：实时监控账户状态和风险指标

## 安装和配置

### 1. 环境要求

- Python 3.8+
- pip 包管理器

### 2. 安装依赖

```bash
cd hyperliquid_trade_bot
pip install -r requirements.txt
```

### 3. 配置设置

#### API 配置

编辑 `config/api_config.py` 文件，添加您的 Hyperliquid API 凭据：

```python
class APIConfig:
    # Hyperliquid API 配置
    HYPERLIQUID_API_KEY = "your_api_key_here"
    HYPERLIQUID_API_SECRET = "your_api_secret_here"
    HYPERLIQUID_TESTNET = True  # 设置为 False 使用主网
```

#### 策略配置

编辑 `config/settings.py` 文件，配置交易策略参数：

```python
class Config:
    # 基本设置
    TRADING_PAIR = "ETH-USD"
    TEST_MODE = True
    
    # 网格交易配置
    GRID_LEVELS = 10
    GRID_SPREAD = 0.01  # 1%
    ORDER_AMOUNT = 0.1
    
    # 资金费率套利配置
    POSITION_SIZE = 1.0
    MIN_FUNDING_RATE = 0.0001  # 0.01%
```

## 使用方法

### 1. 启动交易机器人

```bash
python main.py
```

### 2. 选择交易策略

程序启动后，您可以选择要运行的策略：

- **网格交易策略**：适合震荡市场，通过网格订单获取价差收益
- **资金费率套利策略**：利用现货与永续合约之间的资金费率差异获利

### 3. 监控和管理

- 程序会实时显示策略状态、持仓信息和 PnL
- 可以通过日志文件查看详细的交易记录
- 支持动态调整策略参数

## 策略详解

### 网格交易策略

网格交易是一种在价格区间内放置多个买卖订单的策略：

1. **初始化**：根据当前价格和配置参数计算网格价格
2. **下单**：在网格价格上放置限价订单
3. **监控**：监控订单成交情况
4. **重新平衡**：当订单成交后，重新计算并放置新的网格订单
5. **风险控制**：监控总持仓和风险指标

**适用场景**：
- 震荡市场
- 流动性充足的交易对
- 价格在一定区间内波动

### 资金费率套利策略

资金费率套利利用现货与永续合约之间的资金费率差异：

1. **监控资金费率**：实时监控永续合约的资金费率
2. **判断机会**：当资金费率超过阈值时触发套利
3. **建立对冲**：同时在现货和永续合约建立相反头寸
4. **收取费率**：持有头寸收取资金费率
5. **平仓管理**：根据市场情况和风险控制平仓

**适用场景**：
- 资金费率较高的市场环境
- 现货与永续合约价差稳定
- 有足够资金进行对冲

## 风险提示

⚠️ **重要风险提示**：

1. **市场风险**：加密货币市场波动剧烈，可能导致重大损失
2. **技术风险**：程序可能存在 bug 或网络连接问题
3. **流动性风险**：市场流动性不足可能影响策略执行
4. **资金费率风险**：资金费率可能快速变化，影响套利收益

**建议**：
- 首先在测试网环境中测试策略
- 使用小额资金开始交易
- 设置合理的风险控制参数
- 定期监控和调整策略

## 开发和扩展

### 添加新策略

1. 在 `strategies/` 目录下创建新的策略文件
2. 继承 `ScriptStrategyBase` 类
3. 实现必要的方法：`on_tick()`, `did_fill_order()` 等
4. 在 `main.py` 中注册新策略

### 自定义连接器

1. 在 `connectors/hyperliquid/` 目录下修改连接器
2. 实现 Hummingbot 标准接口
3. 添加特定的 API 调用和数据处理

### 工具函数

`utils/` 目录包含了各种工具函数：
- `hyperliquid_api.py`：Hyperliquid API 客户端
- `helpers.py`：价格计算、风险管理等工具

## 技术支持

如果您在使用过程中遇到问题：

1. 检查配置文件是否正确
2. 确认 API 凭据有效
3. 查看日志文件获取错误信息
4. 参考 Hummingbot 官方文档

## 免责声明

本项目仅供学习和研究使用。使用本项目进行实际交易的风险由用户自行承担。开发者不对任何交易损失负责。

请在充分了解风险的情况下使用本项目，并建议先在测试环境中验证策略的有效性。

## 许可证

本项目基于 Apache 2.0 许可证开源，与 Hummingbot 框架保持一致。