From e06af100b0cb5c5f83abd612c4072a157ad4f983 Mon Sep 17 00:00:00 2001 From: Jett Wang Date: Tue, 28 Oct 2025 11:54:02 +0800 Subject: [PATCH 1/2] docs: add mkdocs documentation site --- .github/workflows/docs.yml | 41 ++ .gitignore | 6 +- API_DOCS_COMPLETE.md | 265 +++++++++ Makefile | 39 ++ Makefile.docs | 30 + docs-requirements.txt | 5 + docs/README.md | 178 ++++++ docs/api/error-handling.md | 595 +++++++++++++++++++ docs/api/response-format.md | 546 ++++++++++++++++++ docs/api/tools-reference.md | 784 ++++++++++++++++++++++++++ docs/changelog.md | 17 + docs/developers/contributing.md | 107 ++++ docs/getting-started/configuration.md | 254 +++++++++ docs/getting-started/installation.md | 171 ++++++ docs/getting-started/quick-start.md | 238 ++++++++ docs/guides/account-management.md | 616 ++++++++++++++++++++ docs/guides/mcp-integration.md | 519 +++++++++++++++++ docs/guides/trading-tools.md | 571 +++++++++++++++++++ docs/index.md | 147 +++++ docs/troubleshooting.md | 337 +++++++++++ mkdocs.yml | 106 ++++ scripts/setup_docs.sh | 42 ++ 22 files changed, 5613 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/docs.yml create mode 100644 API_DOCS_COMPLETE.md create mode 100644 Makefile.docs create mode 100644 docs-requirements.txt create mode 100644 docs/README.md create mode 100644 docs/api/error-handling.md create mode 100644 docs/api/response-format.md create mode 100644 docs/api/tools-reference.md create mode 100644 docs/changelog.md create mode 100644 docs/developers/contributing.md create mode 100644 docs/getting-started/configuration.md create mode 100644 docs/getting-started/installation.md create mode 100644 docs/getting-started/quick-start.md create mode 100644 docs/guides/account-management.md create mode 100644 docs/guides/mcp-integration.md create mode 100644 docs/guides/trading-tools.md create mode 100644 docs/index.md create mode 100644 docs/troubleshooting.md create mode 100644 mkdocs.yml create mode 100755 scripts/setup_docs.sh diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..c8869e0 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,41 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + - '.github/workflows/docs.yml' + workflow_dispatch: + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: 3.x + + - name: Cache dependencies + uses: actions/cache@v4 + with: + key: ${{ github.ref }} + path: .cache + + - name: Install dependencies + run: | + pip install -r docs-requirements.txt + + - name: Build and deploy + run: | + mkdocs gh-deploy --force diff --git a/.gitignore b/.gitignore index 16c76aa..ef7de21 100644 --- a/.gitignore +++ b/.gitignore @@ -44,4 +44,8 @@ env/ .DS_Store Thumbs.db -test.py \ No newline at end of file +# MkDocs +site/ +.cache/ + +test.py diff --git a/API_DOCS_COMPLETE.md b/API_DOCS_COMPLETE.md new file mode 100644 index 0000000..f046daa --- /dev/null +++ b/API_DOCS_COMPLETE.md @@ -0,0 +1,265 @@ +# API 文档已补充完成！ ✅ + +## 新增的 API 文档 + +我已经为你创建了完整的 API 参考文档： + +### 1. 工具 API 参考 (`docs/api/tools-reference.md`) ✅ + +**内容**: + +- 📊 **账户管理** (5 个工具) + + - `get_account_balance` - 获取余额 + - `get_open_positions` - 获取仓位 + - `get_open_orders` - 获取订单 + - `get_trade_history` - 交易历史 + - `get_account_summary` - 账户概览 + +- 📈 **交易工具** (4 个工具) + + - `place_limit_order` - 限价单 + - `market_open_position` - 市价开仓 + - `market_close_position` - 市价平仓 + - `place_bracket_order` - 括号订单 + - `close_position` - 关闭仓位 + +- 🎯 **止盈止损管理** (3 个工具) + + - `set_take_profit_stop_loss` - 设置 TP/SL + - `set_take_profit` - 只设置止盈 + - `set_stop_loss` - 只设置止损 + +- 📝 **订单管理** (4 个工具) + + - `cancel_order` - 取消订单 + - `cancel_order_by_client_id` - 按客户端 ID 取消 + - `cancel_all_orders` - 批量取消 + - `modify_order` - 修改订单 + +- 💹 **市场数据** (3 个工具) + + - `get_market_data` - 市场数据 + - `get_orderbook` - 订单簿 + - `get_funding_history` - 资金费率 + +- ⚙️ **账户设置** (2 个工具) + + - `update_leverage` - 更新杠杆 + - `transfer_between_spot_and_perp` - 转账 + +- 🧮 **实用工具** (1 个工具) + - `calculate_token_amount_from_dollars` - 美元转代币 + +**特色**: + +- ✨ 每个工具都有详细的参数说明 +- 📝 完整的代码示例 +- ⚠️ 重要提示和警告框 +- 💡 使用技巧和最佳实践 + +### 2. 返回格式说明 (`docs/api/response-format.md`) ✅ + +**内容**: + +- 标准响应格式（成功/失败） +- 所有工具的返回示例 +- 字段详细说明 +- 最佳实践 + +**包含**: + +- ✅ 账户信息返回格式 +- ✅ 交易操作返回格式 +- ✅ 订单管理返回格式 +- ✅ 市场数据返回格式 +- ✅ 错误响应格式 +- ✅ 字段说明表格 + +### 3. 错误处理指南 (`docs/api/error-handling.md`) ✅ + +**内容**: + +- 6 种错误类型详解 +- 错误处理模式 +- 常见错误场景及解决方案 +- 日志记录和恢复策略 + +**错误类型**: + +1. `VALIDATION_ERROR` - 验证错误 +2. `INSUFFICIENT_BALANCE` - 余额不足 +3. `POSITION_NOT_FOUND` - 仓位未找到 +4. `ORDER_NOT_FOUND` - 订单未找到 +5. `API_ERROR` - API 错误 +6. `INVALID_PRICE/SIZE` - 价格/数量无效 + +**错误处理模式**: + +- 基础错误检查 +- 详细错误处理 +- 异常处理 +- 防御性编程 + +**实用示例**: + +- ✅ 重试机制 +- ✅ 降级策略 +- ✅ 日志记录 +- ✅ 错误恢复 + +## 📁 完整文档结构 + +``` +docs/ +├── index.md ✅ 首页 +├── getting-started/ ✅ 快速开始 +│ ├── installation.md ✅ 安装指南 +│ ├── configuration.md ✅ 配置指南 +│ └── quick-start.md ✅ 快速验证 +├── api/ ✅ API 参考（新增） +│ ├── tools-reference.md ✅ 工具 API 参考 +│ ├── response-format.md ✅ 返回格式 +│ └── error-handling.md ✅ 错误处理 +├── guides/ 🚧 使用指南（待补充） +│ ├── mcp-integration.md 🚧 MCP 集成 +│ ├── trading-tools.md 🚧 交易工具 +│ ├── account-management.md 🚧 账户管理 +│ ├── market-data.md 🚧 市场数据 +│ └── use-cases.md 🚧 常见用例 +├── developers/ 🚧 开发者文档（待补充） +│ ├── architecture.md 🚧 架构设计 +│ ├── testing.md 🚧 测试工具 +│ └── contributing.md 🚧 贡献指南 +├── troubleshooting.md ✅ 故障排除 +└── changelog.md ✅ 更新日志 +``` + +## 🎯 API 文档亮点 + +### 1. 详尽的工具说明 + +每个工具都包含： + +- **参数列表**：类型、默认值、说明 +- **返回示例**：实际的 JSON 响应 +- **代码示例**：Python 调用示例 +- **注意事项**：重要提示和警告 + +### 2. 突出 Size 参数问题 + +特别强调了最容易出错的 `size` 参数： + +!!! warning "重要" +**`size` 参数是代币数量，不是美元金额！** - ✅ `0.1` = 0.1 个 BTC 代币 - ❌ `20.0` ≠ $20 美元 + +### 3. 清晰的错误处理 + +提供了： + +- 所有错误类型的详细说明 +- 实际的错误响应示例 +- 具体的解决方案代码 +- 重试和降级策略 + +### 4. 最佳实践 + +每个章节都包含最佳实践： + +- ✅ 使用前验证 +- ✅ 错误检查 +- ✅ 日志记录 +- ✅ 重试机制 + +## 🔍 快速预览 + +### 工具 API 参考 + +````markdown +### market_open_position + +使用市价单开仓（最优执行）。 + +**参数**: + +- `coin` (str): 交易对 +- `side` (str): "buy" 做多 或 "sell" 做空 +- `size` (float): **代币数量**（不是美元金额！） + +**示例**: +​```python + +# 先计算代币数量 + +calc = calculate_token_amount_from_dollars("BTC", 100.0) + +# 开多仓 + +order = market_open_position("BTC", "buy", calc["token_amount"]) +​``` +```` + +### 错误处理示例 + +```python +result = place_limit_order("BTC", "buy", 0.1, 45000) + +if not result["success"]: + error_code = result.get("error_code") + + if error_code == "INSUFFICIENT_BALANCE": + print("余额不足，请充值或减少订单大小") + elif error_code == "API_ERROR": + print("API 错误，稍后重试") +``` + +## 📊 文档统计 + +- **总页面数**: 10+ 页 +- **API 工具数**: 25+ 个 +- **代码示例**: 50+ 个 +- **错误类型**: 6 种 +- **最佳实践**: 多个章节 + +## 🚀 下一步 + +### 还需要补充的文档： + +1. **使用指南** (`docs/guides/`) + + - MCP 客户端集成教程 + - 交易工具详细使用 + - 账户管理指南 + - 市场数据获取 + - 常见使用场景 + +2. **开发者文档** (`docs/developers/`) + - 架构设计说明 + - 测试工具使用 + - 贡献指南 + +需要我继续补充这些文档吗？ + +## 📖 查看文档 + +```bash +# 本地预览 +make docs-serve + +# 或直接使用 mkdocs +mkdocs serve +``` + +访问 http://127.0.0.1:8000 查看完整文档！ + +--- + +**API 文档已经完整创建！** 🎉 + +现在用户可以查看： + +- ✅ 所有工具的完整 API 参考 +- ✅ 详细的返回格式说明 +- ✅ 全面的错误处理指南 +- ✅ 丰富的代码示例 +- ✅ 最佳实践建议 diff --git a/Makefile b/Makefile index 4bd02fc..712858b 100644 --- a/Makefile +++ b/Makefile @@ -59,6 +59,12 @@ help: @echo " make publish - 发布到 PyPI" @echo " make version - 显示当前版本" @echo "" + @echo "文档:" + @echo " make docs-install - 安装文档依赖" + @echo " make docs-serve - 本地预览文档 ⭐" + @echo " make docs-build - 构建文档" + @echo " make docs-deploy - 部署到 GitHub Pages" + @echo "" @echo "快捷命令:" @echo " make all - clean + build" @echo " make release - clean + build + publish" @@ -280,3 +286,36 @@ full-release: @echo "🎉 发布完成！别忘了：" @echo " git push origin main" @echo " git push origin v$$(grep '^version = ' pyproject.toml | cut -d'"' -f2)" + +# ============================================================================ +# 文档命令 +# ============================================================================ + +# 安装文档依赖 +docs-install: + @echo "📦 安装文档依赖..." + pip install -r docs-requirements.txt + +# 本地预览文档 +docs-serve: + @echo "🌐 启动文档服务器..." + @echo "📖 浏览器访问 http://127.0.0.1:8000" + mkdocs serve + +# 构建文档 +docs-build: + @echo "📚 构建文档..." + mkdocs build + @echo "✅ 文档已构建到 site/ 目录" + +# 部署文档到 GitHub Pages +docs-deploy: + @echo "🚀 部署文档到 GitHub Pages..." + mkdocs gh-deploy --force + @echo "✅ 文档已部署" + +# 清理文档构建 +docs-clean: + @echo "🧹 清理文档构建..." + rm -rf site/ + @echo "✅ 清理完成" diff --git a/Makefile.docs b/Makefile.docs new file mode 100644 index 0000000..9996cec --- /dev/null +++ b/Makefile.docs @@ -0,0 +1,30 @@ +# 构建文档网站 +.PHONY: docs-build +docs-build: + @echo "📚 Building documentation..." + mkdocs build + +# 本地预览文档 +.PHONY: docs-serve +docs-serve: + @echo "🌐 Starting documentation server..." + @echo "📖 Open http://127.0.0.1:8000 in your browser" + mkdocs serve + +# 部署文档到 GitHub Pages +.PHONY: docs-deploy +docs-deploy: + @echo "🚀 Deploying documentation to GitHub Pages..." + mkdocs gh-deploy --force + +# 安装文档依赖 +.PHONY: docs-install +docs-install: + @echo "📦 Installing documentation dependencies..." + pip install -r docs-requirements.txt + +# 清理文档构建 +.PHONY: docs-clean +docs-clean: + @echo "🧹 Cleaning documentation build..." + rm -rf site/ diff --git a/docs-requirements.txt b/docs-requirements.txt new file mode 100644 index 0000000..ee06942 --- /dev/null +++ b/docs-requirements.txt @@ -0,0 +1,5 @@ +# 依赖包 +mkdocs>=1.5.0 +mkdocs-material>=9.5.0 +mkdocs-minify-plugin>=0.8.0 +pymdown-extensions>=10.7 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..48f15f1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,178 @@ +# 文档网站 + +本项目使用 **MkDocs Material** 构建文档网站。 + +## 本地开发 + +### 安装依赖 + +```bash +pip install -r docs-requirements.txt +``` + +### 本地预览 + +```bash +# 启动开发服务器 +mkdocs serve + +# 或使用 Makefile +make -f Makefile.docs docs-serve +``` + +访问 http://127.0.0.1:8000 查看文档。 + +### 构建静态文件 + +```bash +# 构建文档 +mkdocs build + +# 或使用 Makefile +make -f Makefile.docs docs-build +``` + +生成的静态文件位于 `site/` 目录。 + +## 部署 + +### 自动部署 + +推送到 `main` 分支时，GitHub Actions 会自动构建并部署到 GitHub Pages。 + +### 手动部署 + +```bash +# 部署到 GitHub Pages +mkdocs gh-deploy --force + +# 或使用 Makefile +make -f Makefile.docs docs-deploy +``` + +## 文档结构 + +``` +docs/ +├── index.md # 首页 +├── getting-started/ # 快速开始 +│ ├── installation.md # 安装指南 +│ ├── configuration.md # 配置指南 +│ └── quick-start.md # 快速验证 +├── guides/ # 使用指南 +│ ├── mcp-integration.md # MCP 客户端集成 +│ ├── trading-tools.md # 交易工具 +│ ├── account-management.md # 账户管理 +│ ├── market-data.md # 市场数据 +│ └── use-cases.md # 常见用例 +├── api/ # API 参考 +│ ├── tools-reference.md # 工具列表 +│ ├── response-format.md # 返回格式 +│ └── error-handling.md # 错误处理 +├── developers/ # 开发者文档 +│ ├── architecture.md # 架构设计 +│ ├── testing.md # 测试工具 +│ └── contributing.md # 贡献指南 +├── troubleshooting.md # 故障排除 +└── changelog.md # 更新日志 +``` + +## 编写指南 + +### Markdown 扩展 + +MkDocs Material 支持丰富的 Markdown 扩展： + +#### 告示块 + +```markdown +!!! note "标题" +这是一个提示信息 + +!!! warning "警告" +这是一个警告信息 + +!!! danger "危险" +这是一个危险警告 +``` + +#### 代码高亮 + +````markdown +​`python +def hello(): + print("Hello, World!") +​` +```` + +#### 标签页 + +```markdown +=== "Tab 1" +内容 1 + +=== "Tab 2" +内容 2 +``` + +#### 卡片网格 + +```markdown +
+ +- :material-rocket: **快速开始** + + 快速上手指南 + +- :material-book: **文档** + + 完整文档 + +
+``` + +### 文档规范 + +1. **文件命名**：使用小写字母和连字符，如 `quick-start.md` +2. **标题层级**：每个文件只有一个 `#` 标题 +3. **代码示例**：包含完整的代码示例和输出 +4. **链接**：使用相对路径链接其他文档 +5. **图片**：放在 `docs/assets/images/` 目录 + +## 配置 + +主配置文件：`mkdocs.yml` + +### 主题配置 + +```yaml +theme: + name: material + language: zh + palette: + - scheme: default + primary: indigo +``` + +### 导航配置 + +```yaml +nav: + - 首页: index.md + - 快速开始: + - 安装: getting-started/installation.md +``` + +### 插件配置 + +```yaml +plugins: + - search + - minify +``` + +## 相关资源 + +- [MkDocs 官方文档](https://www.mkdocs.org/) +- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) +- [Markdown 扩展](https://squidfunk.github.io/mkdocs-material/reference/) diff --git a/docs/api/error-handling.md b/docs/api/error-handling.md new file mode 100644 index 0000000..736d180 --- /dev/null +++ b/docs/api/error-handling.md @@ -0,0 +1,595 @@ +# 错误处理 + +本页面介绍如何正确处理 HyperLiquid MCP Server 中的错误。 + +## 错误类型 + +### 1. 验证错误 (VALIDATION_ERROR) + +输入参数不符合要求。 + +**常见原因**: + +- 币种符号无效 +- 价格或数量为负数或零 +- 订单方向无效（不是 "buy" 或 "sell"） +- 客户端订单 ID 格式错误 + +**示例**: + +```json +{ + "success": false, + "error": "Invalid coin symbol: INVALID", + "error_code": "VALIDATION_ERROR" +} +``` + +**解决方案**: + +```python +# ❌ 错误 +order = place_limit_order("INVALID", "buy", 1.0, 3000) + +# ✅ 正确 +order = place_limit_order("BTC", "buy", 0.1, 45000) +``` + +--- + +### 2. 余额不足 (INSUFFICIENT_BALANCE) + +账户余额不足以完成操作。 + +**示例**: + +```json +{ + "success": false, + "error": "Insufficient balance to place order", + "error_code": "INSUFFICIENT_BALANCE", + "required": "1000.00", + "available": "500.00" +} +``` + +**解决方案**: + +```python +# 先检查余额 +balance = get_account_balance() +if balance["success"]: + available = float(balance["data"]["withdrawable"]) + + # 只下能承受的订单 + if available >= required_amount: + order = place_limit_order(...) + else: + print(f"余额不足: 需要 ${required_amount}, 可用 ${available}") +``` + +--- + +### 3. 仓位未找到 (POSITION_NOT_FOUND) + +尝试操作不存在的仓位。 + +**示例**: + +```json +{ + "success": false, + "error": "No position found for BTC", + "error_code": "POSITION_NOT_FOUND", + "coin": "BTC" +} +``` + +**解决方案**: + +```python +# 先检查仓位是否存在 +positions = get_open_positions() +if positions["success"]: + btc_position = next( + (p for p in positions["positions"] if p["coin"] == "BTC"), + None + ) + + if btc_position: + # 仓位存在，可以设置 TP/SL + set_take_profit_stop_loss("BTC", tp_price=47000, sl_price=43000) + else: + print("BTC 仓位不存在，请先开仓") +``` + +--- + +### 4. 订单未找到 (ORDER_NOT_FOUND) + +尝试操作不存在的订单。 + +**示例**: + +```json +{ + "success": false, + "error": "Order not found: 123456", + "error_code": "ORDER_NOT_FOUND", + "order_id": 123456 +} +``` + +**解决方案**: + +```python +# 先获取开放订单列表 +orders = get_open_orders() +if orders["success"]: + order_ids = [o["order_id"] for o in orders["orders"]] + + if order_id in order_ids: + cancel_order("BTC", order_id) + else: + print(f"订单 {order_id} 不存在或已完成") +``` + +--- + +### 5. API 错误 (API_ERROR) + +与 HyperLiquid API 通信失败。 + +**常见原因**: + +- 网络连接问题 +- API 限流 +- HyperLiquid 服务问题 +- 认证失败 + +**示例**: + +```json +{ + "success": false, + "error": "API request failed: Rate limit exceeded", + "error_code": "API_ERROR", + "details": "Please wait before making more requests" +} +``` + +**解决方案**: + +```python +import time + +def retry_with_backoff(func, max_retries=3): + """带退避的重试机制""" + for i in range(max_retries): + result = func() + + if result["success"]: + return result + + if result.get("error_code") == "API_ERROR": + if i < max_retries - 1: + wait_time = 2 ** i # 指数退避 + print(f"API 错误，{wait_time} 秒后重试...") + time.sleep(wait_time) + else: + print("达到最大重试次数") + return result + else: + # 其他错误不重试 + return result + + return result + +# 使用重试机制 +result = retry_with_backoff( + lambda: get_market_data("BTC") +) +``` + +--- + +### 6. 价格/数量无效 + +价格或数量不符合要求。 + +**示例**: + +```json +{ + "success": false, + "error": "Price must be greater than 0", + "error_code": "INVALID_PRICE" +} +``` + +**解决方案**: + +```python +# 验证输入 +def validate_trade_params(size, price): + if size <= 0: + raise ValueError("Size must be greater than 0") + if price <= 0: + raise ValueError("Price must be greater than 0") + return True + +try: + validate_trade_params(0.1, 45000) + order = place_limit_order("BTC", "buy", 0.1, 45000) +except ValueError as e: + print(f"参数错误: {e}") +``` + +## 错误处理模式 + +### 模式 1: 基础错误检查 + +最简单的错误处理方式： + +```python +result = place_limit_order("BTC", "buy", 0.1, 45000) + +if result["success"]: + print(f"订单成功: {result['order_id']}") +else: + print(f"订单失败: {result['error']}") +``` + +### 模式 2: 详细错误处理 + +根据错误类型采取不同行动： + +```python +result = place_limit_order("BTC", "buy", 0.1, 45000) + +if not result["success"]: + error_code = result.get("error_code") + error_msg = result.get("error") + + if error_code == "INSUFFICIENT_BALANCE": + print("余额不足，请充值或减少订单大小") + # 可以尝试减少订单大小 + + elif error_code == "VALIDATION_ERROR": + print(f"参数错误: {error_msg}") + # 修正参数 + + elif error_code == "API_ERROR": + print("API 错误，稍后重试") + # 实施重试机制 + + else: + print(f"未知错误: {error_msg}") +``` + +### 模式 3: 异常处理 + +结合 try-except 处理： + +```python +try: + # 获取市场数据 + market_data = get_market_data("BTC") + + if not market_data["success"]: + raise Exception(market_data["error"]) + + current_price = float(market_data["data"]["mark_px"]) + + # 计算代币数量 + calc = calculate_token_amount_from_dollars("BTC", 100.0) + + if not calc["success"]: + raise Exception(calc["error"]) + + token_amount = calc["token_amount"] + + # 下单 + order = market_open_position("BTC", "buy", token_amount) + + if not order["success"]: + raise Exception(order["error"]) + + print(f"订单成功: {order['order_id']}") + +except Exception as e: + print(f"操作失败: {str(e)}") + # 记录日志或通知用户 +``` + +### 模式 4: 防御性编程 + +在操作前进行检查： + +```python +def safe_place_order(coin, side, dollar_amount): + """安全下单函数，包含所有检查""" + + # 1. 检查余额 + balance = get_account_balance() + if not balance["success"]: + return {"success": False, "error": "无法获取余额"} + + available = float(balance["data"]["withdrawable"]) + if available < dollar_amount: + return { + "success": False, + "error": f"余额不足: 需要 ${dollar_amount}, 可用 ${available}" + } + + # 2. 获取当前价格并计算代币数量 + calc = calculate_token_amount_from_dollars(coin, dollar_amount) + if not calc["success"]: + return {"success": False, "error": calc["error"]} + + token_amount = calc["token_amount"] + + # 3. 下单 + order = market_open_position(coin, side, token_amount) + + return order + +# 使用 +result = safe_place_order("BTC", "buy", 100.0) +if result["success"]: + print("订单成功") +else: + print(f"订单失败: {result['error']}") +``` + +## 常见错误场景 + +### 场景 1: Size 参数误用 + +**问题**: 用户想买 $20 的 SOL，但直接传 20.0 作为 size + +```python +# ❌ 错误 - 会尝试买 20 个 SOL（约 $3000）！ +order = market_open_position("SOL", "buy", 20.0) +``` + +**解决方案**: + +```python +# ✅ 正确 - 先计算代币数量 +calc = calculate_token_amount_from_dollars("SOL", 20.0) + +if calc["success"]: + order = market_open_position("SOL", "buy", calc["token_amount"]) +else: + print(f"计算失败: {calc['error']}") +``` + +--- + +### 场景 2: 为不存在的仓位设置 TP/SL + +**问题**: 在没有仓位的情况下设置止盈止损 + +```python +# ❌ 错误 - 如果没有 BTC 仓位会失败 +result = set_take_profit_stop_loss("BTC", tp_price=47000, sl_price=43000) +# 返回: {"success": false, "error": "No position found for BTC"} +``` + +**解决方案**: + +```python +# ✅ 正确 - 先检查仓位 +positions = get_open_positions() + +if positions["success"]: + btc_pos = next((p for p in positions["positions"] if p["coin"] == "BTC"), None) + + if btc_pos: + result = set_take_profit_stop_loss("BTC", tp_price=47000, sl_price=43000) + else: + # 如果要新开仓位 + TP/SL，使用 bracket 订单 + calc = calculate_token_amount_from_dollars("BTC", 100.0) + result = place_bracket_order( + coin="BTC", + side="buy", + size=calc["token_amount"], + entry_price=45000, + take_profit_price=47000, + stop_loss_price=43000 + ) +``` + +--- + +### 场景 3: 客户端订单 ID 格式错误 + +**问题**: 客户端订单 ID 格式不正确 + +```python +# ❌ 错误 - 格式不正确 +order = place_limit_order( + "BTC", "buy", 0.1, 45000, + client_order_id="my-order-123" # 应该是 128 位十六进制 +) +``` + +**解决方案**: + +```python +# ✅ 正确 - 使用正确的格式 +import secrets + +# 生成 128 位十六进制 ID +client_order_id = "0x" + secrets.token_hex(16) + +order = place_limit_order( + "BTC", "buy", 0.1, 45000, + client_order_id=client_order_id +) +``` + +--- + +### 场景 4: API 限流 + +**问题**: 请求过于频繁被限流 + +```python +# ❌ 错误 - 快速连续请求可能触发限流 +for coin in ["BTC", "ETH", "SOL", "AVAX", "MATIC"]: + data = get_market_data(coin) # 可能触发限流 +``` + +**解决方案**: + +```python +# ✅ 正确 - 添加延迟 +import time + +for coin in ["BTC", "ETH", "SOL", "AVAX", "MATIC"]: + data = get_market_data(coin) + + if data["success"]: + print(f"{coin}: {data['data']['mark_px']}") + else: + if data.get("error_code") == "API_ERROR": + print(f"API 错误，等待重试...") + time.sleep(2) + # 重试一次 + data = get_market_data(coin) + + time.sleep(0.5) # 每次请求间隔 500ms +``` + +## 日志记录 + +记录错误以便调试： + +```python +import logging +from datetime import datetime + +# 配置日志 +logging.basicConfig( + filename='trading.log', + level=logging.INFO, + format='%(asctime)s - %(levelname)s - %(message)s' +) + +def log_error(operation, result): + """记录错误信息""" + if not result["success"]: + logging.error( + f"Operation: {operation} | " + f"Error: {result.get('error')} | " + f"Code: {result.get('error_code')}" + ) + +# 使用 +result = place_limit_order("BTC", "buy", 0.1, 45000) +if not result["success"]: + log_error("place_limit_order", result) +``` + +## 错误恢复策略 + +### 自动重试 + +```python +def auto_retry(func, max_attempts=3, delay=1): + """自动重试机制""" + for attempt in range(max_attempts): + result = func() + + if result["success"]: + return result + + error_code = result.get("error_code") + + # 可重试的错误 + if error_code in ["API_ERROR"]: + if attempt < max_attempts - 1: + print(f"重试 {attempt + 1}/{max_attempts}...") + time.sleep(delay * (attempt + 1)) + continue + + # 不可重试的错误 + return result + + return result +``` + +### 降级策略 + +```python +def get_price_with_fallback(coin): + """获取价格，失败时使用缓存""" + result = get_market_data(coin) + + if result["success"]: + price = float(result["data"]["mark_px"]) + # 缓存价格 + cache[coin] = price + return price + else: + # 使用缓存的价格 + if coin in cache: + print(f"使用缓存价格 for {coin}") + return cache[coin] + else: + raise Exception(f"无法获取 {coin} 价格且无缓存") +``` + +## 最佳实践总结 + +1. **始终检查 `success` 字段** + + ```python + if result["success"]: + # 处理成功 + else: + # 处理错误 + ``` + +2. **根据错误代码采取行动** + + ```python + error_code = result.get("error_code") + if error_code == "INSUFFICIENT_BALANCE": + # 特定处理 + ``` + +3. **操作前验证状态** + + ```python + # 检查仓位存在 + # 检查余额充足 + # 验证参数有效 + ``` + +4. **使用重试机制** + + ```python + # API 错误时重试 + # 使用指数退避 + ``` + +5. **记录所有错误** + + ```python + logging.error(f"Error: {result['error']}") + ``` + +6. **提供友好的错误消息** + ```python + if error_code == "INSUFFICIENT_BALANCE": + print("余额不足，请充值后再试") + ``` + +## 相关文档 + +- [工具 API 参考](tools-reference.md) - 完整的工具列表 +- [返回格式](response-format.md) - 返回数据格式说明 +- [故障排除](../troubleshooting.md) - 常见问题解决 diff --git a/docs/api/response-format.md b/docs/api/response-format.md new file mode 100644 index 0000000..4ce8413 --- /dev/null +++ b/docs/api/response-format.md @@ -0,0 +1,546 @@ +# 返回格式 + +所有 HyperLiquid MCP Server 工具都遵循统一的返回格式规范。 + +## 标准响应格式 + +### 成功响应 + +所有成功的 API 调用都会返回包含 `success: true` 的 JSON 对象： + +```json +{ + "success": true, + "data": { + /* 具体数据内容 */ + } +} +``` + +### 错误响应 + +所有失败的 API 调用都会返回包含 `success: false` 的 JSON 对象： + +```json +{ + "success": false, + "error": "错误描述信息", + "error_code": "ERROR_CODE" +} +``` + +## 常见返回类型 + +### 账户信息 + +#### get_account_balance + +```json +{ + "success": true, + "data": { + "account_value": "12345.67", + "total_margin_used": "2345.67", + "total_ntl_pos": "10000.00", + "total_raw_usd": "12345.67", + "withdrawable": "10000.00" + } +} +``` + +#### get_open_positions + +```json +{ + "success": true, + "positions": [ + { + "coin": "BTC", + "szi": "0.1", + "entry_px": "45000.00", + "position_value": "4512.30", + "unrealized_pnl": "12.30", + "return_on_equity": "0.27", + "leverage": "10x", + "liquidation_px": "40500.00" + } + ], + "total_positions": 1 +} +``` + +#### get_open_orders + +```json +{ + "success": true, + "orders": [ + { + "order_id": 123456789, + "coin": "ETH", + "side": "buy", + "limit_px": "3000.00", + "sz": "1.0", + "timestamp": 1704067200000, + "order_type": "Limit" + } + ], + "total_orders": 1 +} +``` + +### 交易操作 + +#### place_limit_order / market_open_position + +```json +{ + "success": true, + "order_result": { + "status": { + "filled": { + "totalSz": "0.1", + "avgPx": "45123.45", + "oid": 123456789 + } + } + }, + "order_id": 123456789, + "filled": true, + "average_price": "45123.45" +} +``` + +#### market_close_position + +```json +{ + "success": true, + "order_result": { + "status": "closed", + "closed_size": "0.1", + "avg_close_price": "45678.90" + }, + "message": "Position closed successfully" +} +``` + +#### place_bracket_order + +```json +{ + "success": true, + "bulk_result": { + "entry_order": { + "order_id": 123456, + "status": "placed" + }, + "take_profit_order": { + "order_id": 123457, + "status": "placed", + "trigger_price": "47000.00" + }, + "stop_loss_order": { + "order_id": 123458, + "status": "placed", + "trigger_price": "43000.00" + } + }, + "message": "Bracket order placed successfully" +} +``` + +### 订单管理 + +#### cancel_order + +```json +{ + "success": true, + "cancelled_order_id": 123456789, + "message": "Order cancelled successfully" +} +``` + +#### cancel_all_orders + +```json +{ + "success": true, + "cancelled_count": 5, + "message": "Cancelled 5 orders for BTC" +} +``` + +或（全部取消）： + +```json +{ + "success": true, + "cancelled_count": 12, + "message": "Cancelled all 12 orders" +} +``` + +#### modify_order + +```json +{ + "success": true, + "order_result": { + "order_id": 123456789, + "new_size": "2.0", + "new_price": "3100.00", + "status": "modified" + }, + "message": "Order modified successfully" +} +``` + +### 市场数据 + +#### get_market_data + +```json +{ + "success": true, + "data": { + "coin": "BTC", + "mark_px": "45123.45", + "mid_px": "45122.50", + "premium": "0.0001", + "funding": "0.0001", + "open_interest": "123456.78", + "prev_day_px": "44500.00", + "day_ntl_vlm": "1234567890.00" + } +} +``` + +#### get_orderbook + +```json +{ + "success": true, + "orderbook": { + "coin": "BTC", + "time": 1704067200000, + "levels": [ + [ + { + "px": "45125.00", + "sz": "1.5", + "n": 3 + }, + { + "px": "45120.00", + "sz": "2.0", + "n": 5 + } + ], + [ + { + "px": "45115.00", + "sz": "1.2", + "n": 2 + }, + { + "px": "45110.00", + "sz": "1.8", + "n": 4 + } + ] + ] + } +} +``` + +#### get_funding_history + +```json +{ + "success": true, + "funding_history": [ + { + "coin": "BTC", + "fundingRate": "0.0001", + "premium": "0.00005", + "time": 1704067200000 + } + ], + "days": 7 +} +``` + +### 账户设置 + +#### update_leverage + +```json +{ + "success": true, + "leverage": 10, + "leverage_type": "cross", + "coin": "BTC", + "message": "Leverage updated to 10x cross margin" +} +``` + +#### transfer_between_spot_and_perp + +```json +{ + "success": true, + "amount": 1000.0, + "from": "spot", + "to": "perp", + "message": "Transferred $1000.00 from spot to perpetual account" +} +``` + +### 止盈止损 + +#### set_take_profit_stop_loss + +```json +{ + "success": true, + "tp_order": { + "order_id": 123457, + "trigger_price": "47000.00", + "size": "0.1" + }, + "sl_order": { + "order_id": 123458, + "trigger_price": "43000.00", + "size": "0.1" + }, + "message": "TP/SL orders placed successfully (OCO group)" +} +``` + +### 实用工具 + +#### calculate_token_amount_from_dollars + +```json +{ + "success": true, + "coin": "SOL", + "dollar_amount": 20.0, + "current_price": 150.0, + "token_amount": 0.133333, + "calculation": "$20.00 ÷ $150.00 = 0.133333 SOL" +} +``` + +#### get_account_summary + +```json +{ + "success": true, + "summary": { + "balance": { + "account_value": "12345.67", + "withdrawable": "10000.00" + }, + "positions": [ + { + "coin": "BTC", + "szi": "0.1", + "unrealized_pnl": "12.30" + } + ], + "orders": [ + { + "order_id": 123456, + "coin": "ETH", + "side": "buy" + } + ], + "total_positions": 1, + "total_orders": 1 + } +} +``` + +## 错误响应格式 + +### 验证错误 + +```json +{ + "success": false, + "error": "Invalid coin symbol: INVALID", + "error_code": "VALIDATION_ERROR" +} +``` + +### 余额不足 + +```json +{ + "success": false, + "error": "Insufficient balance to place order", + "error_code": "INSUFFICIENT_BALANCE", + "required": "1000.00", + "available": "500.00" +} +``` + +### 仓位未找到 + +```json +{ + "success": false, + "error": "No position found for BTC", + "error_code": "POSITION_NOT_FOUND", + "coin": "BTC" +} +``` + +### 订单未找到 + +```json +{ + "success": false, + "error": "Order not found: 123456", + "error_code": "ORDER_NOT_FOUND", + "order_id": 123456 +} +``` + +### API 错误 + +```json +{ + "success": false, + "error": "API request failed: Rate limit exceeded", + "error_code": "API_ERROR", + "details": "Please wait before making more requests" +} +``` + +## 错误代码列表 + +| 错误代码 | 说明 | 解决方案 | +| ---------------------- | ---------------- | -------------------------------------- | +| `VALIDATION_ERROR` | 输入参数验证失败 | 检查参数格式和取值范围 | +| `INSUFFICIENT_BALANCE` | 账户余额不足 | 充值或减少订单大小 | +| `POSITION_NOT_FOUND` | 未找到仓位 | 确认仓位存在后再操作 | +| `ORDER_NOT_FOUND` | 未找到订单 | 检查订单 ID 是否正确 | +| `API_ERROR` | API 调用失败 | 查看详细错误信息，可能是网络或限流问题 | +| `INVALID_PRICE` | 价格无效 | 价格必须大于 0 | +| `INVALID_SIZE` | 数量无效 | 数量必须大于 0 | +| `RATE_LIMIT_EXCEEDED` | 超过 API 限流 | 降低请求频率 | + +## 字段说明 + +### 通用字段 + +| 字段 | 类型 | 说明 | +| ------------ | ------- | -------------------- | +| `success` | boolean | 是否成功 | +| `error` | string | 错误描述（仅失败时） | +| `error_code` | string | 错误代码（仅失败时） | +| `message` | string | 操作消息 | + +### 仓位字段 + +| 字段 | 类型 | 说明 | +| ------------------ | ------ | ------------------------------ | +| `coin` | string | 交易对 | +| `szi` | string | 仓位大小（正数为多，负数为空） | +| `entry_px` | string | 开仓均价 | +| `position_value` | string | 仓位价值 | +| `unrealized_pnl` | string | 未实现盈亏 | +| `return_on_equity` | string | 回报率 | +| `leverage` | string | 杠杆倍数 | +| `liquidation_px` | string | 强平价格 | + +### 订单字段 + +| 字段 | 类型 | 说明 | +| ------------ | ------- | -------------------- | +| `order_id` | integer | 订单 ID | +| `coin` | string | 交易对 | +| `side` | string | 订单方向（buy/sell） | +| `limit_px` | string | 限价价格 | +| `sz` | string | 订单大小 | +| `timestamp` | integer | 时间戳（毫秒） | +| `order_type` | string | 订单类型 | + +### 成交字段 + +| 字段 | 类型 | 说明 | +| --------- | ------- | -------- | +| `totalSz` | string | 成交总量 | +| `avgPx` | string | 成交均价 | +| `oid` | integer | 订单 ID | + +## 最佳实践 + +### 1. 始终检查 success 字段 + +```python +result = get_account_balance() +if result["success"]: + balance = result["data"] + print(f"余额: {balance['account_value']}") +else: + print(f"错误: {result['error']}") +``` + +### 2. 处理不同的返回结构 + +不同的工具可能使用不同的数据键： + +```python +# 账户数据使用 "data" +balance = get_account_balance() +if balance["success"]: + data = balance["data"] + +# 订单结果使用 "order_result" +order = place_limit_order(...) +if order["success"]: + result = order["order_result"] + +# 列表数据使用特定键名 +positions = get_open_positions() +if positions["success"]: + pos_list = positions["positions"] +``` + +### 3. 错误处理 + +```python +try: + result = market_open_position("BTC", "buy", 0.1) + if not result["success"]: + error_code = result.get("error_code") + if error_code == "INSUFFICIENT_BALANCE": + print("余额不足，请充值") + elif error_code == "VALIDATION_ERROR": + print(f"参数错误: {result['error']}") + else: + print(f"操作失败: {result['error']}") +except Exception as e: + print(f"异常: {str(e)}") +``` + +### 4. 提取关键信息 + +```python +# 获取订单 ID +order = place_limit_order("ETH", "buy", 1.0, 3000) +if order["success"]: + order_id = order.get("order_id") or order["order_result"]["status"]["filled"]["oid"] + print(f"订单 ID: {order_id}") +``` + +## 相关文档 + +- [工具 API 参考](tools-reference.md) - 完整的工具列表 +- [错误处理](error-handling.md) - 错误处理最佳实践 +- [故障排除](../troubleshooting.md) - 常见问题解决 diff --git a/docs/api/tools-reference.md b/docs/api/tools-reference.md new file mode 100644 index 0000000..af97ad9 --- /dev/null +++ b/docs/api/tools-reference.md @@ -0,0 +1,784 @@ +# 工具 API 参考 + +本页面列出了 HyperLiquid MCP Server 提供的所有工具及其详细说明。 + +## 📊 账户管理 + +### get_account_balance + +获取账户余额和保证金信息。 + +**参数**: 无 + +**返回**: + +```json +{ + "success": true, + "data": { + "total_value": "1234.56", + "available_balance": "1000.00", + "margin_used": "234.56", + ... + } +} +``` + +**示例**: + +```python +balance = get_account_balance() +``` + +--- + +### get_open_positions + +获取所有开仓及盈亏信息。 + +**参数**: 无 + +**返回**: + +```json +{ + "success": true, + "positions": [ + { + "coin": "BTC", + "size": "0.1", + "entry_price": "45000", + "unrealized_pnl": "250.00", + ... + } + ], + "total_positions": 1 +} +``` + +**示例**: + +```python +positions = get_open_positions() +``` + +--- + +### get_open_orders + +获取所有未成交订单。 + +**参数**: 无 + +**返回**: + +```json +{ + "success": true, + "orders": [ + { + "order_id": 123456, + "coin": "ETH", + "side": "buy", + "size": "1.0", + "price": "3000", + ... + } + ], + "total_orders": 1 +} +``` + +--- + +### get_trade_history + +获取账户交易历史。 + +**参数**: + +- `days` (int, 可选): 回溯天数，默认 7 天 + +**返回**: + +```json +{ + "success": true, + "trades": [ + { + "time": "2024-01-01T12:00:00Z", + "coin": "BTC", + "side": "buy", + "size": "0.1", + "price": "45000", + ... + } + ] +} +``` + +**示例**: + +```python +# 获取最近 7 天的交易 +history = get_trade_history() + +# 获取最近 30 天的交易 +history = get_trade_history(days=30) +``` + +--- + +### get_account_summary + +获取账户综合概览（余额 + 仓位 + 订单）。 + +**参数**: 无 + +**返回**: + +```json +{ + "success": true, + "summary": { + "balance": {...}, + "positions": [...], + "orders": [...], + "total_positions": 1, + "total_orders": 2 + } +} +``` + +## 📈 交易工具 + +### place_limit_order + +下限价订单（开仓或平仓）。 + +**参数**: + +- `coin` (str): 交易对，如 "BTC"、"ETH" +- `side` (str): 订单方向，"buy" 或 "sell" +- `size` (float): **代币数量**（不是美元金额！） +- `price` (float): 限价价格 +- `reduce_only` (bool, 可选): 是否只减仓，默认 false +- `client_order_id` (str, 可选): 客户端订单 ID（128 位十六进制） + +**返回**: + +```json +{ + "success": true, + "order_result": { + "order_id": 123456, + "status": "placed", + ... + } +} +``` + +**示例**: + +```python +# ❌ 错误：size 不是美元金额 +order = place_limit_order("SOL", "buy", 20.0, 150.0) # 会买 20 个 SOL！ + +# ✅ 正确：先计算代币数量 +calc = calculate_token_amount_from_dollars("SOL", 20.0) # $20 +order = place_limit_order("SOL", "buy", calc["token_amount"], 150.0) +``` + +!!! warning "重要提示" +`size` 参数是**代币数量**，不是美元金额！ - `0.1` 表示 0.1 个 BTC/ETH/SOL 代币 - 如需按美元金额下单，请先使用 `calculate_token_amount_from_dollars()` 转换 + +--- + +### market_open_position + +使用市价单开仓（最优执行）。 + +**参数**: + +- `coin` (str): 交易对 +- `side` (str): "buy" 做多 或 "sell" 做空 +- `size` (float): **代币数量**（不是美元金额！） +- `client_order_id` (str, 可选): 客户端订单 ID + +**返回**: + +```json +{ + "success": true, + "order_result": { + "status": "filled", + "avg_price": "45123.45", + ... + } +} +``` + +**示例**: + +```python +# 先计算代币数量 +calc = calculate_token_amount_from_dollars("BTC", 100.0) # $100 worth + +# 开多仓 +order = market_open_position("BTC", "buy", calc["token_amount"]) + +# 开空仓 +order = market_open_position("BTC", "sell", calc["token_amount"]) +``` + +--- + +### market_close_position + +使用市价单平仓（关闭所有仓位）。 + +**参数**: + +- `coin` (str): 交易对 +- `client_order_id` (str, 可选): 客户端订单 ID + +**返回**: + +```json +{ + "success": true, + "order_result": { + "status": "closed", + "closed_size": "0.1", + ... + } +} +``` + +**示例**: + +```python +# 关闭 BTC 的所有仓位 +result = market_close_position("BTC") +``` + +!!! note "说明" +此方法会关闭指定币种的**所有仓位**，HyperLiquid 会自动确定正确的方向和数量。 + +--- + +### place_bracket_order + +下括号订单（入场 + 止盈 + 止损一体）。 + +**参数**: + +- `coin` (str): 交易对 +- `side` (str): "buy" 或 "sell" +- `size` (float): **代币数量** +- `entry_price` (float): 入场价格 +- `take_profit_price` (float): 止盈价格 +- `stop_loss_price` (float): 止损价格 +- `client_order_id` (str, 可选): 客户端订单 ID + +**返回**: + +```json +{ + "success": true, + "bulk_result": { + "entry_order": {...}, + "take_profit_order": {...}, + "stop_loss_order": {...} + } +} +``` + +**示例**: + +```python +# 计算代币数量 +calc = calculate_token_amount_from_dollars("ETH", 200.0) # $200 + +# 下括号订单：入场 $3000，止盈 $3200，止损 $2900 +order = place_bracket_order( + coin="ETH", + side="buy", + size=calc["token_amount"], + entry_price=3000, + take_profit_price=3200, + stop_loss_price=2900 +) +``` + +!!! tip "使用场景" +适合**新开仓位**，一次性设置入场、止盈、止损。 + + 止盈止损订单使用 OCO（一取消另一个）行为。 + +--- + +### close_position + +关闭仓位（全部或部分）。 + +**参数**: + +- `coin` (str): 交易对 +- `percentage` (float, 可选): 平仓百分比，默认 100.0（全部） + +**返回**: + +```json +{ + "success": true, + "closed_percentage": 100.0, + "order_result": {...} +} +``` + +**示例**: + +```python +# 全部平仓 +close_position("BTC") + +# 平仓 50% +close_position("BTC", percentage=50.0) +``` + +## 🎯 止盈止损管理 + +### set_take_profit_stop_loss + +为**现有仓位**设置止盈止损（OCO 订单）。 + +**参数**: + +- `coin` (str): 交易对（必须有现有仓位） +- `take_profit_price` (float, 可选): 止盈价格 +- `stop_loss_price` (float, 可选): 止损价格 +- `position_size` (float, 可选): 仓位大小（自动检测） + +**返回**: + +```json +{ + "success": true, + "tp_order": {...}, + "sl_order": {...} +} +``` + +**示例**: + +```python +# 为现有 BTC 仓位设置止盈止损 +set_take_profit_stop_loss( + coin="BTC", + take_profit_price=47000, + stop_loss_price=43000 +) + +# 只设置止盈 +set_take_profit_stop_loss(coin="BTC", take_profit_price=47000) + +# 只设置止损 +set_take_profit_stop_loss(coin="BTC", stop_loss_price=43000) +``` + +!!! warning "注意" +此方法仅适用于**已有仓位**。 + + 新开仓位请使用 `place_bracket_order()`。 + +--- + +### set_take_profit + +为现有仓位**只设置**止盈。 + +**参数**: + +- `coin` (str): 交易对 +- `take_profit_price` (float): 止盈价格 +- `position_size` (float, 可选): 仓位大小 + +**示例**: + +```python +set_take_profit("ETH", take_profit_price=3200) +``` + +--- + +### set_stop_loss + +为现有仓位**只设置**止损。 + +**参数**: + +- `coin` (str): 交易对 +- `stop_loss_price` (float): 止损价格 +- `position_size` (float, 可选): 仓位大小 + +**示例**: + +```python +set_stop_loss("ETH", stop_loss_price=2900) +``` + +## 📝 订单管理 + +### cancel_order + +根据订单 ID 取消订单。 + +**参数**: + +- `coin` (str): 交易对 +- `order_id` (int): 订单 ID + +**示例**: + +```python +cancel_order("BTC", order_id=123456) +``` + +--- + +### cancel_order_by_client_id + +根据客户端订单 ID 取消订单。 + +**参数**: + +- `coin` (str): 交易对 +- `client_order_id` (str): 客户端订单 ID + +**示例**: + +```python +cancel_order_by_client_id("BTC", client_order_id="0x1234...") +``` + +--- + +### cancel_all_orders + +取消所有订单或指定币种的订单。 + +**参数**: + +- `coin` (str, 可选): 交易对（不指定则取消所有） + +**示例**: + +```python +# 取消 BTC 的所有订单 +cancel_all_orders("BTC") + +# 取消所有币种的订单 +cancel_all_orders() +``` + +--- + +### modify_order + +修改现有订单。 + +**参数**: + +- `coin` (str): 交易对 +- `order_id` (int): 订单 ID +- `new_size` (float): 新订单大小 +- `new_price` (float): 新订单价格 + +**示例**: + +```python +modify_order("ETH", order_id=123456, new_size=2.0, new_price=3100) +``` + +## 💹 市场数据 + +### get_market_data + +获取指定币种的市场数据。 + +**参数**: + +- `coin` (str): 交易对 + +**返回**: + +```json +{ + "success": true, + "data": { + "coin": "BTC", + "mark_price": "45123.45", + "bid": "45120.00", + "ask": "45125.00", + "24h_volume": "1234567.89", + ... + } +} +``` + +**示例**: + +```python +data = get_market_data("BTC") +``` + +--- + +### get_orderbook + +获取订单簿数据。 + +**参数**: + +- `coin` (str): 交易对 +- `depth` (int, 可选): 深度，默认 20 + +**返回**: + +```json +{ + "success": true, + "orderbook": { + "bids": [[45120.0, 1.5], [45110.0, 2.0], ...], + "asks": [[45125.0, 1.2], [45130.0, 1.8], ...] + } +} +``` + +**示例**: + +```python +# 默认深度 20 +book = get_orderbook("BTC") + +# 深度 50 +book = get_orderbook("BTC", depth=50) +``` + +--- + +### get_funding_history + +获取资金费率历史。 + +**参数**: + +- `coin` (str): 交易对 +- `days` (int, 可选): 回溯天数，默认 7 + +**返回**: + +```json +{ + "success": true, + "funding_history": [ + { + "time": "2024-01-01T12:00:00Z", + "rate": "0.0001", + ... + } + ] +} +``` + +**示例**: + +```python +history = get_funding_history("BTC", days=30) +``` + +## ⚙️ 账户设置 + +### update_leverage + +更新杠杆倍数。 + +**参数**: + +- `coin` (str): 交易对 +- `leverage` (int): 杠杆倍数（如 10 表示 10x） +- `cross_margin` (bool, 可选): 全仓模式（true）或逐仓模式（false），默认 true + +**返回**: + +```json +{ + "success": true, + "leverage": 10, + "mode": "cross" +} +``` + +**示例**: + +```python +# 设置 BTC 为 10x 全仓杠杆 +update_leverage("BTC", leverage=10, cross_margin=True) + +# 设置 ETH 为 5x 逐仓杠杆 +update_leverage("ETH", leverage=5, cross_margin=False) +``` + +--- + +### transfer_between_spot_and_perp + +在现货和合约账户间转账。 + +**参数**: + +- `amount` (float): 转账金额 +- `to_perp` (bool, 可选): 转到合约账户（true）或现货账户（false），默认 true + +**返回**: + +```json +{ + "success": true, + "transferred": 1000.0, + "direction": "to_perp" +} +``` + +**示例**: + +```python +# 从现货转 1000 到合约 +transfer_between_spot_and_perp(amount=1000.0, to_perp=True) + +# 从合约转 500 到现货 +transfer_between_spot_and_perp(amount=500.0, to_perp=False) +``` + +## 🧮 实用工具 + +### calculate_token_amount_from_dollars + +根据当前价格将美元金额转换为代币数量。 + +**参数**: + +- `coin` (str): 交易对 +- `dollar_amount` (float): 美元金额 + +**返回**: + +```json +{ + "success": true, + "coin": "SOL", + "dollar_amount": 20.0, + "current_price": 150.0, + "token_amount": 0.133, + "calculation": "$20.00 ÷ $150.00 = 0.133 SOL" +} +``` + +**示例**: + +```python +# 计算 $20 能买多少 SOL +calc = calculate_token_amount_from_dollars("SOL", 20.0) +print(f"Token amount: {calc['token_amount']}") # 0.133 + +# 用于下单 +order = market_open_position("SOL", "buy", calc["token_amount"]) +``` + +!!! tip "最佳实践" +这是**最常用的工具**之一！ + + 在下单前使用此工具将美元金额转换为代币数量，避免下单错误。 + +--- + +## 📋 返回格式 + +所有工具都返回标准化的 JSON 格式： + +### 成功响应 + +```json +{ + "success": true, + "data": { + /* 具体数据 */ + } +} +``` + +或 + +```json +{ + "success": true, + "order_result": { + /* 订单结果 */ + }, + "order_id": 123456 +} +``` + +### 错误响应 + +```json +{ + "success": false, + "error": "错误描述", + "error_code": "ERROR_CODE" +} +``` + +常见错误代码： + +- `VALIDATION_ERROR` - 输入验证失败 +- `INSUFFICIENT_BALANCE` - 余额不足 +- `POSITION_NOT_FOUND` - 仓位不存在 +- `ORDER_NOT_FOUND` - 订单不存在 +- `API_ERROR` - API 调用失败 + +## 🔑 关键概念 + +### Size 参数 + +!!! danger "重要" +**所有交易函数中的 `size` 参数代表代币数量，不是美元金额！** + + - ✅ `0.1` = 0.1 个 BTC/ETH/SOL 代币 + - ❌ `20.0` ≠ $20 美元 + + 使用 `calculate_token_amount_from_dollars()` 进行转换。 + +### OCO 订单组 + +**括号订单** vs **现有仓位 TP/SL**： + +| 场景 | 使用工具 | 订单组类型 | +| ---------------- | ----------------------------- | -------------- | +| 新仓位 + TP/SL | `place_bracket_order()` | `normalTpSl` | +| 现有仓位 + TP/SL | `set_take_profit_stop_loss()` | `positionTpSl` | + +### 客户端订单 ID + +格式要求：**128 位十六进制字符串** + +- ✅ `0x1234567890abcdef1234567890abcdef` +- ❌ `my-order-123` + +## 📚 相关文档 + +- [使用指南](../guides/trading-tools.md) - 详细的使用教程 +- [常见用例](../guides/use-cases.md) - 实际应用示例 +- [错误处理](error-handling.md) - 错误处理最佳实践 +- [故障排除](../troubleshooting.md) - 常见问题解决 diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..3dd7e54 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,17 @@ +# 更新日志 + +本文件记录了 HyperLiquid MCP Server 的所有重要更改。 + +## [Unreleased] + +### Added + +- 📚 完整的 MkDocs Material 文档网站 +- 🌐 中英文文档支持 +- 🎨 美观的 Material Design 主题 + +## 历史版本 + +请查看 [GitHub Releases](https://github.com/talkincode/hyperliquid-mcp-python/releases) 获取完整的版本历史。 + +另请参阅项目根目录的 [CHANGELOG.md](https://github.com/talkincode/hyperliquid-mcp-python/blob/main/CHANGELOG.md) 文件。 diff --git a/docs/developers/contributing.md b/docs/developers/contributing.md new file mode 100644 index 0000000..24c53b1 --- /dev/null +++ b/docs/developers/contributing.md @@ -0,0 +1,107 @@ +# 贡献指南 + +欢迎为 HyperLiquid MCP Server 做出贡献！本页概述开发流程、代码规范与提交要求。更多细节请参考仓库根目录的 `CONTRIBUTING.md`。 + +## 准备工作 + +### Fork 与克隆 + +```bash +git clone https://github.com/<你的用户名>/hyperliquid-mcp-python.git +cd hyperliquid-mcp-python +``` + +### 安装依赖 + +```bash +uv sync --all-extras --dev +``` + +### 创建分支 + +```bash +git checkout -b feature/<你的功能> +# 或 +git checkout -b fix/<你的修复> +``` + +## 开发流程 + +1. **实现功能**：遵循既有架构约定，保持异步接口和服务层分离。 +2. **补充测试**：新增或修改功能必须附带相应测试。 +3. **自检**：运行格式化和静态检查工具，保持代码整洁。 +4. **提交 PR**：填写 Pull Request 模板，说明变更动机及测试情况。 + +### 常用命令 + +```bash +# 运行全部测试 +uv run pytest + +# 运行指定测试 +uv run pytest tests/unit/test_validators.py + +# 运行格式化 +uv run black . +uv run isort . +``` + +## 提交信息规范 + +项目采用 [Conventional Commits](https://www.conventionalcommits.org/)： + +- `feat:` 新功能 +- `fix:` Bug 修复 +- `docs:` 文档更新 +- `style:` 仅格式调整 +- `refactor:` 代码重构 +- `test:` 测试相关 +- `chore:` 构建或辅助工具变动 + +示例： + +``` +feat: 支持批量撤单工具 +fix: 修复 size 合法性校验 +``` + +## 代码规范 + +- 使用 Black / isort 统一代码风格。 +- 遵循 PEP 8，必要时补充类型注解。 +- 为公共 API 编写 docstring，说明参数与返回值。 +- 捕获并整理 HyperLiquid SDK 抛出的异常，统一返回格式。 + +## 测试要求 + +- 为新功能添加单元测试，必要时补充集成测试。 +- 确保 `uv run pytest` 全部通过。 +- 如需真实 API，请使用测试网 (`HYPERLIQUID_TESTNET=true`) 并提供 mock 方案。 + +## 文档同步 + +- 功能变更需更新 `docs/api/*.md` 或 `docs/guides/*.md`。 +- 文档站点使用 MkDocs，可通过 `mkdocs serve` 本地预览。 +- 提交前运行 `mkdocs build`，确保无损坏链接或缺失文件。 + +## 提交 PR 前检查清单 + +- [ ] 单元测试与集成测试全部通过。 +- [ ] 关键逻辑添加或更新测试用例。 +- [ ] 已运行 `uv run black .` 与 `uv run isort .`。 +- [ ] 文档已更新并通过构建。 +- [ ] PR 模板填写完整，包含测试结果。 + +## 获取帮助 + +- 阅读仓库根目录的 `README.md` 与 `CONTRIBUTING.md`。 +- 在 GitHub Issues 中提问或参考既有讨论。 +- 通过 PR 评论交流实现细节。 + +感谢你的贡献，祝编码愉快！🚀 + +--- + +**相关文档** + +- [项目 README](../../README.md) diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md new file mode 100644 index 0000000..f885e86 --- /dev/null +++ b/docs/getting-started/configuration.md @@ -0,0 +1,254 @@ +# 配置指南 + +在使用 HyperLiquid MCP Server 之前，需要配置必要的参数。 + +## 配置方式 + +支持三种配置方式（按优先级排序）： + +1. **环境变量**（最高优先级） +2. **`.env` 文件** +3. **`config.json` 文件** + +## 方式 1：环境变量（推荐） + +直接设置环境变量： + +```bash +export HYPERLIQUID_PRIVATE_KEY="0x..." +export HYPERLIQUID_TESTNET="true" +export HYPERLIQUID_ACCOUNT_ADDRESS="0x..." # 可选 +``` + +## 方式 2：.env 文件 + +创建 `.env` 文件： + +```bash +# 复制示例文件 +cp .env.example .env + +# 编辑配置 +nano .env +``` + +`.env` 文件内容： + +```bash +# 必填：你的私钥 +HYPERLIQUID_PRIVATE_KEY=0x1234567890abcdef... + +# 可选：是否使用测试网（默认：false） +HYPERLIQUID_TESTNET=true + +# 可选：账户地址（如果不设置，会从私钥自动派生） +HYPERLIQUID_ACCOUNT_ADDRESS=0xabcdef... +``` + +## 方式 3：config.json 文件 + +创建 `config.json` 文件： + +```json +{ + "private_key": "0x1234567890abcdef...", + "testnet": true, + "account_address": "0xabcdef..." +} +``` + +!!! note "键名格式" +注意 `config.json` 使用 **snake_case** 格式（`private_key`），而环境变量使用 **UPPER_CASE** 格式（`HYPERLIQUID_PRIVATE_KEY`）。 + +## 配置参数说明 + +### HYPERLIQUID_PRIVATE_KEY + +- **必填** +- **格式**：以 `0x` 开头的十六进制字符串 +- **说明**：你的 HyperLiquid 账户私钥 + +!!! danger "安全警告" - **绝不要**将私钥提交到版本控制 - **绝不要**在公开场合分享私钥 - 建议使用 **API 钱包**而非主钱包 + +### HYPERLIQUID_TESTNET + +- **可选**（默认：`false`） +- **格式**：`true` 或 `false` +- **说明**：是否使用测试网 + +!!! tip "强烈建议" +在正式使用前，**务必先在测试网**进行充分测试！ + +### HYPERLIQUID_ACCOUNT_ADDRESS + +- **可选** +- **格式**：以 `0x` 开头的以太坊地址 +- **说明**：账户地址 + +!!! info "何时需要设置" - 使用 **API 钱包**时，必须设置为主账户地址 - 使用普通钱包时，会自动从私钥派生，无需设置 + +## 获取私钥 + +### 方式 1：使用 API 钱包（推荐）✅ + +API 钱包是 HyperLiquid 提供的专用交易密钥，权限受限，更安全。 + +1. 访问 [HyperLiquid API 页面](https://app.hyperliquid.xyz/API) +2. 点击 "Create API Wallet" +3. 保存生成的私钥 +4. 设置配置： + +```bash +HYPERLIQUID_PRIVATE_KEY=0x... # API 钱包私钥 +HYPERLIQUID_ACCOUNT_ADDRESS=0x... # 你的主账户地址 +``` + +### 方式 2：使用主钱包私钥 + +!!! warning "不推荐" +使用主钱包私钥风险较高，仅建议在测试网使用。 + +1. 从 MetaMask 或其他钱包导出私钥 +2. 设置配置： + +```bash +HYPERLIQUID_PRIVATE_KEY=0x... # 主钱包私钥 +# 无需设置 ACCOUNT_ADDRESS，会自动派生 +``` + +## 网络选择 + +### 测试网 + +```bash +HYPERLIQUID_TESTNET=true +``` + +- **优点**：安全测试，无真实资金风险 +- **缺点**：需要申请测试币 +- **适用场景**：开发、测试、学习 + +### 主网 + +```bash +HYPERLIQUID_TESTNET=false # 或不设置 +``` + +- **优点**：真实交易 +- **缺点**：涉及真实资金 +- **适用场景**：生产环境 + +!!! danger "主网使用前" +确保已在测试网充分测试，理解所有风险！ + +## 验证配置 + +运行配置验证： + +```bash +# 使用 Makefile +make config + +# 或直接运行 +uv run python -c "from main import get_config; print(get_config())" +``` + +输出示例： + +``` +Network: Testnet +Account: 0x1234567890abcdef1234567890abcdef12345678 +Private Key: 0x**** (hidden) +``` + +## 快速测试 + +验证配置是否正确： + +```bash +# 快速验证（连接 + 余额 + 地址） +make test-quick + +# 或手动运行 +uv run python test_scripts/test_connection.py +``` + +## 安全最佳实践 + +### ✅ 推荐做法 + +- 使用 **API 钱包** +- 先在**测试网**测试 +- 将 `.env` 添加到 `.gitignore` +- 使用**环境变量**而非配置文件 +- 定期**轮换** API 密钥 + +### ❌ 避免做法 + +- 提交私钥到 Git +- 在主网直接测试 +- 使用主钱包私钥 +- 在公共场合分享配置 +- 硬编码私钥到代码 + +## 多环境配置 + +### 开发环境 + +```bash +# .env.development +HYPERLIQUID_PRIVATE_KEY=0x... +HYPERLIQUID_TESTNET=true +``` + +### 生产环境 + +```bash +# .env.production +HYPERLIQUID_PRIVATE_KEY=0x... +HYPERLIQUID_TESTNET=false +``` + +### 使用不同配置 + +```bash +# 加载开发环境 +cp .env.development .env + +# 加载生产环境 +cp .env.production .env +``` + +## 常见问题 + +### 私钥格式错误 + +确保私钥： + +- 以 `0x` 开头 +- 包含 64 个十六进制字符（不含 `0x` 前缀） +- 示例：`0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef` + +### 找不到配置文件 + +确保 `.env` 或 `config.json` 在项目根目录： + +```bash +# 检查文件位置 +ls -la .env +ls -la config.json +``` + +### API 钱包地址未设置 + +使用 API 钱包时必须设置主账户地址： + +```bash +HYPERLIQUID_ACCOUNT_ADDRESS=0x... # 你的主账户地址，不是 API 钱包地址 +``` + +## 下一步 + +- [快速验证](quick-start.md) - 运行测试确保配置正确 +- [MCP 客户端集成](../guides/mcp-integration.md) - 与 Claude Desktop 集成 +- [交易工具](../guides/trading-tools.md) - 开始使用交易功能 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..ad764b5 --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,171 @@ +# 安装指南 + +HyperLiquid MCP Server 提供多种安装方式，选择最适合你的方式开始使用。 + +## 方式 1：使用 uvx（推荐）🚀 + +这是**最简单的方式** - 无需安装，直接运行！ + +### 前提条件 + +确保已安装 [uv](https://github.com/astral-sh/uv)： + +```bash +# macOS/Linux +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Windows +powershell -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +### 运行服务器 + +```bash +# 查看帮助 +uvx --python 3.13 --from hyperliquid-mcp-python hyperliquid-mcp --help + +# 启动 HTTP 服务器（默认 127.0.0.1:8080） +uvx --python 3.13 --from hyperliquid-mcp-python hyperliquid-mcp start + +# 启动 stdio 服务器（用于 MCP 客户端） +uvx --python 3.13 --from hyperliquid-mcp-python hyperliquid-mcp stdio +``` + +!!! info "为什么要指定 `--python 3.13`?" +依赖包 `ckzg` 目前只提供到 Python 3.13 的预编译包，Python 3.14 还不支持。指定版本可以避免编译错误。 + +## 方式 2：本地开发安装 + +适合需要修改代码或深度定制的开发者。 + +### 克隆仓库 + +```bash +git clone https://github.com/talkincode/hyperliquid-mcp-python.git +cd hyperliquid-mcp-python +``` + +### 安装依赖 + +```bash +# 使用 uv（推荐） +uv sync + +# 或使用 pip +pip install -e . +``` + +### 运行 + +```bash +# 使用 Makefile（最简单） +make run-http # HTTP 服务器 +make run-stdio # stdio 服务器 + +# 或直接使用 uv +uv run hyperliquid-mcp # HTTP 模式 +uv run hyperliquid-mcp stdio # stdio 模式 + +# 或使用已安装的命令 +hyperliquid-mcp # HTTP 模式 +hyperliquid-mcp stdio # stdio 模式 +``` + +## 方式 3：pip 安装 + +适合在现有 Python 环境中使用。 + +### 要求 + +- Python 3.10-3.13（不支持 3.14） + +### 安装 + +```bash +pip install hyperliquid-mcp-python +``` + +### 运行 + +```bash +hyperliquid-mcp --help # 查看帮助 +hyperliquid-mcp # HTTP 服务器 +hyperliquid-mcp stdio # stdio 服务器 +``` + +## Python 版本说明 + +!!! warning "重要提示" - **支持版本**：Python 3.10, 3.11, 3.12, 3.13 - **不支持**：Python 3.14（依赖包 `ckzg` 尚未提供预编译包） - **推荐版本**：Python 3.13 + +### 检查 Python 版本 + +```bash +python --version +# 或 +python3 --version +``` + +## 验证安装 + +安装完成后，验证是否正常工作： + +```bash +# 查看版本 +hyperliquid-mcp --version + +# 查看帮助 +hyperliquid-mcp --help + +# 测试连接（需要先配置） +uv run python test_scripts/test_connection.py +``` + +## 下一步 + +- [配置服务器](configuration.md) - 设置私钥和网络 +- [快速验证](quick-start.md) - 运行测试确保一切正常 +- [MCP 客户端集成](../guides/mcp-integration.md) - 与 Claude Desktop 集成 + +## 常见问题 + +### 编译错误 + +如果遇到 `ckzg` 编译错误： + +```bash +# 指定 Python 3.13 +uvx --python 3.13 --from hyperliquid-mcp-python hyperliquid-mcp +``` + +### 命令未找到 + +如果 `hyperliquid-mcp` 命令未找到： + +```bash +# 确保已安装 +pip show hyperliquid-mcp-python + +# 使用完整路径 +python -m cli + +# 或使用 uv +uv run hyperliquid-mcp +``` + +### 权限问题 + +在 macOS/Linux 上，可能需要添加执行权限： + +```bash +chmod +x /path/to/hyperliquid-mcp +``` + +## 卸载 + +```bash +# pip 安装 +pip uninstall hyperliquid-mcp-python + +# 本地开发 +rm -rf .venv +``` diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md new file mode 100644 index 0000000..a1c2372 --- /dev/null +++ b/docs/getting-started/quick-start.md @@ -0,0 +1,238 @@ +# 快速验证 + +完成配置后，运行测试确保一切正常工作。 + +## 方式 1：使用 Makefile（推荐）⭐ + +最简单的方式： + +```bash +# 快速验证（连接 + 余额 + 地址） +make test-quick + +# 查看所有可用测试 +make list-tests + +# 运行所有只读测试 +make test-all +``` + +## 方式 2：手动运行测试 + +### 1. 测试连接 + +验证能否连接到 HyperLiquid API： + +```bash +uv run python test_scripts/test_connection.py +``` + +成功输出示例： + +``` +✅ Connection test passed! +Network: Testnet +Account: 0x1234567890abcdef1234567890abcdef12345678 +``` + +### 2. 检查余额 + +查看账户余额： + +```bash +# 检查所有余额（现货 + 合约） +uv run python test_scripts/check_all_balances.py + +# 查看详细余额 +uv run python test_scripts/check_detailed_balance.py +``` + +输出示例： + +``` +📊 HyperLiquid Account Balance + +Perpetual Account: + Total Value: $1,234.56 + Available: $1,000.00 + Margin Used: $234.56 + +Spot Account: + USDC: 500.00 + BTC: 0.05 +``` + +### 3. 验证地址 + +确认账户地址配置正确： + +```bash +uv run python test_scripts/test_account_address.py +``` + +### 4. 测试市场数据 + +获取实时市场数据： + +```bash +uv run python test_scripts/test_market_data.py +``` + +## 交互式测试工具 + +推荐使用交互式测试工具，可以方便地测试各种功能： + +```bash +uv run python test_scripts/interactive_test.py +``` + +功能菜单： + +``` +HyperLiquid MCP Interactive Test + +1. Get Account Balance +2. Get Open Positions +3. Get Market Data +4. Get Order Book +5. Calculate Token Amount from Dollars +6. Place Test Order (Testnet Only) +7. Exit + +Enter your choice: +``` + +## 运行测试套件 + +运行完整的测试套件： + +```bash +# 使用测试脚本 +./test_scripts/run_tests.sh all + +# 或使用 Makefile +make test-all +``` + +## 验证清单 + +确保以下测试都通过： + +- [ ] ✅ 连接测试通过 +- [ ] ✅ 能获取账户余额 +- [ ] ✅ 账户地址正确 +- [ ] ✅ 能获取市场数据 +- [ ] ✅ 能获取订单簿数据 + +## 常见问题排查 + +### 连接失败 + +**错误信息**：`Connection error` 或 `timeout` + +**解决方案**： + +1. 检查网络连接 +2. 确认 `HYPERLIQUID_TESTNET` 设置正确 +3. 检查防火墙设置 + +### 认证失败 + +**错误信息**：`Authentication failed` 或 `Invalid signature` + +**解决方案**： + +1. 检查私钥格式（必须以 `0x` 开头） +2. 确认私钥正确 +3. 如使用 API 钱包，确认 `ACCOUNT_ADDRESS` 已设置 + +### 余额为 0 + +**测试网**： + +- 访问 HyperLiquid 测试网水龙头获取测试币 +- 确认使用的是测试网地址 + +**主网**： + +- 确认账户已充值 +- 检查是否使用了正确的账户地址 + +### 找不到测试脚本 + +确保在项目根目录运行： + +```bash +cd /path/to/hyperliquid-mcp-python +pwd # 确认当前目录 +ls test_scripts/ # 确认测试脚本存在 +``` + +## 下一步 + +验证通过后，可以： + +1. **学习使用工具** + + - [交易工具](../guides/trading-tools.md) + - [账户管理](../guides/account-management.md) + - [市场数据](../guides/market-data.md) + +2. **集成到 MCP 客户端** + + - [MCP 客户端集成](../guides/mcp-integration.md) + +3. **了解架构** + - [架构设计](../developers/architecture.md) + - [测试工具](../developers/testing.md) + +## 测试环境建议 + +### 测试网优先 + +!!! tip "强烈建议" +**务必先在测试网充分测试**，再考虑使用主网！ + +测试网优势： + +- ✅ 无真实资金风险 +- ✅ 可以放心测试各种功能 +- ✅ 可以测试错误处理 +- ✅ 学习成本低 + +### 测试流程 + +1. **配置测试网** + + ```bash + HYPERLIQUID_TESTNET=true + ``` + +2. **获取测试币** + + - 访问 HyperLiquid 测试网 + - 申请测试 USDC + +3. **运行所有测试** + + ```bash + make test-all + ``` + +4. **尝试小额交易** + + ```bash + uv run python test_scripts/test_small_order.py + ``` + +5. **验证功能完整性** + ```bash + uv run python test_scripts/verify_completion.py + ``` + +## 更多测试 + +查看完整的测试文档： + +- [测试工具文档](../developers/testing.md) +- [测试脚本 README](https://github.com/talkincode/hyperliquid-mcp-python/tree/main/test_scripts) diff --git a/docs/guides/account-management.md b/docs/guides/account-management.md new file mode 100644 index 0000000..fb1350b --- /dev/null +++ b/docs/guides/account-management.md @@ -0,0 +1,616 @@ +# 账户管理 + +本页面介绍如何管理 HyperLiquid 账户、仓位和资金。 + +## 账户信息 + +### 查看余额 + +```python +balance = get_account_balance() + +if balance["success"]: + data = balance["data"] + print(f"账户总值: ${data['account_value']}") + print(f"可用余额: ${data['withdrawable']}") + print(f"已用保证金: ${data['total_margin_used']}") +``` + +**字段说明**: + +- `account_value`: 账户总价值（USD） +- `withdrawable`: 可提取金额 +- `total_margin_used`: 已使用的保证金 +- `total_ntl_pos`: 仓位名义价值 +- `total_raw_usd`: 原始 USD 余额 + +### 账户概览 + +一次性获取所有信息： + +```python +summary = get_account_summary() + +if summary["success"]: + s = summary["summary"] + + # 余额信息 + balance = s["balance"] + print(f"账户总值: ${balance['account_value']}") + + # 仓位信息 + print(f"开仓数量: {s['total_positions']}") + for pos in s["positions"]: + print(f" {pos['coin']}: {pos['szi']} @ ${pos['entry_px']}") + + # 订单信息 + print(f"未成交订单: {s['total_orders']}") +``` + +## 仓位管理 + +### 查看所有仓位 + +```python +positions = get_open_positions() + +if positions["success"]: + for pos in positions["positions"]: + coin = pos["coin"] + size = pos["szi"] + entry = pos["entry_px"] + pnl = pos["unrealized_pnl"] + + direction = "多" if float(size) > 0 else "空" + print(f"{coin} {direction}仓: {abs(float(size))} @ ${entry}") + print(f" 未实现盈亏: ${pnl}") +``` + +### 仓位详细信息 + +```python +positions = get_open_positions() + +if positions["success"]: + for pos in positions["positions"]: + print(f""" +仓位: {pos['coin']} +方向: {'做多' if float(pos['szi']) > 0 else '做空'} +数量: {abs(float(pos['szi']))} +开仓均价: ${pos['entry_px']} +仓位价值: ${pos['position_value']} +未实现盈亏: ${pos['unrealized_pnl']} +回报率: {pos['return_on_equity']} +杠杆: {pos['leverage']} +强平价: ${pos['liquidation_px']} + """) +``` + +### 检查特定仓位 + +```python +def get_position(coin): + """获取特定币种的仓位""" + positions = get_open_positions() + + if positions["success"]: + return next( + (p for p in positions["positions"] if p["coin"] == coin), + None + ) + return None + +# 使用 +btc_pos = get_position("BTC") +if btc_pos: + print(f"BTC 仓位大小: {btc_pos['szi']}") +else: + print("没有 BTC 仓位") +``` + +### 计算仓位盈亏 + +```python +def calculate_pnl(coin): + """计算仓位盈亏详情""" + pos = get_position(coin) + if not pos: + return None + + size = abs(float(pos["szi"])) + entry_price = float(pos["entry_px"]) + + # 获取当前价格 + market = get_market_data(coin) + current_price = float(market["data"]["mark_px"]) + + # 计算盈亏 + is_long = float(pos["szi"]) > 0 + if is_long: + pnl = (current_price - entry_price) * size + pnl_pct = (current_price / entry_price - 1) * 100 + else: + pnl = (entry_price - current_price) * size + pnl_pct = (entry_price / current_price - 1) * 100 + + return { + "unrealized_pnl": pnl, + "pnl_percentage": pnl_pct, + "entry_price": entry_price, + "current_price": current_price + } + +# 使用 +pnl = calculate_pnl("BTC") +if pnl: + print(f"盈亏: ${pnl['unrealized_pnl']:.2f} ({pnl['pnl_percentage']:.2f}%)") +``` + +## 杠杆管理 + +### 更新杠杆 + +```python +# 设置 BTC 为 10x 全仓杠杆 +result = update_leverage("BTC", leverage=10, cross_margin=True) + +# 设置 ETH 为 5x 逐仓杠杆 +result = update_leverage("ETH", leverage=5, cross_margin=False) +``` + +### 全仓 vs 逐仓 + +**全仓模式** (`cross_margin=True`): + +- ✅ 使用账户全部可用余额作为保证金 +- ✅ 降低强平风险 +- ❌ 一个仓位爆仓可能影响其他仓位 + +**逐仓模式** (`cross_margin=False`): + +- ✅ 每个仓位独立，风险隔离 +- ✅ 最大损失仅为该仓位保证金 +- ❌ 更容易触发强平 + +### 批量设置杠杆 + +```python +def set_leverage_for_all(leverage, cross_margin=True): + """为所有仓位设置相同杠杆""" + positions = get_open_positions() + + if positions["success"]: + for pos in positions["positions"]: + coin = pos["coin"] + result = update_leverage(coin, leverage, cross_margin) + + if result["success"]: + print(f"✅ {coin}: {leverage}x") + else: + print(f"❌ {coin}: {result['error']}") + +# 使用：所有仓位设置为 5x 全仓 +set_leverage_for_all(5, cross_margin=True) +``` + +## 资金划转 + +### 现货和合约间转账 + +```python +# 从现货转 1000 到合约账户 +result = transfer_between_spot_and_perp( + amount=1000.0, + to_perp=True +) + +# 从合约转 500 到现货账户 +result = transfer_between_spot_and_perp( + amount=500.0, + to_perp=False +) + +if result["success"]: + print(f"✅ 转账成功: {result['message']}") +``` + +### 检查余额后转账 + +```python +def safe_transfer_to_perp(amount): + """安全地从现货转到合约""" + # TODO: 需要先实现获取现货余额的功能 + # 这里假设有足够余额 + + result = transfer_between_spot_and_perp(amount, to_perp=True) + + if result["success"]: + print(f"✅ 已转入 ${amount} 到合约账户") + else: + print(f"❌ 转账失败: {result['error']}") +``` + +## 交易历史 + +### 查看最近交易 + +```python +# 最近 7 天的交易 +history = get_trade_history(days=7) + +if history["success"]: + for trade in history["trades"]: + print(f""" +时间: {trade['time']} +币种: {trade['coin']} +方向: {trade['side']} +数量: {trade['size']} +价格: ${trade['price']} + """) +``` + +### 查看特定币种的交易 + +```python +def get_coin_trades(coin, days=7): + """获取特定币种的交易历史""" + history = get_trade_history(days=days) + + if history["success"]: + coin_trades = [ + t for t in history["trades"] + if t["coin"] == coin + ] + return coin_trades + return [] + +# 使用 +btc_trades = get_coin_trades("BTC", days=30) +print(f"BTC 最近 30 天交易: {len(btc_trades)} 笔") +``` + +### 计算交易统计 + +```python +def calculate_trade_stats(coin, days=30): + """计算交易统计数据""" + trades = get_coin_trades(coin, days) + + if not trades: + return None + + total_volume = sum(float(t["size"]) * float(t["price"]) for t in trades) + avg_price = sum(float(t["price"]) for t in trades) / len(trades) + + buys = [t for t in trades if t["side"] == "buy"] + sells = [t for t in trades if t["side"] == "sell"] + + return { + "total_trades": len(trades), + "total_volume": total_volume, + "average_price": avg_price, + "buy_count": len(buys), + "sell_count": len(sells), + "days": days + } + +# 使用 +stats = calculate_trade_stats("BTC", days=30) +if stats: + print(f""" +BTC 交易统计 (最近 {stats['days']} 天): +总交易次数: {stats['total_trades']} +总交易量: ${stats['total_volume']:.2f} +平均价格: ${stats['average_price']:.2f} +买入: {stats['buy_count']} | 卖出: {stats['sell_count']} + """) +``` + +## 订单管理 + +### 查看未成交订单 + +```python +orders = get_open_orders() + +if orders["success"]: + print(f"未成交订单: {orders['total_orders']}") + + for order in orders["orders"]: + print(f""" +订单 ID: {order['order_id']} +币种: {order['coin']} +方向: {order['side']} +数量: {order['sz']} +价格: ${order['limit_px']} +类型: {order['order_type']} + """) +``` + +### 按币种分组订单 + +```python +from collections import defaultdict + +def group_orders_by_coin(): + """按币种分组订单""" + orders = get_open_orders() + + if not orders["success"]: + return {} + + grouped = defaultdict(list) + for order in orders["orders"]: + grouped[order["coin"]].append(order) + + return dict(grouped) + +# 使用 +grouped = group_orders_by_coin() +for coin, coin_orders in grouped.items(): + print(f"{coin}: {len(coin_orders)} 个订单") +``` + +### 清理所有订单 + +```python +def cleanup_all_orders(): + """取消所有未成交订单""" + result = cancel_all_orders() + + if result["success"]: + print(f"✅ 已取消 {result['cancelled_count']} 个订单") + else: + print(f"❌ 取消失败: {result['error']}") + +# 使用 +cleanup_all_orders() +``` + +## 风险管理 + +### 计算账户风险 + +```python +def calculate_account_risk(): + """计算账户风险指标""" + summary = get_account_summary() + + if not summary["success"]: + return None + + balance = summary["summary"]["balance"] + account_value = float(balance["account_value"]) + margin_used = float(balance["total_margin_used"]) + + # 保证金使用率 + margin_ratio = (margin_used / account_value) * 100 if account_value > 0 else 0 + + # 计算总未实现盈亏 + positions = summary["summary"]["positions"] + total_unrealized_pnl = sum(float(p["unrealized_pnl"]) for p in positions) + + # 风险等级 + if margin_ratio > 80: + risk_level = "高风险" + elif margin_ratio > 50: + risk_level = "中风险" + else: + risk_level = "低风险" + + return { + "account_value": account_value, + "margin_used": margin_used, + "margin_ratio": margin_ratio, + "risk_level": risk_level, + "total_unrealized_pnl": total_unrealized_pnl, + "free_margin": account_value - margin_used + } + +# 使用 +risk = calculate_account_risk() +if risk: + print(f""" +账户风险分析: +账户总值: ${risk['account_value']:.2f} +已用保证金: ${risk['margin_used']:.2f} +保证金使用率: {risk['margin_ratio']:.1f}% +风险等级: {risk['risk_level']} +未实现盈亏: ${risk['total_unrealized_pnl']:.2f} +可用保证金: ${risk['free_margin']:.2f} + """) +``` + +### 设置仓位限制 + +```python +def check_position_limit(coin, new_size_usd, max_position_pct=20.0): + """检查是否超过仓位限制 + + Args: + coin: 币种 + new_size_usd: 新增仓位美元价值 + max_position_pct: 单个仓位最大占比（默认20%） + """ + balance = get_account_balance() + if not balance["success"]: + return False + + account_value = float(balance["data"]["account_value"]) + max_size = account_value * (max_position_pct / 100) + + # 检查现有仓位 + pos = get_position(coin) + current_size = 0 + if pos: + current_size = float(pos["position_value"]) + + total_size = current_size + new_size_usd + + if total_size > max_size: + print(f"❌ 超过仓位限制!") + print(f"当前: ${current_size:.2f}") + print(f"新增: ${new_size_usd:.2f}") + print(f"总计: ${total_size:.2f}") + print(f"限制: ${max_size:.2f} ({max_position_pct}%)") + return False + + return True + +# 使用 +if check_position_limit("BTC", 5000.0, max_position_pct=25.0): + print("✅ 未超过仓位限制，可以开仓") +``` + +## 资金费率 + +### 查看资金费率历史 + +```python +# 查看 BTC 最近 7 天的资金费率 +funding = get_funding_history("BTC", days=7) + +if funding["success"]: + for rate in funding["funding_history"]: + print(f"时间: {rate['time']}") + print(f"费率: {rate['fundingRate']}") + print(f"溢价: {rate['premium']}") + print("---") +``` + +### 计算资金费用 + +```python +def estimate_funding_cost(coin, days=30): + """估算资金费用""" + # 获取仓位 + pos = get_position(coin) + if not pos: + return None + + position_value = float(pos["position_value"]) + + # 获取资金费率历史 + funding = get_funding_history(coin, days=days) + if not funding["success"]: + return None + + # 计算平均费率 + rates = [float(r["fundingRate"]) for r in funding["funding_history"]] + avg_rate = sum(rates) / len(rates) if rates else 0 + + # 估算费用（每8小时收取一次） + funding_periods = days * 3 # 每天3次 + estimated_cost = position_value * avg_rate * funding_periods + + return { + "avg_funding_rate": avg_rate, + "estimated_cost": estimated_cost, + "days": days, + "position_value": position_value + } + +# 使用 +cost = estimate_funding_cost("BTC", days=30) +if cost: + print(f""" +资金费用估算 (30天): +仓位价值: ${cost['position_value']:.2f} +平均费率: {cost['avg_funding_rate']:.6f} +估算费用: ${cost['estimated_cost']:.2f} + """) +``` + +## 最佳实践 + +### 1. 定期检查账户状态 + +```python +def daily_account_check(): + """每日账户检查""" + print("=== 每日账户检查 ===\n") + + # 1. 余额 + balance = get_account_balance() + if balance["success"]: + print(f"账户总值: ${balance['data']['account_value']}") + + # 2. 仓位 + positions = get_open_positions() + if positions["success"]: + print(f"开仓数: {positions['total_positions']}") + for pos in positions["positions"]: + pnl = float(pos["unrealized_pnl"]) + emoji = "📈" if pnl > 0 else "📉" + print(f" {emoji} {pos['coin']}: ${pnl:.2f}") + + # 3. 风险 + risk = calculate_account_risk() + if risk: + print(f"保证金使用率: {risk['margin_ratio']:.1f}%") + print(f"风险等级: {risk['risk_level']}") + +# 每天运行一次 +daily_account_check() +``` + +### 2. 自动止损检查 + +```python +def check_stop_loss_coverage(): + """检查所有仓位是否设置了止损""" + positions = get_open_positions() + orders = get_open_orders() + + if not positions["success"] or not orders["success"]: + return + + for pos in positions["positions"]: + coin = pos["coin"] + + # 检查是否有止损订单 + has_stop_loss = any( + o["coin"] == coin and o["order_type"] == "Stop" + for o in orders["orders"] + ) + + if not has_stop_loss: + print(f"⚠️ {coin} 没有设置止损!") + +check_stop_loss_coverage() +``` + +### 3. 仓位再平衡 + +```python +def rebalance_portfolio(target_allocations): + """按目标比例重新平衡仓位 + + Args: + target_allocations: {"BTC": 50, "ETH": 30, "SOL": 20} + """ + balance = get_account_balance() + total_value = float(balance["data"]["account_value"]) + + for coin, target_pct in target_allocations.items(): + target_value = total_value * (target_pct / 100) + + pos = get_position(coin) + current_value = float(pos["position_value"]) if pos else 0 + + diff = target_value - current_value + + if abs(diff) > total_value * 0.01: # 超过1%才调整 + print(f"{coin}: 调整 ${diff:.2f}") + # TODO: 实现调整逻辑 + +# 使用 +rebalance_portfolio({"BTC": 50, "ETH": 30, "SOL": 20}) +``` + +## 相关文档 + +- [交易工具](trading-tools.md) - 交易工具使用 +- [市场数据](market-data.md) - 获取市场数据 +- [API 参考](../api/tools-reference.md) - 完整 API 文档 +- [故障排除](../troubleshooting.md) - 常见问题 diff --git a/docs/guides/mcp-integration.md b/docs/guides/mcp-integration.md new file mode 100644 index 0000000..402af82 --- /dev/null +++ b/docs/guides/mcp-integration.md @@ -0,0 +1,519 @@ +# MCP 客户端集成 + +本页面介绍如何将 HyperLiquid MCP Server 集成到 MCP 客户端（如 Claude Desktop）。 + +## Claude Desktop 集成 + +### 前提条件 + +1. 已安装 Claude Desktop +2. 已完成 [HyperLiquid MCP Server 配置](../getting-started/configuration.md) +3. 已验证服务器可以正常运行 + +### 配置文件位置 + +Claude Desktop 的配置文件位于： + +**macOS**: + +``` +~/Library/Application Support/Claude/claude_desktop_config.json +``` + +**Windows**: + +``` +%APPDATA%\Claude\claude_desktop_config.json +``` + +**Linux**: + +``` +~/.config/Claude/claude_desktop_config.json +``` + +## 配置方式 + +### 方式 1: 本地开发版本（推荐） + +如果你克隆了仓库并在本地开发： + +```json +{ + "mcpServers": { + "hyperliquid": { + "command": "uv", + "args": [ + "--directory", + "/完整/绝对/路径/hyperliquid-mcp", + "run", + "hyperliquid-mcp", + "stdio" + ], + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0x你的私钥", + "HYPERLIQUID_TESTNET": "true", + "HYPERLIQUID_ACCOUNT_ADDRESS": "0x你的账户地址（如使用API钱包）" + } + } + } +} +``` + +**重要提示**: + +- ✅ 使用**完整的绝对路径**（不要用 `~`） +- ✅ macOS/Linux 示例: `/Users/yourname/projects/hyperliquid-mcp` +- ✅ Windows 示例: `C:\\Users\\yourname\\projects\\hyperliquid-mcp` + +### 方式 2: 使用 uvx（无需安装） + +最简单的方式，无需克隆仓库： + +```json +{ + "mcpServers": { + "hyperliquid": { + "command": "uvx", + "args": [ + "--python", + "3.13", + "--from", + "hyperliquid-mcp-python", + "hyperliquid-mcp", + "stdio" + ], + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0x你的私钥", + "HYPERLIQUID_TESTNET": "true", + "HYPERLIQUID_ACCOUNT_ADDRESS": "0x你的账户地址（可选）" + } + } + } +} +``` + +!!! tip "为什么指定 Python 3.13?" +依赖包 `ckzg` 目前只提供到 Python 3.13 的预编译包。 + +### 方式 3: 全局安装版本 + +如果已经通过 pip 全局安装： + +```json +{ + "mcpServers": { + "hyperliquid": { + "command": "hyperliquid-mcp", + "args": ["stdio"], + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0x你的私钥", + "HYPERLIQUID_TESTNET": "true" + } + } + } +} +``` + +## 环境变量配置 + +### 必需变量 + +| 变量 | 说明 | 示例 | +| ------------------------- | ------------------ | ----------- | +| `HYPERLIQUID_PRIVATE_KEY` | 私钥（以 0x 开头） | `0x1234...` | + +### 可选变量 + +| 变量 | 默认值 | 说明 | +| ----------------------------- | -------- | -------------------------------- | +| `HYPERLIQUID_TESTNET` | `false` | 使用测试网（强烈建议先用测试网） | +| `HYPERLIQUID_ACCOUNT_ADDRESS` | 自动派生 | 使用 API 钱包时必需 | + +### 配置示例 + +#### 测试网配置（推荐用于学习） + +```json +{ + "mcpServers": { + "hyperliquid": { + "command": "uvx", + "args": [ + "--python", + "3.13", + "--from", + "hyperliquid-mcp-python", + "hyperliquid-mcp", + "stdio" + ], + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0x1234567890abcdef...", + "HYPERLIQUID_TESTNET": "true" + } + } + } +} +``` + +#### 主网配置（用于实际交易） + +```json +{ + "mcpServers": { + "hyperliquid": { + "command": "uvx", + "args": [ + "--python", + "3.13", + "--from", + "hyperliquid-mcp-python", + "hyperliquid-mcp", + "stdio" + ], + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0x1234567890abcdef...", + "HYPERLIQUID_TESTNET": "false" + } + } + } +} +``` + +#### API 钱包配置 + +```json +{ + "mcpServers": { + "hyperliquid": { + "command": "uvx", + "args": [ + "--python", + "3.13", + "--from", + "hyperliquid-mcp-python", + "hyperliquid-mcp", + "stdio" + ], + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0xAPI钱包私钥", + "HYPERLIQUID_ACCOUNT_ADDRESS": "0x主账户地址", + "HYPERLIQUID_TESTNET": "true" + } + } + } +} +``` + +!!! warning "API 钱包重要提示" +使用 API 钱包时，`HYPERLIQUID_ACCOUNT_ADDRESS` **必须设置为主账户地址**，而非 API 钱包地址。 + +## 应用配置 + +### 1. 编辑配置文件 + +```bash +# macOS +nano ~/Library/Application\ Support/Claude/claude_desktop_config.json + +# 或使用文本编辑器 +open ~/Library/Application\ Support/Claude/claude_desktop_config.json +``` + +### 2. 粘贴配置 + +选择上面的一种配置方式，复制到文件中。 + +### 3. 保存并重启 Claude Desktop + +配置文件保存后，**完全退出并重启 Claude Desktop**。 + +### 4. 验证连接 + +重启后，Claude Desktop 会自动连接 MCP 服务器。 + +你可以在 Claude 中询问： + +``` +你能看到 HyperLiquid 相关的工具吗？ +``` + +或直接测试： + +``` +帮我查看一下 HyperLiquid 账户余额 +``` + +## 验证配置 + +### 检查服务器状态 + +在 Claude Desktop 中，服务器状态会显示在界面上： + +- ✅ **绿色点**：已连接 +- 🟡 **黄色点**：连接中 +- ❌ **红色点**：连接失败 + +### 测试基本功能 + +``` +# 1. 查看余额 +帮我查看账户余额 + +# 2. 获取市场数据 +BTC 现在的价格是多少？ + +# 3. 查看仓位 +我有哪些开仓？ +``` + +## 日志查看 + +### Claude Desktop 日志 + +查看 Claude Desktop 的 MCP 日志： + +**macOS**: + +```bash +tail -f ~/Library/Logs/Claude/mcp*.log +``` + +**Windows**: + +``` +%LOCALAPPDATA%\Claude\logs\mcp*.log +``` + +### 服务器日志 + +HyperLiquid MCP Server 的日志： + +```bash +# 在项目目录 +tail -f hyperliquid_mcp.log +``` + +## 常见问题 + +### 服务器无法连接 + +**问题**: Claude Desktop 显示服务器离线 + +**检查清单**: + +1. **路径是否正确** + + ```bash + # 验证路径存在 + ls /完整/路径/hyperliquid-mcp + ``` + +2. **命令是否可用** + + ```bash + # 测试 uv 命令 + which uv + + # 测试 hyperliquid-mcp 命令 + which hyperliquid-mcp + ``` + +3. **环境变量是否正确** + + ```json + { + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0x...", // 必须以 0x 开头 + "HYPERLIQUID_TESTNET": "true" // 注意是字符串 "true" + } + } + ``` + +4. **重启 Claude Desktop** + - 完全退出应用 + - 重新启动 + +### 私钥格式错误 + +**问题**: 认证失败 + +**解决方案**: + +```json +{ + "env": { + // ❌ 错误 + "HYPERLIQUID_PRIVATE_KEY": "1234567890abcdef...", + + // ✅ 正确 + "HYPERLIQUID_PRIVATE_KEY": "0x1234567890abcdef..." + } +} +``` + +### 找不到命令 + +**问题**: `command not found: hyperliquid-mcp` + +**解决方案**: + +使用 uvx 方式（推荐）： + +```json +{ + "command": "uvx", + "args": ["--from", "hyperliquid-mcp-python", "hyperliquid-mcp", "stdio"] +} +``` + +或使用本地开发版本： + +```json +{ + "command": "uv", + "args": ["--directory", "/完整/路径", "run", "hyperliquid-mcp", "stdio"] +} +``` + +### API 钱包无法使用 + +**问题**: 使用 API 钱包时操作失败 + +**解决方案**: + +必须同时设置账户地址： + +```json +{ + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0xAPI钱包私钥", + "HYPERLIQUID_ACCOUNT_ADDRESS": "0x主账户地址" // 必需！ + } +} +``` + +## 高级配置 + +### 多网络配置 + +可以同时配置测试网和主网： + +```json +{ + "mcpServers": { + "hyperliquid-testnet": { + "command": "uvx", + "args": ["--from", "hyperliquid-mcp-python", "hyperliquid-mcp", "stdio"], + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0x测试网私钥", + "HYPERLIQUID_TESTNET": "true" + } + }, + "hyperliquid-mainnet": { + "command": "uvx", + "args": ["--from", "hyperliquid-mcp-python", "hyperliquid-mcp", "stdio"], + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0x主网私钥", + "HYPERLIQUID_TESTNET": "false" + } + } + } +} +``` + +### 使用配置文件 + +除了环境变量，也可以使用 `.env` 文件： + +1. 在项目目录创建 `.env`： + + ```bash + HYPERLIQUID_PRIVATE_KEY=0x... + HYPERLIQUID_TESTNET=true + ``` + +2. 配置 Claude Desktop： + ```json + { + "mcpServers": { + "hyperliquid": { + "command": "uv", + "args": [ + "--directory", + "/完整/路径/hyperliquid-mcp", + "run", + "hyperliquid-mcp", + "stdio" + ] + } + } + } + ``` + +## 安全最佳实践 + +1. **使用测试网** + + ```json + "HYPERLIQUID_TESTNET": "true" + ``` + +2. **使用 API 钱包** + + - 访问 https://app.hyperliquid.xyz/API + - 生成专用 API 钱包 + - 权限受限，更安全 + +3. **定期轮换密钥** + + - 定期更换 API 钱包 + - 删除旧的配置 + +4. **保护配置文件** + ```bash + # 设置适当的文件权限 + chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json + ``` + +## 使用示例 + +### 查看账户信息 + +``` +你: 帮我查看账户余额和仓位 + +Claude: 我来帮您查看... +[调用 get_account_balance 和 get_open_positions] +``` + +### 下单交易 + +``` +你: 用 $100 买入 BTC + +Claude: 我来帮您计算并下单... +[调用 calculate_token_amount_from_dollars] +[调用 market_open_position] +``` + +### 设置止盈止损 + +``` +你: 为我的 BTC 仓位设置止盈 47000，止损 43000 + +Claude: 我来设置... +[调用 set_take_profit_stop_loss] +``` + +## 下一步 + +- [交易工具使用](trading-tools.md) - 学习如何使用各种交易工具 +- [账户管理](account-management.md) - 管理账户和仓位 +- [故障排除](../troubleshooting.md) - 解决常见问题 + +## 相关资源 + +- [Claude Desktop 文档](https://claude.ai/desktop) +- [MCP 协议规范](https://github.com/anthropics/mcp) +- [FastMCP 文档](https://fastmcp.com) diff --git a/docs/guides/trading-tools.md b/docs/guides/trading-tools.md new file mode 100644 index 0000000..aeb6dfb --- /dev/null +++ b/docs/guides/trading-tools.md @@ -0,0 +1,571 @@ +# 交易工具使用指南 + +本页面详细介绍如何使用 HyperLiquid MCP Server 的各种交易工具。 + +## 基础交易流程 + +### 1. 查看市场信息 + +在交易前，先获取市场数据： + +```python +# 获取 BTC 市场数据 +market_data = get_market_data("BTC") + +if market_data["success"]: + data = market_data["data"] + print(f"当前价格: ${data['mark_px']}") + print(f"24h 成交量: ${data['day_ntl_vlm']}") +``` + +### 2. 计算订单大小 + +**关键步骤**：将美元金额转换为代币数量 + +```python +# 想用 $100 买 BTC +calc = calculate_token_amount_from_dollars("BTC", 100.0) + +if calc["success"]: + token_amount = calc["token_amount"] + print(f"$100 = {token_amount} BTC") +``` + +### 3. 下单交易 + +```python +# 使用计算的代币数量下单 +order = market_open_position("BTC", "buy", token_amount) + +if order["success"]: + print(f"订单成功: {order['order_id']}") +``` + +## 市价交易 + +### 开仓 + +使用 `market_open_position()` 快速开仓： + +```python +# 计算代币数量 +calc = calculate_token_amount_from_dollars("ETH", 200.0) + +# 做多（买入） +long_order = market_open_position( + coin="ETH", + side="buy", # 做多 + size=calc["token_amount"] +) + +# 做空（卖出） +short_order = market_open_position( + coin="ETH", + side="sell", # 做空 + size=calc["token_amount"] +) +``` + +### 平仓 + +使用 `market_close_position()` 快速平仓： + +```python +# 关闭所有 BTC 仓位 +result = market_close_position("BTC") + +if result["success"]: + print(f"仓位已平: {result['message']}") +``` + +### 部分平仓 + +```python +# 平仓 50% +result = close_position("BTC", percentage=50.0) + +# 平仓 25% +result = close_position("ETH", percentage=25.0) +``` + +## 限价交易 + +### 基础限价单 + +```python +# 在 $45000 买入 0.1 BTC +order = place_limit_order( + coin="BTC", + side="buy", + size=0.1, + price=45000.0 +) +``` + +### Reduce-Only 订单 + +只减仓，不增加仓位： + +```python +# 只平仓的限价单 +order = place_limit_order( + coin="BTC", + side="sell", + size=0.05, + price=47000.0, + reduce_only=True # 只减仓 +) +``` + +### 带客户端 ID 的订单 + +用于追踪特定订单： + +```python +import secrets + +# 生成 128 位十六进制 ID +client_id = "0x" + secrets.token_hex(16) + +order = place_limit_order( + coin="ETH", + side="buy", + size=1.0, + price=3000.0, + client_order_id=client_id +) + +# 保存 client_id 用于后续追踪 +print(f"客户端订单 ID: {client_id}") +``` + +## 括号订单 + +一次性设置入场、止盈、止损： + +### 基础括号订单 + +```python +# 计算代币数量 +calc = calculate_token_amount_from_dollars("SOL", 100.0) + +# 入场 $150, 止盈 $160, 止损 $140 +order = place_bracket_order( + coin="SOL", + side="buy", + size=calc["token_amount"], + entry_price=150.0, # 入场价 + take_profit_price=160.0, # 止盈价 + stop_loss_price=140.0 # 止损价 +) + +if order["success"]: + result = order["bulk_result"] + print(f"入场订单: {result['entry_order']['order_id']}") + print(f"止盈订单: {result['take_profit_order']['order_id']}") + print(f"止损订单: {result['stop_loss_order']['order_id']}") +``` + +### 适用场景 + +括号订单适合： + +- ✅ 新开仓位 +- ✅ 一次性设置完整的交易计划 +- ✅ 自动化风险管理 + +不适合： + +- ❌ 现有仓位（使用 `set_take_profit_stop_loss`） +- ❌ 只想设置止盈或止损之一 + +## 止盈止损管理 + +### 为现有仓位设置 TP/SL + +```python +# 同时设置止盈和止损 +result = set_take_profit_stop_loss( + coin="BTC", + take_profit_price=47000.0, + stop_loss_price=43000.0 +) +``` + +### 只设置止盈 + +```python +result = set_take_profit("BTC", take_profit_price=47000.0) + +# 或 +result = set_take_profit_stop_loss( + coin="BTC", + take_profit_price=47000.0, + stop_loss_price=None +) +``` + +### 只设置止损 + +```python +result = set_stop_loss("BTC", stop_loss_price=43000.0) + +# 或 +result = set_take_profit_stop_loss( + coin="BTC", + take_profit_price=None, + stop_loss_price=43000.0 +) +``` + +### 修改 TP/SL + +要修改现有的止盈止损，需要先取消旧订单，再设置新的： + +```python +# 1. 取消现有的 TP/SL 订单 +cancel_all_orders("BTC") + +# 2. 设置新的 TP/SL +set_take_profit_stop_loss( + coin="BTC", + take_profit_price=48000.0, # 新止盈价 + stop_loss_price=42000.0 # 新止损价 +) +``` + +## 订单管理 + +### 查看开放订单 + +```python +orders = get_open_orders() + +if orders["success"]: + for order in orders["orders"]: + print(f"{order['coin']}: {order['side']} {order['sz']} @ ${order['limit_px']}") +``` + +### 取消单个订单 + +```python +# 按订单 ID 取消 +cancel_order("BTC", order_id=123456) + +# 按客户端订单 ID 取消 +cancel_order_by_client_id("BTC", client_order_id="0x1234...") +``` + +### 批量取消 + +```python +# 取消 BTC 的所有订单 +cancel_all_orders("BTC") + +# 取消所有币种的订单 +cancel_all_orders() +``` + +### 修改订单 + +```python +# 修改订单的价格和数量 +modify_order( + coin="ETH", + order_id=123456, + new_size=2.0, + new_price=3100.0 +) +``` + +## 实战示例 + +### 示例 1: 简单的市价买入 + +```python +# 1. 获取当前价格 +market = get_market_data("BTC") +current_price = float(market["data"]["mark_px"]) +print(f"BTC 当前价格: ${current_price}") + +# 2. 计算代币数量（用 $500） +calc = calculate_token_amount_from_dollars("BTC", 500.0) +token_amount = calc["token_amount"] +print(f"将买入: {token_amount} BTC") + +# 3. 市价开仓 +order = market_open_position("BTC", "buy", token_amount) + +if order["success"]: + print(f"✅ 订单成功") + print(f"成交均价: ${order['order_result']['avgPx']}") +else: + print(f"❌ 订单失败: {order['error']}") +``` + +### 示例 2: 带止盈止损的限价单 + +```python +# 1. 计算代币数量 +calc = calculate_token_amount_from_dollars("ETH", 300.0) + +# 2. 下括号订单 +order = place_bracket_order( + coin="ETH", + side="buy", + size=calc["token_amount"], + entry_price=3000.0, # 在 $3000 入场 + take_profit_price=3300.0, # 止盈 $3300 (+10%) + stop_loss_price=2850.0 # 止损 $2850 (-5%) +) + +if order["success"]: + print("✅ 括号订单已设置") + print(f"入场: $3000") + print(f"止盈: $3300 (+10%)") + print(f"止损: $2850 (-5%)") +``` + +### 示例 3: 追踪止损 + +手动实现追踪止损逻辑： + +```python +import time + +def trailing_stop_loss(coin, initial_stop_distance_pct=5.0, trail_distance_pct=3.0): + """ + 简单的追踪止损实现 + + Args: + coin: 交易对 + initial_stop_distance_pct: 初始止损距离百分比 + trail_distance_pct: 追踪距离百分比 + """ + # 获取当前仓位 + positions = get_open_positions() + position = next((p for p in positions["positions"] if p["coin"] == coin), None) + + if not position: + print(f"没有 {coin} 仓位") + return + + entry_price = float(position["entry_px"]) + position_size = abs(float(position["szi"])) + is_long = float(position["szi"]) > 0 + + # 计算初始止损价 + if is_long: + stop_loss = entry_price * (1 - initial_stop_distance_pct / 100) + else: + stop_loss = entry_price * (1 + initial_stop_distance_pct / 100) + + print(f"开始追踪止损 - 入场价: ${entry_price}, 初始止损: ${stop_loss}") + + highest_price = entry_price + + while True: + # 获取当前价格 + market = get_market_data(coin) + current_price = float(market["data"]["mark_px"]) + + if is_long: + # 做多：价格创新高，提升止损 + if current_price > highest_price: + highest_price = current_price + new_stop = highest_price * (1 - trail_distance_pct / 100) + + if new_stop > stop_loss: + stop_loss = new_stop + print(f"提升止损到: ${stop_loss:.2f}") + + # 更新止损订单 + set_stop_loss(coin, stop_loss_price=stop_loss) + + # 触发止损 + if current_price <= stop_loss: + print(f"触发止损！平仓价: ${current_price}") + market_close_position(coin) + break + + time.sleep(5) # 每 5 秒检查一次 +``` + +### 示例 4: 分批建仓 + +```python +def scale_in_position(coin, total_usd, num_orders=3): + """ + 分批建仓 + + Args: + coin: 交易对 + total_usd: 总投资金额 + num_orders: 分几批 + """ + # 获取当前价格 + market = get_market_data(coin) + current_price = float(market["data"]["mark_px"]) + + # 每批金额 + amount_per_order = total_usd / num_orders + + # 价格梯度（每次降低 1%） + price_step = 0.01 + + for i in range(num_orders): + # 计算每批的入场价 + entry_price = current_price * (1 - price_step * i) + + # 计算代币数量 + calc = calculate_token_amount_from_dollars(coin, amount_per_order) + + # 下限价单 + order = place_limit_order( + coin=coin, + side="buy", + size=calc["token_amount"], + price=entry_price + ) + + if order["success"]: + print(f"✅ 批次 {i+1}: ${amount_per_order} @ ${entry_price:.2f}") + else: + print(f"❌ 批次 {i+1} 失败: {order['error']}") + +# 使用: $1000 分 3 批买入 BTC +scale_in_position("BTC", 1000.0, num_orders=3) +``` + +### 示例 5: 网格交易 + +```python +def grid_trading(coin, grid_size=5, price_range_pct=5.0, amount_per_grid=100.0): + """ + 简单的网格交易策略 + + Args: + coin: 交易对 + grid_size: 网格数量 + price_range_pct: 价格范围百分比 + amount_per_grid: 每个网格的金额 + """ + # 获取当前价格 + market = get_market_data(coin) + mid_price = float(market["data"]["mark_px"]) + + # 计算价格范围 + upper_price = mid_price * (1 + price_range_pct / 100) + lower_price = mid_price * (1 - price_range_pct / 100) + price_step = (upper_price - lower_price) / grid_size + + print(f"设置网格交易:") + print(f"中间价: ${mid_price:.2f}") + print(f"范围: ${lower_price:.2f} - ${upper_price:.2f}") + + # 在中间价下方设置买单 + for i in range(grid_size // 2): + buy_price = mid_price - (i + 1) * price_step + calc = calculate_token_amount_from_dollars(coin, amount_per_grid) + + order = place_limit_order( + coin=coin, + side="buy", + size=calc["token_amount"], + price=buy_price + ) + print(f"买单 @ ${buy_price:.2f}") + + # 在中间价上方设置卖单 + for i in range(grid_size // 2): + sell_price = mid_price + (i + 1) * price_step + calc = calculate_token_amount_from_dollars(coin, amount_per_grid) + + order = place_limit_order( + coin=coin, + side="sell", + size=calc["token_amount"], + price=sell_price + ) + print(f"卖单 @ ${sell_price:.2f}") + +# 使用 +grid_trading("ETH", grid_size=6, price_range_pct=3.0, amount_per_grid=50.0) +``` + +## 最佳实践 + +### 1. 始终先计算代币数量 + +```python +# ❌ 错误 +order = market_open_position("SOL", "buy", 20.0) # 会买 20 个 SOL！ + +# ✅ 正确 +calc = calculate_token_amount_from_dollars("SOL", 20.0) +order = market_open_position("SOL", "buy", calc["token_amount"]) +``` + +### 2. 操作前检查状态 + +```python +# 检查余额 +balance = get_account_balance() +if balance["success"]: + available = float(balance["data"]["withdrawable"]) + if available < required_amount: + print("余额不足") + return + +# 检查仓位 +positions = get_open_positions() +# ... +``` + +### 3. 错误处理 + +```python +order = market_open_position("BTC", "buy", 0.1) + +if not order["success"]: + error_code = order.get("error_code") + + if error_code == "INSUFFICIENT_BALANCE": + print("余额不足，请充值") + elif error_code == "API_ERROR": + print("API 错误，稍后重试") + else: + print(f"错误: {order['error']}") +``` + +### 4. 使用止盈止损 + +```python +# 开仓时设置 +order = place_bracket_order(...) + +# 或开仓后立即设置 +order = market_open_position("BTC", "buy", 0.1) +if order["success"]: + set_take_profit_stop_loss("BTC", tp_price=47000, sl_price=43000) +``` + +### 5. 记录交易 + +```python +import logging + +logging.basicConfig(filename='trading.log', level=logging.INFO) + +# 记录每笔交易 +order = market_open_position("BTC", "buy", 0.1) +if order["success"]: + logging.info(f"开仓成功: BTC, size=0.1, id={order['order_id']}") +``` + +## 相关文档 + +- [API 参考](../api/tools-reference.md) - 完整的工具列表 +- [账户管理](account-management.md) - 管理账户和仓位 +- [错误处理](../api/error-handling.md) - 错误处理指南 +- [故障排除](../troubleshooting.md) - 常见问题解决 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..dce0351 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,147 @@ +# HyperLiquid MCP Server + +[![CI](https://github.com/talkincode/hyperliquid-mcp-python/actions/workflows/ci.yml/badge.svg)](https://github.com/talkincode/hyperliquid-mcp-python/actions/workflows/ci.yml) +[![PyPI version](https://badge.fury.io/py/hyperliquid-mcp-python.svg)](https://badge.fury.io/py/hyperliquid-mcp-python) +[![Python Versions](https://img.shields.io/pypi/pyversions/hyperliquid-mcp-python.svg)](https://pypi.org/project/hyperliquid-mcp-python/) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +基于 FastMCP 的 HyperLiquid 交易 MCP 服务器。为 AI 助手提供与 HyperLiquid 永续合约和现货交易平台交互的工具。 + +!!! success "致谢" +本项目 Fork 自 [GigabrainGG/hyperliquid-mcp](https://github.com/GigabrainGG/hyperliquid-mcp)，感谢原作者的出色工作！ + +## ✨ 主要功能 + +### 🚀 交易工具 + +- **市价订单**：使用 HyperLiquid 原生函数优化的开仓和平仓 +- **限价订单**：支持 reduce-only 和自定义订单 ID 追踪 +- **括号订单**：一键创建带止盈止损的新仓位（OCO 行为） +- **订单管理**：按 ID 或客户端 ID 取消订单、批量取消、修改订单 +- **仓位管理**：查看仓位、平仓（全部或部分）、获取盈亏信息 +- **高级止盈止损**：为现有仓位设置 OCO 止盈止损 + +### 📊 账户管理 + +- **余额信息**：获取账户余额和保证金详情 +- **仓位跟踪**：监控所有开仓及未实现盈亏 +- **交易历史**：查询成交记录和交易历史 +- **杠杆控制**：为不同资产更新杠杆设置 +- **资金划转**：在现货和合约账户间转移资金 + +### 📈 市场数据 + +- **实时价格**：获取当前市场数据，包括买卖价差 +- **订单簿**：获取可配置深度的实时订单簿数据 +- **资金费率**：访问历史资金费率信息 + +### 🛠️ 实用工具 + +- **账户总览**：获取账户综合概览 +- **美元转换**：根据当前价格计算代币数量 +- **仓位管理**：专用的现有仓位管理工具 + +## 🎯 快速开始 + +=== "使用 uvx（推荐）" + + **最简单的方式** - 无需安装，直接运行： + + ```bash + # 查看帮助 + uvx --python 3.13 --from hyperliquid-mcp-python hyperliquid-mcp --help + + # 启动 HTTP 服务器 + uvx --python 3.13 --from hyperliquid-mcp-python hyperliquid-mcp start + + # 启动 stdio 服务器（用于 MCP 客户端） + uvx --python 3.13 --from hyperliquid-mcp-python hyperliquid-mcp stdio + ``` + + !!! info "为什么指定 Python 3.13?" + 依赖包 `ckzg` 目前只提供到 Python 3.13 的预编译包，Python 3.14 还不支持。 + +=== "本地开发" + + ```bash + # 克隆仓库 + git clone https://github.com/talkincode/hyperliquid-mcp-python.git + cd hyperliquid-mcp-python + + # 安装依赖 + uv sync + + # 配置 + cp .env.example .env # 然后编辑 .env 文件 + + # 运行 + uv run hyperliquid-mcp # HTTP 模式 + uv run hyperliquid-mcp stdio # stdio 模式 + ``` + +=== "pip 安装" + + ```bash + # 使用 pip（需要 Python 3.10-3.13） + pip install hyperliquid-mcp-python + + # 运行 + hyperliquid-mcp --help + ``` + +## 📚 文档导航 + +
+ +- :material-rocket-launch:{ .lg .middle } **快速开始** + + *** + + 了解如何安装、配置和运行 HyperLiquid MCP Server + + [:octicons-arrow-right-24: 开始使用](getting-started/installation.md) + +- :material-book-open-variant:{ .lg .middle } **使用指南** + + *** + + 学习如何使用各种交易工具、管理账户和获取市场数据 + + [:octicons-arrow-right-24: 查看指南](guides/trading-tools.md) + +- :material-code-braces:{ .lg .middle } **API 参考** + + *** + + 完整的工具列表、参数说明和返回格式文档 + + [:octicons-arrow-right-24: API 文档](api/tools-reference.md) + +- :material-wrench:{ .lg .middle } **开发者文档** + + *** + + 了解架构设计、测试工具和如何贡献代码 + + [:octicons-arrow-right-24: 开发文档](developers/architecture.md) + +
+ +## ⚠️ 重要提示 + +!!! warning "安全建议" - 绝不提交包含私钥的 `.env` 文件 - **强烈建议先使用测试网**进行测试 - 建议使用 API 钱包：https://app.hyperliquid.xyz/API + +!!! danger "交易风险" +加密货币交易涉及重大风险。本项目仅供学习使用，请谨慎使用真实资金。 + +## 🔗 相关链接 + +- [HyperLiquid 文档](https://hyperliquid.gitbook.io/hyperliquid-docs/) +- [FastMCP](https://fastmcp.com) +- [MCP 协议](https://github.com/anthropics/mcp) +- [GitHub 仓库](https://github.com/talkincode/hyperliquid-mcp-python) +- [PyPI 包](https://pypi.org/project/hyperliquid-mcp-python/) + +## 📄 许可证 + +本项目采用 MIT 许可证 - 查看 [LICENSE](https://github.com/talkincode/hyperliquid-mcp-python/blob/main/LICENSE) 文件了解详情。 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..638f317 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,337 @@ +# 故障排除 + +本页面列出了常见问题及解决方案。 + +## 安装问题 + +### Python 版本不兼容 + +**问题**：使用 Python 3.14 时出现编译错误 + +**原因**：依赖包 `ckzg` 尚未提供 Python 3.14 预编译包 + +**解决方案**： + +```bash +# 使用 Python 3.13 +uvx --python 3.13 --from hyperliquid-mcp-python hyperliquid-mcp + +# 或使用 pyenv 切换版本 +pyenv install 3.13 +pyenv local 3.13 +``` + +### 命令未找到 + +**问题**：`hyperliquid-mcp: command not found` + +**解决方案**： + +```bash +# 检查是否已安装 +pip show hyperliquid-mcp-python + +# 使用完整路径 +python -m cli + +# 或使用 uvx +uvx --from hyperliquid-mcp-python hyperliquid-mcp +``` + +## 配置问题 + +### 私钥格式错误 + +**问题**：`Invalid private key format` + +**解决方案**： + +- 确保私钥以 `0x` 开头 +- 私钥长度为 66 个字符（含 `0x`） +- 示例：`0x1234...abcd`（64 个十六进制字符 + `0x`） + +### 找不到配置文件 + +**问题**：`Configuration file not found` + +**解决方案**： + +```bash +# 确保 .env 在项目根目录 +ls -la .env + +# 或使用环境变量 +export HYPERLIQUID_PRIVATE_KEY="0x..." +``` + +### API 钱包配置 + +**问题**：使用 API 钱包时无法操作 + +**解决方案**： + +```bash +# 必须同时设置账户地址 +HYPERLIQUID_PRIVATE_KEY=0x... # API 钱包私钥 +HYPERLIQUID_ACCOUNT_ADDRESS=0x... # 主账户地址 +``` + +## 连接问题 + +### 连接超时 + +**问题**：`Connection timeout` + +**解决方案**： + +1. 检查网络连接 +2. 确认防火墙设置 +3. 尝试更换网络 +4. 检查 HyperLiquid API 状态 + +### 认证失败 + +**问题**：`Authentication failed` + +**解决方案**： + +1. 验证私钥正确性 +2. 确认网络配置（测试网/主网） +3. 检查账户地址设置 +4. 重新生成 API 钱包 + +## 交易问题 + +### Size 参数错误 + +**问题**：订单大小不符合预期 + +**原因**：**`size` 参数表示代币数量，不是美元金额！** + +**示例**： + +```python +# ❌ 错误 - 这会尝试购买 20 个 SOL 代币，而非 $20 +market_open_position("SOL", "buy", 20.0) + +# ✅ 正确 - 先转换美元到代币数量 +calc = calculate_token_amount_from_dollars("SOL", 20.0) +market_open_position("SOL", "buy", calc["token_amount"]) +``` + +### 订单被拒绝 + +**问题**：`Order rejected` + +**可能原因**： + +1. 余额不足 +2. 订单大小低于最小值 +3. 价格偏离市场价过大 +4. 杠杆设置不当 + +**解决方案**： + +```bash +# 检查余额 +make test-balance + +# 查看市场数据 +uv run python test_scripts/test_market_data.py + +# 调整杠杆 +update_leverage("BTC", 5, True) +``` + +### 找不到仓位 + +**问题**：`Position not found` + +**原因**：尝试对不存在的仓位设置止盈止损 + +**解决方案**： + +```python +# 先检查是否有仓位 +positions = get_open_positions() + +# 确认仓位存在后再设置 TP/SL +if positions["data"]: + set_take_profit_stop_loss("BTC", tp_price=50000, sl_price=45000) +``` + +### OCO 订单组行为 + +**问题**：止盈止损订单未正确关联 + +**解决方案**： + +- **新仓位**：使用 `place_bracket_order()` 创建带 TP/SL 的入场订单 +- **现有仓位**：使用 `set_take_profit_stop_loss()` 为已有仓位设置 TP/SL + +```python +# ✅ 新仓位 - 使用 bracket 订单 +place_bracket_order("BTC", "buy", 0.1, 45000, 47000, 43000) + +# ✅ 现有仓位 - 使用专用函数 +set_take_profit_stop_loss("BTC", tp_price=47000, sl_price=43000) +``` + +## 测试问题 + +### 测试脚本运行失败 + +**问题**：无法运行测试脚本 + +**解决方案**： + +```bash +# 确保在项目根目录 +cd /path/to/hyperliquid-mcp-python + +# 使用 uv 运行 +uv run python test_scripts/test_connection.py + +# 或使用 Makefile +make test-quick +``` + +### 测试网余额为 0 + +**问题**：测试网账户无余额 + +**解决方案**： + +1. 访问 HyperLiquid 测试网 +2. 申请测试 USDC +3. 等待几分钟后再测试 + +## MCP 客户端集成问题 + +### Claude Desktop 无法连接 + +**问题**：Claude Desktop 显示服务器离线 + +**解决方案**： + +```json +// 检查 config.json 路径 +// ~/Library/Application Support/Claude/claude_desktop_config.json + +{ + "mcpServers": { + "hyperliquid": { + "command": "uv", + "args": [ + "--directory", + "/完整/绝对/路径/hyperliquid-mcp", + "run", + "hyperliquid-mcp", + "stdio" + ], + "env": { + "HYPERLIQUID_PRIVATE_KEY": "0x...", + "HYPERLIQUID_TESTNET": "true" + } + } + } +} +``` + +### 日志查看 + +**查看服务器日志**： + +```bash +# 主日志文件 +tail -f hyperliquid_mcp.log + +# Claude Desktop 日志 +tail -f ~/Library/Logs/Claude/mcp*.log +``` + +## 性能问题 + +### 响应缓慢 + +**可能原因**： + +1. 网络延迟 +2. API 限流 +3. 订单簿深度过大 + +**解决方案**： + +```python +# 减少订单簿深度 +get_orderbook("BTC", depth=10) # 而非 100 + +# 使用缓存的市场数据 +# 避免频繁调用 API +``` + +## 错误日志分析 + +### 启用详细日志 + +```python +# 在 main.py 中 +import logging +logging.basicConfig(level=logging.DEBUG) +``` + +### 常见错误代码 + +| 错误信息 | 原因 | 解决方案 | +| ---------------------- | ---------- | ------------------ | +| `Invalid signature` | 私钥错误 | 检查私钥配置 | +| `Insufficient balance` | 余额不足 | 充值或减少订单大小 | +| `Order size too small` | 订单太小 | 增加订单大小 | +| `Rate limit exceeded` | API 限流 | 减少请求频率 | +| `Position not found` | 仓位不存在 | 先开仓再操作 | + +## 获取帮助 + +如果以上方案无法解决问题： + +1. **查看日志**：`hyperliquid_mcp.log` +2. **运行诊断**：`make test-all` +3. **提交 Issue**：[GitHub Issues](https://github.com/talkincode/hyperliquid-mcp-python/issues) +4. **查看文档**：[完整文档](https://talkincode.github.io/hyperliquid-mcp-python/) + +## 诊断清单 + +运行完整诊断： + +```bash +# 1. 检查配置 +make config + +# 2. 测试连接 +make test-quick + +# 3. 检查余额 +make test-balance + +# 4. 测试市场数据 +make test-market + +# 5. 查看日志 +tail -f hyperliquid_mcp.log +``` + +## 常见误区 + +### ❌ 错误理解 + +1. **Size 是美元金额** → Size 是代币数量 +2. **可以直接修改 TP/SL** → 需要取消重新下单 +3. **测试网和主网通用** → 需要分别配置 +4. **API 钱包可以独立使用** → 需要主账户地址 + +### ✅ 正确理解 + +1. 使用 `calculate_token_amount_from_dollars()` 转换 +2. 使用专用的 TP/SL 管理函数 +3. 明确设置 `HYPERLIQUID_TESTNET` +4. API 钱包需配合主账户地址使用 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..edf00ee --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,106 @@ +site_name: HyperLiquid MCP Server +site_description: FastMCP-based trading server for HyperLiquid perpetual and spot trading +site_author: TalkingData +site_url: https://talkincode.github.io/hyperliquid-mcp-python/ + +repo_name: talkincode/hyperliquid-mcp-python +repo_url: https://github.com/talkincode/hyperliquid-mcp-python +edit_uri: edit/main/docs/ + +theme: + name: material + language: zh + palette: + # 浅色模式 + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/brightness-7 + name: 切换到暗色模式 + # 暗色模式 + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + accent: indigo + toggle: + icon: material/brightness-4 + name: 切换到浅色模式 + + features: + - navigation.tabs + - navigation.sections + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow + - content.code.copy + - content.code.annotate + + icon: + repo: fontawesome/brands/github + +plugins: + - search: + lang: + - zh + - en + - minify: + minify_html: true + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - admonition + - pymdownx.details + - pymdownx.emoji: + emoji_index: material.extensions.emoji.twemoji + emoji_generator: material.extensions.emoji.to_svg + - attr_list + - md_in_html + - tables + - toc: + permalink: true + +nav: + - 首页: index.md + - 快速开始: + - 安装: getting-started/installation.md + - 配置: getting-started/configuration.md + - 快速验证: getting-started/quick-start.md + - 使用指南: + - MCP 客户端集成: guides/mcp-integration.md + - 交易工具: guides/trading-tools.md + - 账户管理: guides/account-management.md + - 市场数据: guides/market-data.md + - 常见用例: guides/use-cases.md + - API 参考: + - 工具列表: api/tools-reference.md + - 返回格式: api/response-format.md + - 错误处理: api/error-handling.md + - 开发者: + - 贡献指南: developers/contributing.md + - 故障排除: troubleshooting.md + - 更新日志: changelog.md + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/talkincode/hyperliquid-mcp-python + - icon: fontawesome/brands/python + link: https://pypi.org/project/hyperliquid-mcp-python/ + + version: + provider: mike + +copyright: Copyright © 2024 TalkingData diff --git a/scripts/setup_docs.sh b/scripts/setup_docs.sh new file mode 100755 index 0000000..b17975d --- /dev/null +++ b/scripts/setup_docs.sh @@ -0,0 +1,42 @@ +#!/bin/bash + +# 文档网站快速设置脚本 + +set -e + +echo "📚 HyperLiquid MCP - 文档网站设置" +echo "==================================" +echo "" + +# 检查是否安装了 Python +if ! command -v python3 &> /dev/null; then + echo "❌ 未找到 Python 3" + echo "请先安装 Python 3.10 或更高版本" + exit 1 +fi + +echo "✅ Python 版本: $(python3 --version)" +echo "" + +# 安装文档依赖 +echo "📦 安装文档依赖..." +pip install -r docs-requirements.txt + +echo "" +echo "✅ 文档依赖安装完成！" +echo "" +echo "下一步：" +echo "" +echo "1. 本地预览文档：" +echo " make docs-serve" +echo " 或: mkdocs serve" +echo "" +echo "2. 构建文档：" +echo " make docs-build" +echo " 或: mkdocs build" +echo "" +echo "3. 部署到 GitHub Pages：" +echo " make docs-deploy" +echo " 或: mkdocs gh-deploy --force" +echo "" +echo "📖 访问 http://127.0.0.1:8000 查看文档" From 27892c44010b920eddcb5238b30af83e5c58986b Mon Sep 17 00:00:00 2001 From: Jett Wang Date: Tue, 28 Oct 2025 12:11:45 +0800 Subject: [PATCH 2/2] build: allow mkdocs emoji extensions --- .pre-commit-config.yaml | 1 + mkdocs.yml | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index aea48b3..7392575 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -20,6 +20,7 @@ repos: - id: trailing-whitespace # 删除行尾空格 - id: end-of-file-fixer # 确保文件以换行符结束 - id: check-yaml # 检查 YAML 语法 + args: ['--unsafe'] - id: check-added-large-files # 防止提交大文件 args: ['--maxkb=1000'] - id: check-merge-conflict # 检查合并冲突标记 diff --git a/mkdocs.yml b/mkdocs.yml index edf00ee..bb7884c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,8 +64,8 @@ markdown_extensions: - admonition - pymdownx.details - pymdownx.emoji: - emoji_index: material.extensions.emoji.twemoji - emoji_generator: material.extensions.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - attr_list - md_in_html - tables