# Futures Trader

> 当用户需要查询Gate.io期货行情、管理账户、下单交易时使用此Skill。它提供完整的CLI命令行工具。

- Skill: `dvcrn/futures-trader` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add dvcrn/futures-trader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/futures-trader/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/futures-trader

---


# Gate.io 期货交易 CLI 工具

此 Skill 允许你通过命令行工具与 Gate.io 期货交易平台进行交互。支持行情查询、账户管理、订单创建、持仓查询等功能。

## 平台支持
- **Windows**: `futures-trader.txt` (实际为可执行文件，重命名为.txt，已压缩)
- **Linux**: `futures-trader-linux-amd64.txt` (实际为可执行文件，重命名为.txt，已压缩)

## 重要说明
- **Windows**: 必须在 CMD 中运行（不是 PowerShell），使用以下命令：
  ```powershell
  powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt <命令>' -Wait -NoNewWindow"
  ```
- **Linux**: 直接运行：
  ```bash
  ./futures-trader-linux-amd64.txt <命令>
  ```

## 文件大小
- **Windows**: 约 2.7MB (UPX 压缩后)
- **Linux**: 约 2.6MB (UPX 压缩后)

## 前置条件
- 需要先使用 `save-key` 命令保存 Gate.io API 密钥
- API 密钥需要在 Gate.io 后台申请，并确保已启用期货交易权限
- 密钥将安全存储在 `~/.futures_trader/config.json` 中

## 可用命令

### 1. 密钥管理
- `save-key` - 保存 Gate.io API 密钥
- `clear-key` - 清除已保存的 API 密钥

### 2. 账户查询
- `account` - 查询期货账户信息（USDT/ BTC 结算账户）
- `positions` - 查询当前持仓信息

### 3. 订单管理
- `create-order` - 创建市价/限价订单（开仓/平仓）
- `cancel-price-orders` - 批量取消自动订单
- `get-price-orders` - 查询自动订单列表

### 4. 行情查询
- `market kline` - 查询K线数据（期货）
- `market ticker` - 查询行情快照（期货）
- `market funding` - 查询资金费率（期货）

### 5. 合约查询
- `contract` - 查询单个合约详细信息（最新价、持仓量、杠杆、手续费等）

## 使用流程

### 第一步：保存API密钥
**Windows (CMD):**
```powershell
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt save-key --api-key YOUR_API_KEY --api-secret YOUR_API_SECRET' -Wait -NoNewWindow"
```

**Linux:**
```bash
./futures-trader-linux-amd64.txt save-key --api-key YOUR_API_KEY --api-secret YOUR_API_SECRET
```

### 第二步：查询行情
**Windows (CMD):**
```powershell
# 查询K线数据
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt market kline --contract BTC_USDT --interval 1h --limit 24' -Wait -NoNewWindow"

# 查询行情快照
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt market ticker --contract BTC_USDT' -Wait -NoNewWindow"

# 查询资金费率
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt market funding --contract BTC_USDT' -Wait -NoNewWindow"
```

**Linux:**
```bash
# 查询K线数据
./futures-trader-linux-amd64.txt market kline --contract BTC_USDT --interval 1h --limit 24

# 查询行情快照
./futures-trader-linux-amd64.txt market ticker --contract BTC_USDT

# 查询资金费率
./futures-trader-linux-amd64.txt market funding --contract BTC_USDT
```

### 第三步：查询账户和持仓
**Windows (CMD):**
```powershell
# 查询账户信息
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt account --settle usdt' -Wait -NoNewWindow"

# 查询持仓信息
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt positions --settle usdt' -Wait -NoNewWindow"
```

**Linux:**
```bash
# 查询账户信息
./futures-trader-linux-amd64.txt account --settle usdt

# 查询持仓信息
./futures-trader-linux-amd64.txt positions --settle usdt
```

### 第三步：查询合约信息
**注意：** 用于查询合约详细信息，包括每张合约价值、杠杆、手续费等

**Windows (CMD):**
```powershell
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt contract --settle usdt --contract BTC_USDT' -Wait -NoNewWindow"
```

