# Byreal CLMM Copy Trade

Solana 链上 [byreal.io](https://byreal.io) DEX CLMM（集中流动性）跟单系统。监控目标钱包的流动性操作，自动复制开仓、加仓、减仓、关仓，并支持可配置的倍率和金额上限。

## 功能

- **实时监控** — WebSocket 订阅 + 轮询双模式，监听目标钱包的 CLMM 操作
- **自动跟单** — 检测到目标操作后自动复制（Open / Add / Decrease / Close）
- **智能换币** — 余额不足时通过 Jupiter Ultra API 自动 swap（ExactOut 模式，优先 USDC）
- **倍率控制** — 基于 USD 价值的倍率缩放，支持全局默认和单地址覆盖
- **关仓回收** — 关仓后自动将收到的代币 swap 回 USDC
- **Web 管理面板** — Dashboard、地址管理、仓位查看、操作历史、参数设置

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | Next.js 16 + React 19 + Tailwind CSS 4 + SWR |
| 后端 | Next.js API Routes |
| 数据库 | SQLite (better-sqlite3) |
| 区块链 | Solana Web3.js + Anchor 0.31 + Byreal CLMM SDK |
| 换币 | Jupiter Ultra API |

## 项目结构

```
src/
├── app/
│   ├── page.tsx                     # Dashboard（状态、余额、活跃仓位、最近操作）
│   ├── addresses/page.tsx           # 监控地址管理
│   ├── positions/page.tsx           # 仓位映射表
│   ├── history/page.tsx             # 跟单历史
│   ├── settings/page.tsx            # 全局参数设置
│   └── api/
│       ├── monitor/                 # 监控启停与状态
│       ├── addresses/route.ts       # 地址 CRUD
│       ├── positions/route.ts       # 仓位查询与手动关仓
│       ├── history/route.ts         # 操作历史
│       ├── settings/route.ts        # 设置读写
│       └── wallet/balance/route.ts  # 钱包余额
├── lib/
│   ├── monitor/                     # TX 监听与解析
│   │   ├── index.ts                 # MonitorService（WebSocket + 轮询）
│   │   ├── parser.ts                # TX 解析（IDL 判别符 + 日志匹配 + 事件解码）
│   │   └── types.ts                 # ParsedOperation 类型
│   ├── copier/                      # 跟单引擎
│   │   ├── index.ts                 # CopyEngine（四种操作调度）
│   │   ├── price.ts                 # 代币价格获取
│   │   ├── ratio.ts                 # 金额缩放
│   │   └── swap.ts                  # Jupiter Ultra swap（ExactIn / ExactOut）
│   ├── db/                          # SQLite 数据层
│   ├── solana/                      # RPC 连接 & 钱包
│   ├── pool-info.ts                 # 池子信息缓存（byreal API）
│   ├── config.ts                    # 环境变量加载
│   └── clmm-sdk/                    # Byreal CLMM SDK
└── components/layout/               # 侧边栏 & 顶部导航
```

## 快速开始

### 1. 安装依赖

```bash
pnpm install
```

### 2. 配置环境变量

```bash
cp .env.example .env.local
```

编辑 `.env.local`：

```env
SOL_ENDPOINT=https://api.mainnet-beta.solana.com   # Solana RPC（建议用付费节点）
SOL_SECRET_KEY=                                      # Base58 私钥
JUPITER_API_KEY=                                     # Jupiter API Key
COPY_MULTIPLIER=1.0                                  # 跟单倍率（1.0=等额，0.5=半仓）
COPY_MAX_USD=1000                                    # 单次跟单最大 USD
COPY_SLIPPAGE=0.02                                   # 默认滑点 2%
MONITOR_POLL_INTERVAL=5000                           # 轮询间隔(ms)
```

### 3. 启动

```bash
pnpm dev
```

访问 `http://localhost:3000`。

## 使用流程

1. **添加监控地址** — 在 Addresses 页面添加目标钱包地址
2. **启动监控** — 在 Dashboard 点击 Start 按钮
3. **自动跟单** — 系统检测到目标钱包的 CLMM 操作后自动复制
4. **查看仓位** — Dashboard 和 Positions 页面展示活跃仓位与价格区间
5. **手动关仓** — 点击仓位旁的 Close 按钮手动关闭
6. **查看历史** — History 页面展示所有操作记录与交易链接

## 跟单逻辑

### 操作类型

| 目标操作 | 跟单行为 |
|---------|---------|
| **Open Position** | 同池、同 tick 区间，按倍率缩放金额开仓，附带 referer memo |
| **Add Liquidity** | 通过 NFT 映射找到我方仓位，按倍率加仓 |
| **Decrease Liquidity** | 按目标减少量与我方流动性取较小值减仓 |
| **Close Position** | 全额减仓并关闭仓位，可选 swap 回 USDC |

### 金额计算

1. 获取代币 USD 价格
2. 计算目标仓位 USD 总值
3. `我方USD = min(目标USD * 倍率, 最大USD)`
4. `缩放比例 = 我方USD / 目标USD`
5. 按比例缩放 tokenA 和 tokenB 数量

### Swap 策略

- **开仓/加仓前**：检查余额，不足时用 USDC（ExactOut）补齐
- **关仓后**：将收到的非稳定币 swap 回 USDC（ExactIn）
- 稳定币（USDC、USDT、USD1）不触发 swap

## 数据库

SQLite 存储于 `data/copytrade.db`，包含四张表：

- **watched_addresses** — 监控地址（支持单独设置倍率和最大值）
- **position_mappings** — 目标 NFT → 我方 NFT 的仓位映射
- **copy_history** — 完整操作日志（含交易签名、金额、状态）
- **settings** — 全局配置键值对

## 设置项

| 参数 | 默认值 | 说明 |
|-----|-------|------|
| 跟单倍率 | 1.0 | 相对目标的金额倍数 |
| 最大 USD | 1000 | 单次操作上限 |
| 滑点 | 2% | 开仓/加仓 swap 滑点 |
| 轮询间隔 | 5000ms | 链上数据拉取频率 |
| 关仓换回 | 开启 | 关仓后是否 swap 回 USDC |

> 每个监控地址可单独覆盖倍率和最大 USD 设置。

## License

Private