@catalyst-team/poly-sdk 0.2.1 → 0.3.0

package/README.zh-CN.md

@@ -1,236 +1,283 @@
 # @catalyst-team/poly-sdk
 
-[![English](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)
-[![中文](https://img.shields.io/badge/语言-中文-red.svg)](README.zh-CN.md)
-[![版本](https://img.shields.io/badge/版本-0.2.0-blue.svg)](package.json)
-[![许可](https://img.shields.io/badge/许可-MIT-green.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@catalyst-team/poly-sdk.svg)](https://www.npmjs.com/package/@catalyst-team/poly-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Polymarket 统一 TypeScript SDK - 预测市场交易、套利检测、聪明钱分析和完整市场数据。
+**Polymarket 统一 TypeScript SDK** - 交易、市场数据、聪明钱分析和链上操作。
 
 **开发者**: [@hhhx402](https://x.com/hhhx402) | **项目**: [Catalyst.fun](https://x.com/catalystdotfun)
 
-## 核心功能
+[English](README.md)
 
-- 🔄 **实时套利检测**: WebSocket 监控 + 自动执行
-- 📊 **聪明钱分析**: 追踪顶级交易者及其策略
-- 💱 **交易集成**: 支持 GTC/GTD/FOK/FAK 订单类型
-- 🔐 **链上操作**: Split、Merge、Redeem CTF 代币
-- 🌉 **跨链桥接**: 从 Ethereum、Solana、Bitcoin 充值
-- 💰 **DEX 交换**: 使用 QuickSwap V3 在 Polygon 上兑换代币
-- 📈 **市场分析**: K 线、信号、成交量分析
+---
 
-## 安装
+## 目录
 
-```bash
-pnpm add @catalyst-team/poly-sdk
-```
+- [概览](#概览)
+- [安装](#安装)
+- [架构](#架构)
+- [快速开始](#快速开始)
+- [服务指南](#服务指南)
+  - [PolymarketSDK (入口)](#polymarketsdk-入口)
+  - [TradingService](#tradingservice)
+  - [MarketService](#marketservice)
+  - [OnchainService](#onchainservice)
+  - [RealtimeServiceV2](#realtimeservicev2)
+  - [WalletService](#walletservice)
+  - [SmartMoneyService](#smartmoneyservice)
+  - [ArbitrageService](#arbitrageservice)
+- [底层客户端](#底层客户端)
+- [破坏性变更 (v0.3.0)](#破坏性变更-v030)
+- [示例](#示例)
+- [API 参考](#api-参考)
+- [许可证](#许可证)
 
-## 快速开始
+---
 
-```typescript
-import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+## 概览
 
-const sdk = new PolymarketSDK();
+`@catalyst-team/poly-sdk` 是一个全面的 TypeScript SDK，提供：
 
-// 通过 slug 或 condition ID 获取市场
-const market = await sdk.getMarket('will-trump-win-2024');
-console.log(market.tokens.yes.price); // 0.65
+- **交易** - 下限价单/市价单 (GTC, GTD, FOK, FAK)
+- **市场数据** - 实时价格、订单簿、K线、历史成交
+- **聪明钱分析** - 追踪顶级交易者、计算聪明分数、跟单策略
+- **链上操作** - CTF (split/merge/redeem)、授权、DEX 交换
+- **套利检测** - 实时套利扫描和执行
+- **WebSocket 推送** - 实时价格和订单簿更新
 
-// 获取处理后的订单簿（包含分析数据）
-const orderbook = await sdk.getOrderbook(market.conditionId);
-console.log(orderbook.summary.longArbProfit); // 套利机会
+### 核心功能
 
-// 检测套利
-const arb = await sdk.detectArbitrage(market.conditionId);
-if (arb) {
-  console.log(`${arb.type} 套利: ${arb.profit * 100}% 利润`);
-}
+| 功能 | 描述 |
+|------|------|
+| **统一 API** | 单一 SDK 访问所有 Polymarket API |
+| **类型安全** | 完整的 TypeScript 支持和类型定义 |
+| **速率限制** | 按 API 端点内置速率限制 |
+| **缓存** | 基于 TTL 的缓存，支持可插拔适配器 |
+| **错误处理** | 结构化错误和自动重试 |
+
+---
+
+## 安装
+
+```bash
+pnpm add @catalyst-team/poly-sdk
+
+# 或
+npm install @catalyst-team/poly-sdk
+
+# 或
+yarn add @catalyst-team/poly-sdk
 ```
 
+---
+
 ## 架构
 
+SDK 分为三层：
+
 ```
+poly-sdk 架构
+================================================================================
+
 ┌──────────────────────────────────────────────────────────────────────────────┐
-│                             PolymarketSDK                                     │
+│                              PolymarketSDK                                    │
+│                               (入口点)                                         │
 ├──────────────────────────────────────────────────────────────────────────────┤
-│  第三层: 服务层                                                                │
-│  ┌─────────────┐ ┌─────────────┐ ┌───────────────┐ ┌─────────────────────────┐│
-│  │钱包服务     │ │市场服务     │ │实时服务       │ │   授权服务              ││
-│  │ - 用户画像  │ │ - K 线     │ │- 订阅管理     │ │   - ERC20 授权          ││
-│  │ - 卖出检测  │ │ - 信号     │ │- 价格缓存     │ │   - ERC1155 授权        ││
-│  └─────────────┘ └─────────────┘ └───────────────┘ └─────────────────────────┘│
-│  ┌─────────────────────────────────────────────────────────────────────────┐  │
-│  │ 套利服务: 实时套利检测、自动再平衡、智能清仓                                │  │
-│  └─────────────────────────────────────────────────────────────────────────┘  │
-│  ┌─────────────────────────────────────────────────────────────────────────┐  │
-│  │ 交换服务: Polygon 上的 DEX 交换 (QuickSwap V3, USDC/USDC.e 转换)         │  │
-│  └─────────────────────────────────────────────────────────────────────────┘  │
+│                                                                               │
+│  第三层: 高级服务 (推荐使用)                                                    │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                                      │
+│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐                 │
+│  │  TradingService │ │  MarketService  │ │ OnchainService  │                 │
+│  │  ────────────── │ │  ────────────── │ │ ──────────────  │                 │
+│  │  • 限价单       │ │  • K线          │ │ • Split/Merge   │                 │
+│  │  • 市价单       │ │  • 订单簿       │ │ • Redeem        │                 │
+│  │  • 订单管理     │ │  • 价格历史     │ │ • 授权          │                 │
+│  │  • 奖励         │ │  • 套利检测     │ │ • 交换          │                 │
+│  └─────────────────┘ └─────────────────┘ └─────────────────┘                 │
+│                                                                               │
+│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐                 │
+│  │RealtimeServiceV2│ │  WalletService  │ │SmartMoneyService│                 │
+│  │  ────────────── │ │  ────────────── │ │ ──────────────  │                 │
+│  │  • WebSocket    │ │  • 用户画像     │ │ • 顶级交易者    │                 │
+│  │  • 价格推送     │ │  • 聪明分数     │ │ • 跟单交易      │                 │
+│  │  • 订单簿更新   │ │  • 卖出检测     │ │ • 信号检测      │                 │
+│  │  • 用户事件     │ │  • PnL 计算     │ │ • 排行榜        │                 │
+│  └─────────────────┘ └─────────────────┘ └─────────────────┘                 │
+│                                                                               │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │                        ArbitrageService                                  │ │
+│  │  ─────────────────────────────────────────────────────────────────────  │ │
+│  │  • 市场扫描    • 自动执行    • 再平衡器    • 智能清仓                      │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│                                                                               │
 ├──────────────────────────────────────────────────────────────────────────────┤
-│  第二层: API 客户端                                                           │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌────────────────────┐  │
-│  │ Data API │ │Gamma API │ │ CLOB API │ │ WebSocket │ │   跨链桥            │  │
-│  │持仓数据  │ │ 市场数据 │ │ 订单簿   │ │ 实时价格  │ │   跨链充值          │  │
-│  │交易记录  │ │ 事件数据 │ │ 交易     │ │ 价格推送  │ │   多链支持          │  │
-│  └──────────┘ └──────────┘ └──────────┘ └───────────┘ └────────────────────┘  │
-│  ┌──────────────────────────────────────┐ ┌────────────────────────────────┐  │
-│  │ 交易客户端: 订单执行                  │ │ CTF 客户端: 链上操作           │  │
-│  │ GTC/GTD/FOK/FAK, 奖励, 余额查询      │ │ Split / Merge / Redeem 代币    │  │
-│  └──────────────────────────────────────┘ └────────────────────────────────┘  │
+│                                                                               │
+│  第二层: 底层客户端 (高级用户 / 原始 API 访问)                                  │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                       │
+│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
+│  │GammaApiClnt│ │DataApiClnt │ │SubgraphClnt│ │ CTFClient  │ │BridgeClient│ │
+│  │ ────────── │ │ ────────── │ │ ────────── │ │ ────────── │ │ ────────── │ │
+│  │ • 市场     │ │ • 持仓     │ │ • 链上数据 │ │ • Split    │ │ • 跨链     │ │
+│  │ • 事件     │ │ • 交易     │ │ • PnL      │ │ • Merge    │ │   充值     │ │
+│  │ • 搜索     │ │ • 活动     │ │ • OI       │ │ • Redeem   │ │            │ │
+│  └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
+│                                                                               │
+│  使用官方 Polymarket 客户端:                                                   │
+│  • @polymarket/clob-client - 交易、订单簿、市场数据                            │
+│  • @polymarket/real-time-data-client - WebSocket 实时更新                     │
+│                                                                               │
 ├──────────────────────────────────────────────────────────────────────────────┤
-│  第一层: 基础设施                                                             │
-│  ┌────────────┐  ┌─────────┐  ┌──────────┐  ┌────────────┐ ┌──────────────┐   │
-│  │速率限制器  │  │  缓存   │  │  错误    │  │   类型     │ │ 价格工具     │   │
-│  │按 API 限制 │  │TTL 机制 │  │ 重试机制 │  │ 统一定义   │ │ 套利检测     │   │
-│  └────────────┘  └─────────┘  └──────────┘  └────────────┘ └──────────────┘   │
+│                                                                               │
+│  第一层: 核心基础设施                                                          │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━                                                │
+│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
+│  │ 速率限制器 │ │    缓存    │ │    错误    │ │    类型    │ │  价格工具  │ │
+│  │ ────────── │ │ ────────── │ │ ────────── │ │ ────────── │ │ ────────── │ │
+│  │ • 按 API   │ │ • 基于 TTL │ │ • 重试     │ │ • 统一     │ │ • 套利计算 │ │
+│  │ • Bottleneck│ │ • 可插拔   │ │ • 错误码   │ │ • K线      │ │ • 舍入     │ │
+│  └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
+│                                                                               │
 └──────────────────────────────────────────────────────────────────────────────┘
 ```
 
-## 核心概念
+### 服务职责
 
-### 理解 Polymarket 的镜像订单簿
+| 服务 | 职责 |
+|------|------|
+| **PolymarketSDK** | 入口点，整合所有服务 |
+| **TradingService** | 订单管理（下单/撤单/查询）|
+| **MarketService** | 市场数据（订单簿/K线/搜索）|
+| **OnchainService** | 链上操作（split/merge/redeem/授权/交换）|
+| **RealtimeServiceV2** | WebSocket 实时数据 |
+| **WalletService** | 钱包/交易者分析 |
+| **SmartMoneyService** | 聪明钱跟踪 |
+| **ArbitrageService** | 套利检测与执行 |
 
-⚠️ **关键：Polymarket 订单簿有一个容易被忽略的镜像特性**
+---
 
-```
-买 YES @ P = 卖 NO @ (1-P)
-```
+## 快速开始
 
-这意味着**同一订单会出现在两个订单簿中**。例如，一个 "卖 NO @ 0.50" 订单会同时作为 "买 YES @ 0.50" 出现在 YES 订单簿中。
+### 基础用法（只读）
 
-**常见错误：**
 ```typescript
-// ❌ 错误: 简单相加会重复计算镜像订单
-const askSum = YES.ask + NO.ask;  // ≈ 1.998-1.999，而非 ≈ 1.0
-const bidSum = YES.bid + NO.bid;  // ≈ 0.001-0.002，而非 ≈ 1.0
-```
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
 
-**正确做法：使用有效价格**
-```typescript
-import { getEffectivePrices, checkArbitrage } from '@catalyst-team/poly-sdk';
+// 只读操作无需认证
+const sdk = new PolymarketSDK();
 
-// 计算考虑镜像后的最优价格
-const effective = getEffectivePrices(yesAsk, yesBid, noAsk, noBid);
+// 通过 slug 或 condition ID 获取市场
+const market = await sdk.getMarket('will-trump-win-2024');
+console.log(`${market.question}`);
+console.log(`YES: ${market.tokens.find(t => t.outcome === 'Yes')?.price}`);
+console.log(`NO: ${market.tokens.find(t => t.outcome === 'No')?.price}`);
 
-// effective.effectiveBuyYes = min(YES.ask, 1 - NO.bid)
-// effective.effectiveBuyNo = min(NO.ask, 1 - YES.bid)
-// effective.effectiveSellYes = max(YES.bid, 1 - NO.ask)
-// effective.effectiveSellNo = max(NO.bid, 1 - YES.ask)
+// 获取处理后的订单簿（含分析数据）
+const orderbook = await sdk.getOrderbook(market.conditionId);
+console.log(`多头套利利润: ${orderbook.summary.longArbProfit}`);
+console.log(`空头套利利润: ${orderbook.summary.shortArbProfit}`);
 
-// 使用有效价格检测套利
-const arb = checkArbitrage(yesAsk, noAsk, yesBid, noBid);
+// 检测套利机会
+const arb = await sdk.detectArbitrage(market.conditionId);
 if (arb) {
-  console.log(`${arb.type} 套利: ${(arb.profit * 100).toFixed(2)}% 利润`);
-  console.log(arb.description);
+  console.log(`${arb.type.toUpperCase()} 套利: ${(arb.profit * 100).toFixed(2)}% 利润`);
+  console.log(arb.action);
 }
 ```
 
-详细文档见: [docs/01-polymarket-orderbook-arbitrage.md](docs/01-polymarket-orderbook-arbitrage.md)
-
-### ArbitrageService - 自动化交易
-
-实时套利检测和执行，支持市场扫描、自动再平衡和智能清仓。
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  核心功能                                                                     │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  • scanMarkets()     - 扫描市场找套利机会                                      │
-│  • start(market)     - 启动实时监控 + 自动执行                                 │
-│  • clearPositions()  - 智能清仓 (活跃市场卖出, 已结算市场 redeem)                │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  自动再平衡器                                                                  │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  套利需要 USDC + YES/NO 代币，再平衡器自动维持最佳组合：                         │
-│  • USDC < 20%  → 自动 Merge (YES+NO → USDC)                                 │
-│  • USDC > 80%  → 自动 Split (USDC → YES+NO)                                 │
-│  • 冷却机制：操作间隔 30 秒，检测间隔 10 秒                                      │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  部分成交保护                                                                  │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  套利需要同时买入 YES 和 NO，但订单可能部分成交：                                 │
-│  • sizeSafetyFactor=0.8 → 仅使用 80% 的订单簿深度                             │
-│  • autoFixImbalance=true → 如果只成交一侧，自动卖出多余的代币                   │
-│  • imbalanceThreshold=5 → YES-NO 差额超过 $5 时触发修复                        │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-**完整工作流：**
+### 带认证（交易）
 
 ```typescript
-import { ArbitrageService } from '@catalyst-team/poly-sdk';
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
 
-const arbService = new ArbitrageService({
-  privateKey: process.env.POLY_PRIVKEY,
-  profitThreshold: 0.005,  // 最小 0.5% 利润
-  minTradeSize: 5,         // 最小 $5
-  maxTradeSize: 100,       // 最大 $100
-  autoExecute: true,       // 自动执行套利机会
-
-  // 再平衡配置
-  enableRebalancer: true,  // 启用自动再平衡
-  minUsdcRatio: 0.2,       // 最小 20% USDC (低于则 Split)
-  maxUsdcRatio: 0.8,       // 最大 80% USDC (高于则 Merge)
-  targetUsdcRatio: 0.5,    // 再平衡目标 50%
-  imbalanceThreshold: 5,   // 修复前的最大 YES-NO 差额
-  rebalanceInterval: 10000, // 每 10 秒检查一次
-  rebalanceCooldown: 30000, // 操作间隔最小 30 秒
-
-  // 执行安全（防止部分成交导致 YES ≠ NO）
-  sizeSafetyFactor: 0.8,   // 使用 80% 的订单簿深度
-  autoFixImbalance: true,  // 如果一侧失败自动卖出多余部分
+// 推荐: 使用静态工厂方法（一行代码启动）
+const sdk = await PolymarketSDK.create({
+  privateKey: process.env.POLYMARKET_PRIVATE_KEY!,
 });
+// 准备好交易 - SDK 已初始化并连接 WebSocket
 
-// 监听事件
-arbService.on('opportunity', (opp) => {
-  console.log(`${opp.type.toUpperCase()} 套利: ${opp.profitPercent.toFixed(2)}%`);
+// 下限价单
+const order = await sdk.tradingService.createLimitOrder({
+  tokenId: yesTokenId,
+  side: 'BUY',
+  price: 0.45,
+  size: 10,
+  orderType: 'GTC',
 });
+console.log(`订单已下: ${order.id}`);
 
-arbService.on('execution', (result) => {
-  if (result.success) {
-    console.log(`✅ 已执行: $${result.profit.toFixed(2)} 利润`);
-  }
-});
+// 获取未成交订单
+const openOrders = await sdk.tradingService.getOpenOrders();
+console.log(`未成交订单: ${openOrders.length}`);
 
-// ========== 步骤 1: 扫描市场 ==========
-const results = await arbService.scanMarkets({ minVolume24h: 5000 }, 0.005);
-console.log(`找到 ${results.filter(r => r.arbType !== 'none').length} 个机会`);
+// 完成后清理
+sdk.stop();
+```
 
-// 或者一键扫描 + 启动最佳市场
-const best = await arbService.findAndStart(0.005);
-if (!best) {
-  console.log('未找到套利机会');
-  process.exit(0);
-}
-console.log(`🎯 已启动: ${best.market.name} (+${best.profitPercent.toFixed(2)}%)`);
+---
 
-// ========== 步骤 2: 运行套利 ==========
-// 服务现在自动监控并执行套利...
-await new Promise(resolve => setTimeout(resolve, 60 * 60 * 1000)); // 1 小时
+## 服务指南
 
-// ========== 步骤 3: 停止并清仓 ==========
-await arbService.stop();
-console.log('统计数据:', arbService.getStats());
+### PolymarketSDK (入口)
 
-// 智能清仓: 活跃市场 merge+sell, 已结算市场 redeem
-const clearResult = await arbService.clearPositions(best.market, true);
-console.log(`✅ 已回收: $${clearResult.totalUsdcRecovered.toFixed(2)}`);
+整合所有服务的主 SDK 类。
+
+```typescript
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+
+// ===== 方式 1: 静态工厂方法（推荐）=====
+// 一行搞定: new + initialize + connect + waitForConnection
+const sdk = await PolymarketSDK.create({
+  privateKey: '0x...', // 可选: 用于交易
+  chainId: 137,        // 可选: Polygon 主网（默认）
+});
+
+// ===== 方式 2: 使用 start() =====
+// const sdk = new PolymarketSDK({ privateKey: '0x...' });
+// await sdk.start();  // initialize + connect + waitForConnection
+
+// ===== 方式 3: 手动分步（完全控制）=====
+// const sdk = new PolymarketSDK({ privateKey: '0x...' });
+// await sdk.initialize();       // 初始化交易服务
+// sdk.connect();                // 连接 WebSocket
+// await sdk.waitForConnection(); // 等待连接完成
+
+// 访问服务
+sdk.tradingService  // 交易操作
+sdk.markets         // 市场数据
+sdk.wallets         // 钱包分析
+sdk.realtime        // WebSocket 实时数据
+sdk.smartMoney      // 聪明钱跟踪和跟单交易
+sdk.dataApi         // 直接访问 Data API
+sdk.gammaApi        // 直接访问 Gamma API
+sdk.subgraph        // 通过 Goldsky 访问链上数据
+
+// 便捷方法
+await sdk.getMarket(identifier);        // 获取统一市场
+await sdk.getOrderbook(conditionId);    // 获取处理后的订单簿
+await sdk.detectArbitrage(conditionId); // 检测套利机会
+
+// 清理
+sdk.stop();  // 断开所有服务
 ```
 
-## API 客户端
+---
+
+### TradingService
 
-### TradingClient - 订单执行
+使用 `@polymarket/clob-client` 进行订单管理。
 
 ```typescript
-import { TradingClient, RateLimiter } from '@catalyst-team/poly-sdk';
+import { TradingService } from '@catalyst-team/poly-sdk';
 
-const tradingClient = new TradingClient(new RateLimiter(), {
+const trading = new TradingService(rateLimiter, cache, {
   privateKey: process.env.POLYMARKET_PRIVATE_KEY!,
 });
+await trading.initialize();
 
-await tradingClient.initialize();
+// ===== 限价单 =====
 
-// GTC 限价单（保持有效直到成交或取消）
-const order = await tradingClient.createOrder({
+// GTC: 一直有效直到取消
+const gtcOrder = await trading.createLimitOrder({
   tokenId: yesTokenId,
   side: 'BUY',
   price: 0.45,
@@ -238,93 +285,199 @@ const order = await tradingClient.createOrder({
   orderType: 'GTC',
 });
 
-// FOK 市价单（完全成交或取消）
-const marketOrder = await tradingClient.createMarketOrder({
+// GTD: 有效期至指定时间
+const gtdOrder = await trading.createLimitOrder({
+  tokenId: yesTokenId,
+  side: 'BUY',
+  price: 0.45,
+  size: 10,
+  orderType: 'GTD',
+  expiration: Math.floor(Date.now() / 1000) + 3600, // 1 小时
+});
+
+// ===== 市价单 =====
+
+// FOK: 全部成交或取消
+const fokOrder = await trading.createMarketOrder({
   tokenId: yesTokenId,
   side: 'BUY',
   amount: 10, // $10 USDC
   orderType: 'FOK',
 });
 
-// 订单管理
-const openOrders = await tradingClient.getOpenOrders();
-await tradingClient.cancelOrder(orderId);
+// FAK: 部分成交也可以
+const fakOrder = await trading.createMarketOrder({
+  tokenId: yesTokenId,
+  side: 'SELL',
+  amount: 10, // 10 份额
+  orderType: 'FAK',
+});
+
+// ===== 订单管理 =====
+const openOrders = await trading.getOpenOrders();
+await trading.cancelOrder(orderId);
+await trading.cancelAllOrders();
+
+// ===== 奖励（做市激励）=====
+const isScoring = await trading.isOrderScoring(orderId);
+const rewards = await trading.getCurrentRewards();
+const earnings = await trading.getEarnings('2024-12-07');
+```
+
+---
+
+### MarketService
+
+市场数据、K线、订单簿分析。
+
+```typescript
+import { MarketService } from '@catalyst-team/poly-sdk';
+
+// 获取统一市场
+const market = await sdk.markets.getMarket('btc-100k-2024');
+
+// 获取 K 线
+const klines = await sdk.markets.getKLines(conditionId, '1h', { limit: 100 });
+
+// 获取双 K 线（YES + NO）含价差分析
+const dual = await sdk.markets.getDualKLines(conditionId, '1h');
+console.log(dual.yes);              // YES 代币蜡烛图
+console.log(dual.no);               // NO 代币蜡烛图
+console.log(dual.spreadAnalysis);   // 历史价差（成交价）
+console.log(dual.realtimeSpread);   // 实时价差（订单簿）
+
+// 获取处理后的订单簿
+const orderbook = await sdk.markets.getProcessedOrderbook(conditionId);
+
+// 快速实时价差检查
+const spread = await sdk.markets.getRealtimeSpread(conditionId);
+if (spread.longArbProfit > 0.005) {
+  console.log(`多头套利: 买 YES@${spread.yesAsk} + NO@${spread.noAsk}`);
+}
+
+// 检测市场信号
+const signals = await sdk.markets.detectMarketSignals(conditionId);
 ```
 
-### CTFClient - 链上代币操作
+#### 理解 Polymarket 订单簿
 
-CTF (Conditional Token Framework) 客户端支持 Polymarket 条件代币的链上操作。
+**重要**: Polymarket 订单簿有镜像特性：
 
 ```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  CTF 操作快速参考                                                              │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  操作       │ 功能                │ 典型用例                                   │
-├────────────┼─────────────────────┼────────────────────────────────────────────┤
-│  Split     │ USDC → YES + NO     │ 做市：创建代币库存                          │
-│  Merge     │ YES + NO → USDC     │ 套利：买入双边后合并                        │
-│  Redeem    │ 获胜代币 → USDC     │ 结算：领取获胜代币                          │
-└─────────────────────────────────────────────────────────────────────────────┘
+买 YES @ P = 卖 NO @ (1-P)
 ```
 
+这意味着**同一订单会出现在两个订单簿中**。简单相加会导致重复计算：
+
 ```typescript
-import { CTFClient } from '@catalyst-team/poly-sdk';
+// 错误: 重复计算镜像订单
+const askSum = YES.ask + NO.ask;  // ~1.998, 而非 ~1.0
 
-const ctf = new CTFClient({
+// 正确: 使用有效价格
+import { getEffectivePrices, checkArbitrage } from '@catalyst-team/poly-sdk';
+
+const effective = getEffectivePrices(yesAsk, yesBid, noAsk, noBid);
+// effective.effectiveBuyYes = min(YES.ask, 1 - NO.bid)
+// effective.effectiveBuyNo = min(NO.ask, 1 - YES.bid)
+
+const arb = checkArbitrage(yesAsk, noAsk, yesBid, noBid);
+if (arb) {
+  console.log(`${arb.type} 套利: ${(arb.profit * 100).toFixed(2)}% 利润`);
+}
+```
+
+---
+
+### OnchainService
+
+链上操作的统一接口：CTF + 授权 + 交换。
+
+```typescript
+import { OnchainService } from '@catalyst-team/poly-sdk';
+
+const onchain = new OnchainService({
   privateKey: process.env.POLYMARKET_PRIVATE_KEY!,
-  rpcUrl: 'https://polygon-rpc.com',
+  rpcUrl: 'https://polygon-rpc.com', // 可选
 });
 
-// Split: USDC → YES + NO 代币
-const splitResult = await ctf.split(conditionId, '100');
-console.log(`创建了 ${splitResult.yesTokens} YES + ${splitResult.noTokens} NO`);
-
-// Merge: YES + NO → USDC
-const tokenIds = {
-  yesTokenId: market.tokens[0].tokenId,
-  noTokenId: market.tokens[1].tokenId,
-};
-const mergeResult = await ctf.mergeByTokenIds(conditionId, tokenIds, '100');
-console.log(`收到 ${mergeResult.usdcReceived} USDC`);
-
-// Redeem: 获胜代币 → USDC
-const redeemResult = await ctf.redeemByTokenIds(conditionId, tokenIds);
-console.log(`兑换了 ${redeemResult.tokensRedeemed} 个代币`);
-```
+// 检查是否准备好进行 CTF 交易
+const status = await onchain.checkReadyForCTF('100');
+if (!status.ready) {
+  console.log('问题:', status.issues);
+  await onchain.approveAll();
+}
+
+// ===== CTF 操作 =====
+
+// Split: USDC -> YES + NO 代币
+const splitResult = await onchain.split(conditionId, '100');
+
+// Merge: YES + NO -> USDC（用于套利）
+const mergeResult = await onchain.mergeByTokenIds(conditionId, tokenIds, '100');
 
-⚠️ **重要：对 Polymarket 市场使用 `mergeByTokenIds()` 和 `redeemByTokenIds()`**
+// Redeem: 获胜代币 -> USDC（结算后）
+const redeemResult = await onchain.redeemByTokenIds(conditionId, tokenIds);
 
-Polymarket 使用的自定义 token ID 与标准 CTF position ID 不同。始终使用 `*ByTokenIds` 方法配合 CLOB API 返回的 token ID。
+// ===== DEX 交换 (QuickSwap V3) =====
+
+// 将 MATIC 交换为 USDC.e（CTF 需要）
+await onchain.swap('MATIC', 'USDC_E', '50');
+
+// 获取余额
+const balances = await onchain.getBalances();
+console.log(`USDC.e: ${balances.usdcE}`);
+```
 
-### SwapService - Polygon 上的 DEX 交换
+**注意**: Polymarket CTF 需要 **USDC.e** (0x2791...)，不是原生 USDC。
 
-使用 QuickSwap V3 在 Polygon 上交换代币。对于 CTF 操作，转换为 USDC.e 是必需的。
+---
 
-⚠️ **Polymarket CTF 的 USDC vs USDC.e**
+### RealtimeServiceV2
 
-| 代币 | 地址 | Polymarket CTF |
-|------|------|---------------|
-| USDC.e | `0x2791...` | ✅ **必需** |
-| USDC (原生) | `0x3c49...` | ❌ 不接受 |
+使用 `@polymarket/real-time-data-client` 的 WebSocket 实时数据。
 
 ```typescript
-import { SwapService, POLYGON_TOKENS } from '@catalyst-team/poly-sdk';
+import { RealtimeServiceV2 } from '@catalyst-team/poly-sdk';
 
-const swapService = new SwapService(signer);
+const realtime = new RealtimeServiceV2({
+  autoReconnect: true,
+  pingInterval: 5000,
+});
+
+// 连接并订阅
+realtime.connect();
+realtime.subscribeMarket([yesTokenId, noTokenId]);
+
+// 事件 API
+realtime.on('priceUpdate', (update) => {
+  console.log(`${update.assetId}: ${update.price}`);
+  console.log(`中间价: ${update.midpoint}, 价差: ${update.spread}`);
+});
 
-// 将原生 USDC 交换为 USDC.e 用于 CTF 操作
-const swapResult = await swapService.swap('USDC', 'USDC_E', '100');
-console.log(`已交换: ${swapResult.amountOut} USDC.e`);
+realtime.on('bookUpdate', (update) => {
+  // 订单簿自动规范化:
+  // bids: 降序（最佳在前）, asks: 升序（最佳在前）
+  console.log(`最佳买价: ${update.bids[0]?.price}`);
+  console.log(`最佳卖价: ${update.asks[0]?.price}`);
+});
+
+realtime.on('lastTrade', (trade) => {
+  console.log(`成交: ${trade.side} ${trade.size} @ ${trade.price}`);
+});
 
-// 将 MATIC 交换为 USDC.e
-const maticSwap = await swapService.swap('MATIC', 'USDC_E', '50');
+// 获取缓存价格
+const price = realtime.getPrice(yesTokenId);
+const book = realtime.getBook(yesTokenId);
 
-// 交换前获取报价
-const quote = await swapService.getQuote('WETH', 'USDC_E', '0.1');
-console.log(`预期输出: ${quote.estimatedAmountOut} USDC.e`);
+// 清理
+realtime.disconnect();
 ```
 
-### WalletService - 聪明钱分析
+---
+
+### WalletService
+
+钱包分析和聪明钱评分。
 
 ```typescript
 // 获取顶级交易者
@@ -332,171 +485,321 @@ const traders = await sdk.wallets.getTopTraders(10);
 
 // 获取钱包画像（含聪明分数）
 const profile = await sdk.wallets.getWalletProfile('0x...');
-console.log(profile.smartScore); // 0-100
+console.log(`聪明分数: ${profile.smartScore}/100`);
+console.log(`胜率: ${profile.winRate}%`);
+console.log(`总 PnL: $${profile.totalPnL}`);
 
 // 检测卖出活动（用于跟单策略）
 const sellResult = await sdk.wallets.detectSellActivity(
   '0x...',
   conditionId,
-  Date.now() - 24 * 60 * 60 * 1000
+  Date.now() - 24 * 60 * 60 * 1000 // 24小时前
 );
 if (sellResult.isSelling) {
   console.log(`已卖出 ${sellResult.percentageSold}%`);
 }
+
+// 跟踪群体卖出比例
+const groupSell = await sdk.wallets.trackGroupSellRatio(
+  ['0x...', '0x...'],
+  conditionId,
+  peakValue,
+  sinceTimestamp
+);
 ```
 
-### MarketService - K 线和信号
+---
+
+### SmartMoneyService
+
+聪明钱检测和**实时自动跟单交易**。
 
 ```typescript
-// 获取 K 线蜡烛图
-const klines = await sdk.markets.getKLines(conditionId, '1h', { limit: 100 });
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
 
-// 获取双 K 线（YES + NO）含价差分析
-const dual = await sdk.markets.getDualKLines(conditionId, '1h');
+// 一行代码启动（推荐）
+const sdk = await PolymarketSDK.create({ privateKey: '0x...' });
 
-// 历史价差（来自成交收盘价）- 用于回测
-for (const point of dual.spreadAnalysis) {
-  console.log(`${point.timestamp}: 总和=${point.priceSum}, 价差=${point.priceSpread}`);
-  if (point.arbOpportunity) {
-    console.log(`  历史 ${point.arbOpportunity} 信号`);
-  }
-}
+// ===== 自动跟单交易 =====
+// 实时跟单 - 聪明钱一旦交易，立即跟单
 
-// 实时价差（来自订单簿）- 用于实盘交易
-if (dual.realtimeSpread) {
-  const rt = dual.realtimeSpread;
-  if (rt.arbOpportunity) {
-    console.log(`🎯 ${rt.arbOpportunity} 套利: ${rt.arbProfitPercent.toFixed(2)}%`);
-  }
-}
-```
+const subscription = await sdk.smartMoney.startAutoCopyTrading({
+  // 目标选择
+  topN: 50,                    // 跟踪排行榜前 50 名
+  // targetAddresses: ['0x...'], // 或直接指定地址
 
-#### 价差分析 - 两种方法
+  // 订单设置
+  sizeScale: 0.1,              // 跟单 10% 的交易量
+  maxSizePerTrade: 10,         // 每笔最多 $10
+  maxSlippage: 0.03,           // 3% 滑点容忍度
+  orderType: 'FOK',            // FOK 或 FAK
 
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│  spreadAnalysis (历史分析)        │  realtimeSpread (实时交易)         │
-├─────────────────────────────────────────────────────────────────────────┤
-│  数据源: 成交收盘价                │  数据源: 订单簿 bid/ask             │
-│  YES_close + NO_close             │  使用有效价格（考虑镜像）            │
-├─────────────────────────────────────────────────────────────────────────┤
-│  ✅ 可构建历史图表                 │  ❌ 无历史数据*                      │
-│  ✅ Polymarket 保留成交历史        │  ❌ Polymarket 不保留快照           │
-│  ✅ 适合回测                       │  ✅ 适合实盘交易                     │
-│  ⚠️ 套利信号仅供参考               │  ✅ 套利利润计算准确                 │
-└─────────────────────────────────────────────────────────────────────────┘
-
-* 要构建历史实时价差，必须自己存储订单簿快照
-  参考: apps/api/src/services/spread-sampler.ts
+  // 过滤
+  minTradeSize: 5,             // 只跟单 > $5 的交易
+  sideFilter: 'BUY',           // 只跟单买入（可选）
+
+  // 测试模式
+  dryRun: true,                // 设为 false 执行真实交易
+
+  // 回调
+  onTrade: (trade, result) => {
+    console.log(`跟单 ${trade.traderName}: ${result.success ? '✅' : '❌'}`);
+  },
+  onError: (error) => console.error(error),
+});
+// 停止
+subscription.stop();
+sdk.stop();
+
+console.log(`正在跟踪 ${subscription.targetAddresses.length} 个钱包`);
+
+// 获取统计
+const stats = subscription.getStats();
+console.log(`检测: ${stats.tradesDetected}, 执行: ${stats.tradesExecuted}`);
+
+// 停止
+subscription.stop();
+sdk.stop();
 ```
 
-### RealtimeService - WebSocket 订阅
+> **注意**: Polymarket 最小订单金额为 **$1**。低于 $1 的订单会被自动跳过。
 
-⚠️ **重要：订单簿自动排序**
+📁 **完整示例**: 查看 [scripts/smart-money/](scripts/smart-money/) 获取完整可运行的脚本：
+- `04-auto-copy-trading.ts` - 完整功能的自动跟单
+- `05-auto-copy-simple.ts` - 简化的 SDK 用法
+- `06-real-copy-test.ts` - 真实交易测试
 
-Polymarket CLOB API 返回的订单簿顺序与标准预期相反：
-- **bids**: 升序（最低价在前 = 最差价）
-- **asks**: 降序（最高价在前 = 最差价）
+---
 
-我们的 SDK **自动规范化**订单簿数据：
-- **bids**: 降序（最高价在前 = 最佳买价）
-- **asks**: 升序（最低价在前 = 最佳卖价）
+### ArbitrageService
 
-这意味着你可以安全地使用 `bids[0]` 和 `asks[0]` 获取最优价格：
+实时套利检测、执行和仓位管理。
 
 ```typescript
-const book = await sdk.clobApi.getOrderbook(conditionId);
-const bestBid = book.bids[0]?.price;  // ✅ 最高买价（最佳）
-const bestAsk = book.asks[0]?.price;  // ✅ 最低卖价（最佳）
-
-// WebSocket 更新同样自动排序
-wsManager.on('bookUpdate', (update) => {
-  const bestBid = update.bids[0]?.price;  // ✅ 已排序
-  const bestAsk = update.asks[0]?.price;  // ✅ 已排序
+import { ArbitrageService } from '@catalyst-team/poly-sdk';
+
+const arbService = new ArbitrageService({
+  privateKey: process.env.POLY_PRIVKEY,
+  profitThreshold: 0.005,  // 最小 0.5% 利润
+  minTradeSize: 5,         // 最小 $5
+  maxTradeSize: 100,       // 最大 $100
+  autoExecute: true,       // 自动执行机会
+
+  // 再平衡器: 自动维持 USDC/代币比例
+  enableRebalancer: true,
+  minUsdcRatio: 0.2,       // 最小 20% USDC
+  maxUsdcRatio: 0.8,       // 最大 80% USDC
+  targetUsdcRatio: 0.5,    // 再平衡目标
+
+  // 执行安全
+  sizeSafetyFactor: 0.8,   // 使用 80% 订单簿深度
+  autoFixImbalance: true,  // 自动修复部分成交
+});
+
+// 监听事件
+arbService.on('opportunity', (opp) => {
+  console.log(`${opp.type.toUpperCase()} 套利: ${opp.profitPercent.toFixed(2)}%`);
+});
+
+arbService.on('execution', (result) => {
+  if (result.success) {
+    console.log(`已执行: $${result.profit.toFixed(2)} 利润`);
+  }
 });
+
+// ===== 工作流程 =====
+
+// 1. 扫描市场寻找机会
+const results = await arbService.scanMarkets({ minVolume24h: 5000 }, 0.005);
+
+// 2. 开始监控最佳市场
+const best = await arbService.findAndStart(0.005);
+console.log(`已启动: ${best.market.name} (+${best.profitPercent.toFixed(2)}%)`);
+
+// 3. 运行一段时间...
+await new Promise(r => setTimeout(r, 60 * 60 * 1000)); // 1 小时
+
+// 4. 停止并清仓
+await arbService.stop();
+const clearResult = await arbService.clearPositions(best.market, true);
+console.log(`已回收: $${clearResult.totalUsdcRecovered.toFixed(2)}`);
 ```
 
-## 示例
+---
+
+## 底层客户端
 
-| 示例 | 说明 | 命令 |
-|------|------|------|
-| [基础用法](examples/01-basic-usage.ts) | 获取市场、订单簿、检测套利 | `pnpm example:basic` |
-| [聪明钱](examples/02-smart-money.ts) | 顶级交易者、钱包画像、聪明分数 | `pnpm example:smart-money` |
-| [市场分析](examples/03-market-analysis.ts) | 市场信号、成交量分析 | `pnpm example:market-analysis` |
-| [K 线聚合](examples/04-kline-aggregation.ts) | 从成交记录构建 OHLCV 蜡烛图 | `pnpm example:kline` |
-| [跟单策略](examples/05-follow-wallet-strategy.ts) | 追踪聪明钱持仓、检测退出 | `pnpm example:follow-wallet` |
-| [服务演示](examples/06-services-demo.ts) | 所有 SDK 服务实战 | `pnpm example:services` |
-| [实时 WebSocket](examples/07-realtime-websocket.ts) | 实时价格推送、订单簿更新 | `pnpm example:realtime` |
-| [交易订单](examples/08-trading-orders.ts) | GTC、GTD、FOK、FAK 订单类型 | `pnpm example:trading` |
-| [奖励追踪](examples/09-rewards-tracking.ts) | 做市激励、收益 | `pnpm example:rewards` |
-| [CTF 操作](examples/10-ctf-operations.ts) | Split、merge、redeem 代币 | `pnpm example:ctf` |
-| [实时套利扫描](examples/11-live-arbitrage-scan.ts) | 扫描真实市场寻找机会 | `pnpm example:live-arb` |
-
-## 错误处理
+高级用户可直接访问 API：
 
 ```typescript
-import { PolymarketError, ErrorCode, withRetry } from '@catalyst-team/poly-sdk';
-
-try {
-  const market = await sdk.getMarket('invalid-slug');
-} catch (error) {
-  if (error instanceof PolymarketError) {
-    if (error.code === ErrorCode.MARKET_NOT_FOUND) {
-      console.log('市场未找到');
-    } else if (error.code === ErrorCode.RATE_LIMITED) {
-      console.log('速率限制，稍后重试');
-    }
-  }
-}
+import {
+  DataApiClient,    // 持仓、交易、排行榜
+  GammaApiClient,   // 市场、事件、搜索
+  SubgraphClient,   // 通过 Goldsky 访问链上数据
+  CTFClient,        // CTF 合约操作
+  BridgeClient,     // 跨链充值
+  SwapService,      // Polygon DEX 交换
+} from '@catalyst-team/poly-sdk';
+
+// Data API
+const positions = await sdk.dataApi.getPositions('0x...');
+const trades = await sdk.dataApi.getTrades('0x...');
+const leaderboard = await sdk.dataApi.getLeaderboard();
+
+// Gamma API
+const markets = await sdk.gammaApi.searchMarkets({ query: 'bitcoin' });
+const trending = await sdk.gammaApi.getTrendingMarkets(10);
+const events = await sdk.gammaApi.getEvents({ limit: 20 });
+
+// Subgraph（链上数据）
+const userPositions = await sdk.subgraph.getUserPositions(address);
+const isResolved = await sdk.subgraph.isConditionResolved(conditionId);
+const globalOI = await sdk.subgraph.getGlobalOpenInterest();
+```
 
-// 自动重试（指数退避）
-const result = await withRetry(() => sdk.getMarket(slug), {
-  maxRetries: 3,
-  baseDelay: 1000,
-});
+---
+
+## 破坏性变更 (v0.3.0)
+
+### `UnifiedMarket.tokens` 现在是数组
+
+**之前 (v0.2.x)**:
+```typescript
+// 带 yes/no 属性的对象
+const yesPrice = market.tokens.yes.price;
+const noPrice = market.tokens.no.price;
 ```
 
-## 速率限制
+**之后 (v0.3.0)**:
+```typescript
+// MarketToken 对象数组
+const yesToken = market.tokens.find(t => t.outcome === 'Yes');
+const noToken = market.tokens.find(t => t.outcome === 'No');
+
+const yesPrice = yesToken?.price;
+const noPrice = noToken?.price;
+```
 
-内置按 API 类型的速率限制：
-- Data API: 10 请求/秒
-- Gamma API: 10 请求/秒
-- CLOB API: 5 请求/秒
+### 迁移指南
 
 ```typescript
-import { RateLimiter, ApiType } from '@catalyst-team/poly-sdk';
+// 迁移辅助函数
+function getTokenPrice(market: UnifiedMarket, outcome: 'Yes' | 'No'): number {
+  return market.tokens.find(t => t.outcome === outcome)?.price ?? 0;
+}
 
-// 自定义速率限制器
-const limiter = new RateLimiter({
-  [ApiType.DATA]: { maxConcurrent: 5, minTime: 200 },
-  [ApiType.GAMMA]: { maxConcurrent: 5, minTime: 200 },
-  [ApiType.CLOB]: { maxConcurrent: 2, minTime: 500 },
-});
+// 使用
+const yesPrice = getTokenPrice(market, 'Yes');
+const noPrice = getTokenPrice(market, 'No');
 ```
 
-## 文档
+**为什么改变？** 数组格式更好地支持多结果市场，并且与 Polymarket API 响应格式更一致。
 
-- [订单簿与套利指南](docs/01-polymarket-orderbook-arbitrage.md) - 理解镜像订单
+---
 
-## 依赖
+## 示例
 
-- `@nevuamarkets/poly-websockets` - WebSocket 客户端
-- `bottleneck` - 速率限制
-- `ethers` - 区块链交互
+运行示例：
+
+```bash
+pnpm example:basic        # 基础用法
+pnpm example:smart-money  # 聪明钱分析
+pnpm example:trading      # 交易订单
+pnpm example:realtime     # WebSocket 推送
+pnpm example:arb-service  # 套利服务
+```
 
-## 许可
+| 示例 | 描述 |
+|------|------|
+| [01-basic-usage.ts](examples/01-basic-usage.ts) | 获取市场、订单簿、检测套利 |
+| [02-smart-money.ts](examples/02-smart-money.ts) | 顶级交易者、钱包画像、聪明分数 |
+| [03-market-analysis.ts](examples/03-market-analysis.ts) | 市场信号、成交量分析 |
+| [04-kline-aggregation.ts](examples/04-kline-aggregation.ts) | 从成交构建 OHLCV 蜡烛图 |
+| [05-follow-wallet-strategy.ts](examples/05-follow-wallet-strategy.ts) | 跟踪聪明钱、检测退出 |
+| [06-services-demo.ts](examples/06-services-demo.ts) | 所有 SDK 服务实战 |
+| [07-realtime-websocket.ts](examples/07-realtime-websocket.ts) | 实时价格推送、订单簿更新 |
+| [08-trading-orders.ts](examples/08-trading-orders.ts) | GTC、GTD、FOK、FAK 订单类型 |
+| [09-rewards-tracking.ts](examples/09-rewards-tracking.ts) | 做市激励、收益 |
+| [10-ctf-operations.ts](examples/10-ctf-operations.ts) | Split、merge、redeem 代币 |
+| [11-live-arbitrage-scan.ts](examples/11-live-arbitrage-scan.ts) | 扫描市场寻找机会 |
+| [12-trending-arb-monitor.ts](examples/12-trending-arb-monitor.ts) | 实时热门监控 |
+| [13-arbitrage-service.ts](examples/13-arbitrage-service.ts) | 完整套利工作流程 |
 
-MIT
+---
+
+## API 参考
+
+详细 API 文档见：
+
+- [docs/00-design.md](docs/00-design.md) - 架构设计
+- [docs/02-API.md](docs/02-API.md) - 完整 API 参考
+- [docs/01-polymarket-orderbook-arbitrage.md](docs/01-polymarket-orderbook-arbitrage.md) - 订单簿镜像与套利
+
+### 类型导出
 
-## 更新日志
+```typescript
+import type {
+  // 核心类型
+  UnifiedMarket,
+  MarketToken,
+  ProcessedOrderbook,
+  ArbitrageOpportunity,
+  EffectivePrices,
+
+  // 交易
+  Side,
+  OrderType,
+  Order,
+  OrderResult,
+  LimitOrderParams,
+  MarketOrderParams,
+
+  // K 线
+  KLineInterval,
+  KLineCandle,
+  DualKLineData,
+  SpreadDataPoint,
+
+  // WebSocket
+  PriceUpdate,
+  BookUpdate,
+  OrderbookSnapshot,
+
+  // 钱包
+  WalletProfile,
+  SellActivityResult,
+
+  // 聪明钱
+  SmartMoneyWallet,
+  SmartMoneyTrade,
+  AutoCopyTradingOptions,
+  AutoCopyTradingStats,
+  AutoCopyTradingSubscription,
+
+  // CTF
+  SplitResult,
+  MergeResult,
+  RedeemResult,
+
+  // 套利
+  ArbitrageMarketConfig,
+  ArbitrageServiceConfig,
+  ScanResult,
+  ClearPositionResult,
+} from '@catalyst-team/poly-sdk';
+```
 
-### v0.2.0 (2024-12-24)
+---
 
-- 📊 基于成交量和订单簿深度的智能市场选择
-- 🔧 ArbitrageService 验证和完善
+## 依赖
 
-### v0.1.1
+- `@polymarket/clob-client` - 官方 CLOB 交易客户端
+- `@polymarket/real-time-data-client` - 官方 WebSocket 客户端
+- `ethers@5` - 区块链交互
+- `bottleneck` - 速率限制
 
-- 初始套利服务实现
-- CTF 操作支持
-- 实时 WebSocket 监控
+---
+
+## 许可证
+
+MIT