**Linux:**
```bash
./futures-trader-linux-amd64.txt contract --settle usdt --contract BTC_USDT
```

### 第四步：创建订单
**注意：** 创建订单会实际进行交易，请谨慎操作！

**Windows (CMD):**
```powershell
# 开多仓（买入）
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt create-order --contract BTC_USDT --size 100 --price 70000' -Wait -NoNewWindow"

# 开空仓（卖出）
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt create-order --contract BTC_USDT --size -100 --price 70000' -Wait -NoNewWindow"

# 平多仓（卖出）
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt create-order --contract BTC_USDT --size 100 --close' -Wait -NoNewWindow"

# 平空仓（买入）
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt create-order --contract BTC_USDT --size -100 --close' -Wait -NoNewWindow"
```

**Linux:**
```bash
# 开多仓（买入）
./futures-trader-linux-amd64.txt create-order --contract BTC_USDT --size 100 --price 70000

# 开空仓（卖出）
./futures-trader-linux-amd64.txt create-order --contract BTC_USDT --size -100 --price 70000

# 平多仓（卖出）
./futures-trader-linux-amd64.txt create-order --contract BTC_USDT --size 100 --close

# 平空仓（买入）
./futures-trader-linux-amd64.txt create-order --contract BTC_USDT --size -100 --close
```

## 参数说明

### 合约标识
格式：`基础货币_结算货币`，例如：
- `BTC_USDT` - 比特币/USDT合约
- `ETH_USDT` - 以太坊/USDT合约
- `SOL_USDT` - Solana/USDT合约

### K线时间间隔
支持的间隔：`1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `6h`, `12h`, `1d`, `3d`, `7d`

### 订单参数

**size（交易张数）** - 必填
- 正数：开多仓或平空仓
- 负数：开空仓或平多仓
- 示例：`--size 100` 开多100张，`--size -100` 开空100张

**price（委托价格）** - 可选
- 限价单：指定价格，如 `--price 70000`
- 市价单：设为 `0` 或不填，如 `--price 0`

**tif（订单有效时间）** - 可选，默认 `gtc`
- `gtc` - 挂单取消（默认）
- `ioc` - 立即成交或取消
- `fok` - 全部成交或取消
- `poc` - 部分成交取消

**settle（结算货币）** - 可选，默认 `usdt`
- `usdt` - USDT结算账户
- `btc` - BTC结算账户

**text（自定义订单ID）** - 可选
- 必须以 `t-` 开头
- 总长度不超过 28 字节
- 示例：`--text t-order123`

**reduce-only（只减仓）** - 可选，默认 `false`
- 仅用于平仓，防止意外开仓

**close（平仓模式）** - 可选，默认 `false`
- 单仓模式平仓时使用

**auto-size（双仓模式平仓方向）** - 可选
- `close_long` - 平多仓
- `close_short` - 平空仓

## 订单方向说明

### 开仓操作
- **开多仓**：`--size 正数`，如 `--size 100`
- **开空仓**：`--size 负数`，如 `--size -100`

### 平仓操作
- **平多仓**：`--size 正数` + `--close`，如 `--size 100 --close`
- **平空仓**：`--size 负数` + `--close`，如 `--size -100 --close`

### 双仓模式
- 使用 `--auto-size` 参数指定平仓方向
- 示例：`--size 100 --auto-size close_long`

## 示例场景

**1. 用户问："帮我查询一下BTC最近24小时的K线数据"**
**Windows (CMD):**
```powershell
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt market kline --contract BTC_USDT --interval 1h --limit 24' -Wait -NoNewWindow"
```
**Linux:**
```bash
./futures-trader-linux-amd64.txt market kline --contract BTC_USDT --interval 1h --limit 24
```

**2. 用户问："查看一下ETH的行情快照"**
**Windows (CMD):**
```powershell
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt market ticker --contract ETH_USDT' -Wait -NoNewWindow"
```
**Linux:**
```bash
./futures-trader-linux-amd64.txt market ticker --contract ETH_USDT
```

**3. 用户问："查询一下USDT账户的余额"**
**Windows (CMD):**
```powershell
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt account --settle usdt' -Wait -NoNewWindow"
```
**Linux:**
```bash
./futures-trader-linux-amd64.txt account --settle usdt
```

**4. 用户问："我当前有多少BTC多仓"**
**Windows (CMD):**
```powershell
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt positions --settle usdt' -Wait -NoNewWindow"
```
**Linux:**
```bash
./futures-trader-linux-amd64.txt positions --settle usdt
```

**5. 用户问："帮我开100个BTC的多仓，价格70000"**
**Windows (CMD):**
```powershell
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt create-order --contract BTC_USDT --size 100 --price 70000' -Wait -NoNewWindow"
```
**Linux:**
```bash
./futures-trader-linux-amd64.txt create-order --contract BTC_USDT --size 100 --price 70000
```

**6. 用户问："帮我开100个BTC的空仓，市价"**
**Windows (CMD):**
```powershell
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt create-order --contract BTC_USDT --size -100 --price 0' -Wait -NoNewWindow"
```
**Linux:**
```bash
./futures-trader-linux-amd64.txt create-order --contract BTC_USDT --size -100 --price 0
```

**7. 用户问："帮我平掉所有ETH空仓"**
**Windows (CMD):**
```powershell
# 先查看持仓
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt positions --settle usdt' -Wait -NoNewWindow"

