# MEXC 定投交易机器人

## 项目简介

MEXC 定投交易机器人是一个自动化交易工具，用于在 MEXC 交易所执行现货定投交易。它通过 JSON 配置文件管理交易指令，支持多种订单类型，并自动记录交易日志。

## 主要功能

1. **配置文件管理**：从 JSON 文件读取交易指令
2. **灵活调度**：支持按日期执行交易（`*`表示每天执行）
3. **多种订单类型**：支持 limit（限价）、market（市价）、convert（闪兑）等订单类型
4. **智能价格获取**：当无 price 参数时自动获取实时价格作为限价
5. **自动计算数量**：limit 订单支持只提供 quoteOrderQty 自动计算 quantity
6. **闪兑交易**：convert 订单直接币币兑换，不走订单簿（buy 用 quoteOrderQty，sell 用 quantity）
7. **证券代码映射**：支持不同代码格式间的转换
8. **完整交易记录**：记录交易到 CSV 文件和日志

## 安装与使用

1. 创建配置文件`config/trading_config.json`（可有多个不同名字的`.json`文件，程序会自动遍历所有）
2. 运行程序：

    ```bash
    python main.py
    ```

## 配置文件

### 配置文件结构

配置文件采用 JSON 格式，命名为`trading_config.json`，基本结构如下：

```json
{
    "api": {
        "mexc_host": "https://api.mexc.com",
        "api_key": "mxxxxxxxxxx",
        "secret_key": "xxxxxxxxxxxxxxxxx"
    },
    "symbol_mapping": {
        "BTCUSDC": "BTCUSDT"
    },
    "trades": [
        {
            "symbol": "BTCUSDT",
            "order_type": "LIMIT",
            "side": "BUY",
            "execute_dates": ["*"],
            "params": {
                "quoteOrderQty": "100",
                "price": "50000"
            }
        }
    ]
}
```

### 配置字段详解

#### 1. API 配置 (`api`)

#### 2. 证券代码映射 (`symbol_mapping`)

- 类型：数组
- 描述：API 代码: CSV 记录代码，如`"BTCUSDC": "BTCUSDT"`代表向 API 请求`BTCUSDC`，但 CSV 中记录证券代码`BTCUSDT`

#### 3. 交易列表 (`trades`)

- 类型：数组
- 描述：包含所有交易指令的列表
- 每个交易指令是一个包含以下字段的对象：

##### 1. 交易对 (`symbol`)

- 类型：字符串
- 必填：是
- 示例：`"BTCUSDT"`
- 描述：要交易的货币对，如 BTC/USDT

##### 2. 订单类型 (`order_type`)

- 类型：字符串
- 必填：是
- 可选值：
  - `"limit"`：限价单
  - `"market"`：市价单
  - `"convert"`：闪兑（币币兑换，不走订单簿，见下方说明）

##### 3. 交易方向 (`side`)

- 类型：字符串
- 必填：是
- 可选值：
  - `"buy"`：买入
  - `"sell"`：卖出

##### 4. 执行日期 (`execute_dates`)

- 类型：数组
- 必填：是
- 特殊值：
  - `"*"`：表示每天执行
- 示例：
  - `["2023-01-01", "2023-01-15"]`：仅在指定日期执行
  - `["*"]`：每天执行
- 格式：YYYY-MM-DD

##### 5. 订单参数 (`params`)

- 类型：对象
- 必填：是
- 内容根据订单类型不同而变化：

**必须包含 `quantity` 或 `quoteOrderQty` 之一**

- `quantity`：交易数量（字符串格式的数字）
- `quoteOrderQty`：交易金额（字符串格式的数字）
- `price`：限价价格（字符串格式的数字），如果为空则自动获取最新价

> convert 闪兑订单的参数按方向区分，`quantity` / `quoteOrderQty` 至少提供一个：
> - `buy`：用计价币兑换基础币
>   - `quoteOrderQty`：指定花费金额（如 `"100"` 表示用 100 USDT 兑换）
>   - `quantity`：指定目标数量（如 `"0.01"` 表示兑换约 0.01 BTC，自动按实时价估算所需金额）
> - `sell`：用基础币兑换计价币
>   - `quantity`：指定卖出数量（如 `"0.5"` 表示卖出 0.5 ETH）
>   - `quoteOrderQty`：指定目标金额（如 `"2000"` 表示兑换到约 2000 USDT，自动按实时价估算卖出数量）
>
> convert 订单`symbol`需使用 `BASE/QUOTE` 格式，如 `"BTC/USDT"`。