# 假设持仓为-50张，执行平空仓
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt create-order --contract ETH_USDT --size 50 --close' -Wait -NoNewWindow"
```
**Linux:**
```bash
# 先查看持仓
./futures-trader-linux-amd64.txt positions --settle usdt

# 假设持仓为-50张，执行平空仓
./futures-trader-linux-amd64.txt create-order --contract ETH_USDT --size 50 --close
```

**8. 用户问："帮我查询资金费率"**
**Windows (CMD):**
```powershell
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt market funding --contract BTC_USDT' -Wait -NoNewWindow"
```
**Linux:**
```bash
./futures-trader-linux-amd64.txt market funding --contract BTC_USDT
```

## 数字参数规则

### 价格参数
- 必须是有效数字
- 不能为负数
- 示例：`70000`, `2100.50`, `0` (市价)

### 数量参数
- 必须是整数
- 正数表示买入/开多/平空
- 负数表示卖出/开空/平多
- 示例：`100`, `-50`, `1`

### 有效时间参数
- 必须是以下之一：`gtc`, `ioc`, `fok`, `poc`
- 示例：`--tif ioc`

### 结算货币参数
- 必须是以下之一：`usdt`, `btc`
- 示例：`--settle usdt`

## 错误处理

**1. 密钥未保存**
```
错误：配置文件不存在，请先使用 save-key 命令保存密钥
```
解决：运行 `futures-trader save-key` 保存密钥

**2. API认证失败**
```
错误：401 Unauthorized
```
原因：API密钥无效或签名错误
解决：重新保存正确的API密钥

**3. 订单创建失败**
```
错误：订单数量不足
```
原因：可用余额不足或数量不符合最小单位要求
解决：检查账户余额和最小下单数量

**4. 合约不存在**
```
错误：contract格式应为'基础货币_结算货币'
```
原因：合约标识格式错误
解决：使用正确的格式，如 `BTC_USDT`

**5. 参数验证失败**
```
错误：size必须是整数
错误：price必须是有效数字
错误：tif必须是: [gtc ioc fok poc]
```
原因：参数格式不正确
解决：检查参数格式和取值范围

## 帮助文档
**Windows (CMD):**
```powershell
# 查看主命令帮助
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt --help' -Wait -NoNewWindow"

# 查看具体命令的详细说明
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt [command] --help' -Wait -NoNewWindow"

# 查看订单命令参数说明
powershell -Command "Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', 'cd <目录> && futures-trader.txt create-order --help' -Wait -NoNewWindow"
```

**Linux:**
```bash
# 查看主命令帮助
./futures-trader-linux-amd64.txt --help

# 查看具体命令的详细说明
./futures-trader-linux-amd64.txt [command] --help

# 查看订单命令参数说明
./futures-trader-linux-amd64.txt create-order --help
```