### 配置示例

#### 示例 1：每日限价买入

```json
{
    "trades": [
        {
            "symbol": "BTCUSDT",
            "order_type": "LIMIT",
            "side": "BUY",
            "execute_dates": ["*"],
            "params": {
                "quoteOrderQty": "100",
                "price": "50000"
            }
        }
    ]
}
```

#### 示例 2：特定日期市价卖出

```json
{
    "trades": [
        {
            "symbol": "ETHUSDT",
            "order_type": "MARKET",
            "side": "SELL",
            "execute_dates": ["2023-12-25", "2023-12-31"],
            "params": {
                "quantity": "1.5"
            }
        }
    ]
}
```

#### 示例 3：每日闪兑买入

```json
{
    "trades": [
        {
            "symbol": "BTC/USDT",
            "order_type": "convert",
            "side": "buy",
            "execute_dates": ["*"],
            "params": {
                "quoteOrderQty": "100"
            }
        }
    ]
}
```

说明：每天用 100 USDT 通过闪兑兑换成 BTC（不走订单簿）。

#### 示例 4：闪兑卖出（按数量）

```json
{
    "trades": [
        {
            "symbol": "ETH/USDT",
            "order_type": "convert",
            "side": "sell",
            "execute_dates": ["2023-12-25"],
            "params": {
                "quantity": "0.5"
            }
        }
    ]
}
```

说明：在指定日期将 0.5 ETH 通过闪兑兑换成 USDT。

#### 示例 4b：闪兑买入（按目标数量自动估算金额）

```json
{
    "trades": [
        {
            "symbol": "BTC/USDT",
            "order_type": "convert",
            "side": "buy",
            "execute_dates": ["*"],
            "params": {
                "quantity": "0.01"
            }
        }
    ]
}
```

说明：每天按实时价估算约 0.01 BTC 所需 USDT，然后通过闪兑买入。

#### 示例 4c：闪兑卖出（按目标金额自动估算数量）

```json
{
    "trades": [
        {
            "symbol": "ETH/USDT",
            "order_type": "convert",
            "side": "sell",
            "execute_dates": ["2023-12-25"],
            "params": {
                "quoteOrderQty": "2000"
            }
        }
    ]
}
```

说明：在指定日期按实时价估算卖出 ETH，兑换到约 2000 USDT。

#### 示例 5：多种订单组合

```json
{
    "trades": [
        {
            "symbol": "BTCUSDT",
            "order_type": "LIMIT",
            "side": "BUY",
            "execute_dates": ["2023-12-01"],
            "params": {
                "quantity": "0.01",
                "price": "42000"
            }
        },
        {
            "symbol": "ETHUSDT",
            "order_type": "MARKET",
            "side": "SELL",
            "execute_dates": ["*"],
            "params": {
                "quoteOrderQty": "200"
            }
        }
    ]
}
```

### 注意事项

1. 价格和数量都使用字符串格式而非数字，以避免浮点数精度问题
2. 对于 `limit` 订单，可以只提供`quoteOrderQty`，系统会自动计算`quantity`
3. 当`execute_dates`包含`"*"`时，会忽略其他日期设置
4. 系统会自动创建`output`目录存放日志和交易记录
5. 所有时间均以系统时区为准
6. `order_type`、`side` 均为小写；`convert` 订单的`symbol`使用 `BASE/QUOTE` 格式
7. `convert` 闪兑产出的 CSV 备注为 `DCA Order ID (Convert): {id}`，`tool_csv_merge.py` 已兼容该格式

### 错误处理

如果配置文件格式错误，程序会记录错误并退出。常见错误包括：

- JSON 格式错误
- 缺少必填字段
- 日期格式不正确
- 订单参数不符合订单类型要求

## 输出文件

- `output/mexc_trading_bot.log`: 交易日志
- `output/mexc_spot_trade.csv`: 交易记录 CSV 文件

---