@catalyst-team/poly-sdk 0.2.0 → 0.3.0

package/README.md

@@ -1,318 +1,283 @@
 # @catalyst-team/poly-sdk
 
-Unified SDK for Polymarket APIs - Data API, Gamma API, CLOB API, and WebSocket real-time updates.
+[![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)
 
-**Builder**: [@hhhx402](https://x.com/hhhx402)
-**Project**: [Catalyst.fun](https://x.com/catalystdotfun)
+**Unified TypeScript SDK for Polymarket** - Trading, market data, smart money analysis, and on-chain operations.
 
-## Installation
+**Builder**: [@hhhx402](https://x.com/hhhx402) | **Project**: [Catalyst.fun](https://x.com/catalystdotfun)
 
-```bash
-pnpm add @catalyst-team/poly-sdk
-```
+[中文文档](README.zh-CN.md)
 
-## Quick Start
+---
 
-```typescript
-import { PolymarketSDK } from '@catalyst-team/poly-sdk';
+## Table of Contents
 
-const sdk = new PolymarketSDK();
+- [Overview](#overview)
+- [Installation](#installation)
+- [Architecture](#architecture)
+- [Quick Start](#quick-start)
+- [Services Guide](#services-guide)
+  - [PolymarketSDK (Entry Point)](#polymarketsdk-entry-point)
+  - [TradingService](#tradingservice)
+  - [MarketService](#marketservice)
+  - [OnchainService](#onchainservice)
+  - [RealtimeServiceV2](#realtimeservicev2)
+  - [WalletService](#walletservice)
+  - [SmartMoneyService](#smartmoneyservice)
+  - [ArbitrageService](#arbitrageservice)
+- [Low-Level Clients](#low-level-clients)
+- [Breaking Changes (v0.3.0)](#breaking-changes-v030)
+- [Examples](#examples)
+- [API Reference](#api-reference)
+- [License](#license)
 
-// Get market by slug or condition ID
-const market = await sdk.getMarket('will-trump-win-2024');
-console.log(market.tokens.yes.price); // 0.65
+---
 
-// Get processed orderbook with analytics
-const orderbook = await sdk.getOrderbook(market.conditionId);
-console.log(orderbook.summary.longArbProfit); // Arbitrage opportunity
+## Overview
 
-// Detect arbitrage
-const arb = await sdk.detectArbitrage(market.conditionId);
-if (arb) {
-  console.log(`${arb.type} arb: ${arb.profit * 100}% profit`);
-}
-```
+`@catalyst-team/poly-sdk` is a comprehensive TypeScript SDK that provides:
 
-## Architecture
+- **Trading** - Place limit/market orders (GTC, GTD, FOK, FAK)
+- **Market Data** - Real-time prices, orderbooks, K-lines, historical trades
+- **Smart Money Analysis** - Track top traders, calculate smart scores, follow wallet strategies
+- **On-chain Operations** - CTF (split/merge/redeem), approvals, DEX swaps
+- **Arbitrage Detection** - Real-time arbitrage scanning and execution
+- **WebSocket Streaming** - Live price feeds and orderbook updates
 
-```
-┌──────────────────────────────────────────────────────────────────────────────┐
-│                             PolymarketSDK                                     │
-├──────────────────────────────────────────────────────────────────────────────┤
-│  Layer 3: Services                                                            │
-│  ┌─────────────┐ ┌─────────────┐ ┌───────────────┐ ┌─────────────────────────┐│
-│  │WalletService│ │MarketService│ │RealtimeService│ │   AuthorizationService  ││
-│  │ - profiles  │ │ - K-Lines   │ │- subscriptions│ │   - ERC20 approvals     ││
-│  │ - sell det. │ │ - signals   │ │- price cache  │ │   - ERC1155 approvals   ││
-│  └─────────────┘ └─────────────┘ └───────────────┘ └─────────────────────────┘│
-│  ┌─────────────────────────────────────────────────────────────────────────┐  │
-│  │ ArbitrageService: Real-time arbitrage detection, rebalancer, settlement │  │
-│  └─────────────────────────────────────────────────────────────────────────┘  │
-│  ┌─────────────────────────────────────────────────────────────────────────┐  │
-│  │ SwapService: DEX swaps on Polygon (QuickSwap V3, USDC/USDC.e conversion)│  │
-│  └─────────────────────────────────────────────────────────────────────────┘  │
-├──────────────────────────────────────────────────────────────────────────────┤
-│  Layer 2: API Clients                                                         │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌────────────────────┐  │
-│  │ DataAPI  │ │ GammaAPI │ │ CLOB API │ │ WebSocket │ │   BridgeClient     │  │
-│  │positions │ │ markets  │ │ orderbook│ │ real-time │ │   cross-chain      │  │
-│  │ trades   │ │ events   │ │ trading  │ │ prices    │ │   deposits         │  │
-│  └──────────┘ └──────────┘ └──────────┘ └───────────┘ └────────────────────┘  │
-│  ┌──────────────────────────────────────┐ ┌────────────────────────────────┐  │
-│  │ TradingClient: Order execution       │ │ CTFClient: On-chain operations │  │
-│  │ GTC/GTD/FOK/FAK, rewards, balances   │ │ Split / Merge / Redeem tokens  │  │
-│  └──────────────────────────────────────┘ └────────────────────────────────┘  │
-├──────────────────────────────────────────────────────────────────────────────┤
-│  Layer 1: Infrastructure                                                      │
-│  ┌────────────┐  ┌─────────┐  ┌──────────┐  ┌────────────┐ ┌──────────────┐   │
-│  │RateLimiter │  │  Cache  │  │  Errors  │  │   Types    │ │ Price Utils  │   │
-│  │per-API     │  │TTL-based│  │ retry    │  │ unified    │ │ arb detect   │   │
-│  └────────────┘  └─────────┘  └──────────┘  └────────────┘ └──────────────┘   │
-└──────────────────────────────────────────────────────────────────────────────┘
-```
+### Key Features
 
-## API Clients
+| Feature | Description |
+|---------|-------------|
+| **Unified API** | Single SDK for all Polymarket APIs |
+| **Type Safety** | Full TypeScript support with comprehensive types |
+| **Rate Limiting** | Built-in rate limiting per API endpoint |
+| **Caching** | TTL-based caching with pluggable adapters |
+| **Error Handling** | Structured errors with auto-retry |
 
-### DataApiClient - Positions, Trades, Leaderboard
+---
 
-```typescript
-// Get wallet positions
-const positions = await sdk.dataApi.getPositions('0x...');
+## Installation
 
-// Get recent trades
-const trades = await sdk.dataApi.getTrades('0x...');
+```bash
+pnpm add @catalyst-team/poly-sdk
 
-// Get leaderboard
-const leaderboard = await sdk.dataApi.getLeaderboard();
+# or
+npm install @catalyst-team/poly-sdk
+
+# or
+yarn add @catalyst-team/poly-sdk
 ```
 
-### GammaApiClient - Markets, Events
+---
 
-```typescript
-// Search markets
-const markets = await sdk.gammaApi.searchMarkets({ query: 'bitcoin' });
+## Architecture
 
-// Get trending markets
-const trending = await sdk.gammaApi.getTrendingMarkets(10);
+The SDK is organized into three layers:
 
-// Get events
-const events = await sdk.gammaApi.getEvents({ limit: 20 });
 ```
+poly-sdk Architecture
+================================================================================
 
-### ClobApiClient - Orderbook, Trading
-
-```typescript
-// Get orderbook
-const book = await sdk.clobApi.getOrderbook(conditionId);
-
-// Get processed orderbook with analytics
-const processed = await sdk.clobApi.getProcessedOrderbook(conditionId);
-console.log(processed.summary.longArbProfit);
-console.log(processed.summary.shortArbProfit);
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                              PolymarketSDK                                    │
+│                            (Entry Point)                                      │
+├──────────────────────────────────────────────────────────────────────────────┤
+│                                                                               │
+│  Layer 3: High-Level Services (Recommended)                                   │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                                      │
+│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐                 │
+│  │  TradingService │ │  MarketService  │ │ OnchainService  │                 │
+│  │  ────────────── │ │  ────────────── │ │ ──────────────  │                 │
+│  │  • Limit orders │ │  • K-lines      │ │ • Split/Merge   │                 │
+│  │  • Market orders│ │  • Orderbook    │ │ • Redeem        │                 │
+│  │  • Order mgmt   │ │  • Price history│ │ • Approvals     │                 │
+│  │  • Rewards      │ │  • Arbitrage    │ │ • Swaps         │                 │
+│  └─────────────────┘ └─────────────────┘ └─────────────────┘                 │
+│                                                                               │
+│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐                 │
+│  │RealtimeServiceV2│ │  WalletService  │ │SmartMoneyService│                 │
+│  │  ────────────── │ │  ────────────── │ │ ──────────────  │                 │
+│  │  • WebSocket    │ │  • Profiles     │ │ • Top traders   │                 │
+│  │  • Price feeds  │ │  • Smart scores │ │ • Copy trading  │                 │
+│  │  • Book updates │ │  • Sell detect  │ │ • Signal detect │                 │
+│  │  • User events  │ │  • PnL calc     │ │ • Leaderboard   │                 │
+│  └─────────────────┘ └─────────────────┘ └─────────────────┘                 │
+│                                                                               │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │                        ArbitrageService                                  │ │
+│  │  ─────────────────────────────────────────────────────────────────────  │ │
+│  │  • Market scanning  • Auto execution  • Rebalancer  • Smart clearing    │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│                                                                               │
+├──────────────────────────────────────────────────────────────────────────────┤
+│                                                                               │
+│  Layer 2: Low-Level Clients (Advanced Users / Raw API Access)                │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                       │
+│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
+│  │GammaApiClnt│ │DataApiClnt │ │SubgraphClnt│ │ CTFClient  │ │BridgeClient│ │
+│  │ ────────── │ │ ────────── │ │ ────────── │ │ ────────── │ │ ────────── │ │
+│  │ • Markets  │ │ • Positions│ │ • On-chain │ │ • Split    │ │ • Cross-   │ │
+│  │ • Events   │ │ • Trades   │ │ • PnL      │ │ • Merge    │ │   chain    │ │
+│  │ • Search   │ │ • Activity │ │ • OI       │ │ • Redeem   │ │ • Deposits │ │
+│  └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
+│                                                                               │
+│  Uses Official Polymarket Clients:                                           │
+│  • @polymarket/clob-client - Trading, orderbook, market data                 │
+│  • @polymarket/real-time-data-client - WebSocket real-time updates           │
+│                                                                               │
+├──────────────────────────────────────────────────────────────────────────────┤
+│                                                                               │
+│  Layer 1: Core Infrastructure                                                │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━                                                │
+│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
+│  │RateLimiter │ │   Cache    │ │   Errors   │ │   Types    │ │Price Utils │ │
+│  │ ────────── │ │ ────────── │ │ ────────── │ │ ────────── │ │ ────────── │ │
+│  │ • Per-API  │ │ • TTL-based│ │ • Retry    │ │ • Unified  │ │ • Arb calc │ │
+│  │ • Bottleneck│ │ • Pluggable│ │ • Codes    │ │ • K-lines  │ │ • Rounding │ │
+│  └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
+│                                                                               │
+└──────────────────────────────────────────────────────────────────────────────┘
 ```
 
-## Services
+### Service Responsibilities
 
-### WalletService - Smart Money Analysis
+| Service | Responsibility |
+|---------|---------------|
+| **PolymarketSDK** | Entry point, integrates all services |
+| **TradingService** | Order management (place/cancel/query) |
+| **MarketService** | Market data (orderbook/K-lines/search) |
+| **OnchainService** | On-chain ops (split/merge/redeem/approve/swap) |
+| **RealtimeServiceV2** | WebSocket real-time data |
+| **WalletService** | Wallet/trader analysis |
+| **SmartMoneyService** | Smart money tracking |
+| **ArbitrageService** | Arbitrage detection & execution |
 
-```typescript
-// Get top traders
-const traders = await sdk.wallets.getTopTraders(10);
-
-// Get wallet profile with smart score
-const profile = await sdk.wallets.getWalletProfile('0x...');
-console.log(profile.smartScore); // 0-100
+---
 
-// Detect sell activity (for follow-wallet strategy)
-const sellResult = await sdk.wallets.detectSellActivity(
-  '0x...',
-  conditionId,
-  Date.now() - 24 * 60 * 60 * 1000
-);
-if (sellResult.isSelling) {
-  console.log(`Sold ${sellResult.percentageSold}%`);
-}
-
-// Track group sell ratio
-const groupSell = await sdk.wallets.trackGroupSellRatio(
-  ['0x...', '0x...'],
-  conditionId,
-  peakValue,
-  sinceTimestamp
-);
-```
+## Quick Start
 
-### MarketService - K-Lines and Signals
+### Basic Usage (Read-Only)
 
 ```typescript
-// Get K-Line candles
-const klines = await sdk.markets.getKLines(conditionId, '1h', { limit: 100 });
-
-// Get dual K-Lines (YES + NO) with spread analysis
-const dual = await sdk.markets.getDualKLines(conditionId, '1h');
-console.log(dual.yes);              // YES token candles
-console.log(dual.no);               // NO token candles
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
 
-// Historical spread (from trade close prices) - for backtesting
-console.log(dual.spreadAnalysis);   // SpreadDataPoint[]
-for (const point of dual.spreadAnalysis) {
-  console.log(`${point.timestamp}: priceSum=${point.priceSum}, spread=${point.priceSpread}`);
-  if (point.arbOpportunity) {
-    console.log(`  Historical ${point.arbOpportunity} signal`);
-  }
-}
+// No authentication needed for read operations
+const sdk = new PolymarketSDK();
 
-// Real-time spread (from orderbook) - for live trading
-if (dual.realtimeSpread) {
-  const rt = dual.realtimeSpread;
-  console.log(`Ask Sum: ${rt.askSum} (spread: ${rt.askSpread})`);
-  console.log(`Bid Sum: ${rt.bidSum} (spread: ${rt.bidSpread})`);
-  if (rt.arbOpportunity) {
-    console.log(`🎯 ${rt.arbOpportunity} ARB: ${rt.arbProfitPercent.toFixed(2)}% profit`);
-  }
-}
+// Get market by slug or 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}`);
 
-// Quick real-time spread check (without K-lines)
-const spread = await sdk.markets.getRealtimeSpread(conditionId);
-if (spread.longArbProfit > 0.005) {
-  console.log(`Long arb: buy YES@${spread.yesAsk} + NO@${spread.noAsk}`);
-}
+// Get processed orderbook with analytics
+const orderbook = await sdk.getOrderbook(market.conditionId);
+console.log(`Long Arb Profit: ${orderbook.summary.longArbProfit}`);
+console.log(`Short Arb Profit: ${orderbook.summary.shortArbProfit}`);
 
-// Detect market signals
-const signals = await sdk.markets.detectMarketSignals(conditionId);
-for (const signal of signals) {
-  console.log(`${signal.type}: ${signal.severity}`);
+// Detect arbitrage opportunities
+const arb = await sdk.detectArbitrage(market.conditionId);
+if (arb) {
+  console.log(`${arb.type.toUpperCase()} ARB: ${(arb.profit * 100).toFixed(2)}% profit`);
+  console.log(arb.action);
 }
-
-// Detect arbitrage
-const arb = await sdk.markets.detectArbitrage(conditionId);
 ```
 
-#### Understanding Polymarket Orderbook & Arbitrage
+### With Authentication (Trading)
 
-⚠️ **重要：Polymarket 订单簿的镜像特性**
+```typescript
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
 
-Polymarket 的订单簿有一个关键特性容易被忽略：
+// Recommended: Use static factory method (one line to get started)
+const sdk = await PolymarketSDK.create({
+  privateKey: process.env.POLYMARKET_PRIVATE_KEY!,
+});
+// Ready to trade - SDK is initialized and WebSocket connected
 
-```
-买 YES @ P = 卖 NO @ (1-P)
-```
+// Place a limit order
+const order = await sdk.tradingService.createLimitOrder({
+  tokenId: yesTokenId,
+  side: 'BUY',
+  price: 0.45,
+  size: 10,
+  orderType: 'GTC',
+});
+console.log(`Order placed: ${order.id}`);
 
-这意味着**同一订单会在两个订单簿中出现**。例如，一个 "Sell NO @ 0.50" 订单
-会同时作为 "Buy YES @ 0.50" 出现在 YES 订单簿中。
+// Get open orders
+const openOrders = await sdk.tradingService.getOpenOrders();
+console.log(`Open orders: ${openOrders.length}`);
 
-**常见误解：**
-```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
+// Clean up when done
+sdk.stop();
 ```
 
-**正确做法：使用有效价格 (Effective Prices)**
-```typescript
-import { getEffectivePrices, checkArbitrage } from '@catalyst-team/poly-sdk';
+---
 
-// 计算考虑镜像后的最优价格
-const effective = getEffectivePrices(yesAsk, yesBid, noAsk, noBid);
+## Services Guide
 
-// 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)
+### PolymarketSDK (Entry Point)
 
-// 使用有效价格检测套利
-const arb = checkArbitrage(yesAsk, noAsk, yesBid, noBid);
-if (arb) {
-  console.log(`${arb.type} arb: ${(arb.profit * 100).toFixed(2)}% profit`);
-  console.log(arb.description);
-}
-```
+The main SDK class that integrates all services.
 
-详细文档见: [docs/01-polymarket-orderbook-arbitrage.md](docs/01-polymarket-orderbook-arbitrage.md)
+```typescript
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
 
-#### Spread Analysis - Two Approaches
+// ===== Method 1: Static Factory (Recommended) =====
+// One line: new + initialize + connect + waitForConnection
+const sdk = await PolymarketSDK.create({
+  privateKey: '0x...', // Optional: for trading
+  chainId: 137,        // Optional: Polygon mainnet (default)
+});
 
-我们提供两种 Spread 分析方式，核心区别如下：
+// ===== Method 2: Using start() =====
+// const sdk = new PolymarketSDK({ privateKey: '0x...' });
+// await sdk.start();  // initialize + connect + waitForConnection
 
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│  spreadAnalysis (历史分析)           │  realtimeSpread (实时分析)        │
-├─────────────────────────────────────────────────────────────────────────┤
-│  数据源: 成交记录的收盘价             │  数据源: 订单簿的最优 bid/ask     │
-│  YES_close + NO_close               │  使用有效价格 (考虑镜像订单)       │
-├─────────────────────────────────────────────────────────────────────────┤
-│  ✅ 可构建历史曲线                   │  ❌ 无法构建历史曲线*              │
-│  ✅ Polymarket 保留成交历史          │  ❌ Polymarket 不保留盘口历史     │
-│  ✅ 适合回测、模式识别               │  ✅ 适合实盘交易、套利执行         │
-│  ⚠️ 套利信号仅供参考                 │  ✅ 套利利润计算准确              │
-└─────────────────────────────────────────────────────────────────────────┘
-
-* 如需构建实时 Spread 的历史曲线，必须自行存储盘口快照数据
-  参考: apps/api/src/services/spread-sampler.ts
-```
+// ===== Method 3: Manual Step-by-Step (Full Control) =====
+// const sdk = new PolymarketSDK({ privateKey: '0x...' });
+// await sdk.initialize();       // Initialize trading service
+// sdk.connect();                // Connect WebSocket
+// await sdk.waitForConnection(); // Wait for connection
 
-**核心区别：**
+// Access services
+sdk.tradingService  // Trading operations
+sdk.markets         // Market data
+sdk.wallets         // Wallet analysis
+sdk.realtime        // WebSocket real-time data
+sdk.smartMoney      // Smart money tracking & copy trading
+sdk.dataApi         // Direct Data API access
+sdk.gammaApi        // Direct Gamma API access
+sdk.subgraph        // On-chain data via Goldsky
 
-1. **成交价 vs 盘口价**
-   - 成交价 (close): 过去某时刻实际成交的价格
-   - 盘口价 (bid/ask): 当前市场上的最优挂单价格
-   - 例: YES 最后成交 0.52，但当前 bid=0.50, ask=0.54
+// Convenience methods
+await sdk.getMarket(identifier);        // Get unified market
+await sdk.getOrderbook(conditionId);    // Get processed orderbook
+await sdk.detectArbitrage(conditionId); // Detect arb opportunity
 
-2. **为什么套利计算需要有效价格？**
-   - 同一订单在 YES 和 NO 订单簿中都有镜像
-   - 简单的 `YES.ask + NO.ask` 会重复计算
-   - 必须用 `min(YES.ask, 1-NO.bid)` 等公式消除重复
+// Clean up
+sdk.stop();  // Disconnect all services
+```
 
-3. **为什么历史分析只能用成交价？**
-   - Polymarket CLOB API 不保存历史盘口数据
-   - 只有成交记录 (trades) 有历史
-   - 除非你自己运行 spread-sampler 持续采样盘口
+---
 
-```typescript
-// SpreadDataPoint (历史分析 - 可构建曲线)
-interface SpreadDataPoint {
-  timestamp: number;
-  yesPrice: number;      // YES 收盘价 (来自成交记录)
-  noPrice: number;       // NO 收盘价
-  priceSum: number;      // YES + NO
-  priceSpread: number;   // priceSum - 1 (偏离均衡程度)
-  arbOpportunity: 'LONG' | 'SHORT' | '';  // 参考信号
-}
-
-// ProcessedOrderbook.summary (实时分析 - 使用有效价格)
-interface OrderbookSummary {
-  // 有效价格 (考虑镜像订单)
-  effectivePrices: {
-    effectiveBuyYes: number;   // min(YES.ask, 1 - NO.bid)
-    effectiveBuyNo: number;    // min(NO.ask, 1 - YES.bid)
-    effectiveSellYes: number;  // max(YES.bid, 1 - NO.ask)
-    effectiveSellNo: number;   // max(NO.bid, 1 - YES.ask)
-  };
-  // 套利成本/收入
-  effectiveLongCost: number;    // effectiveBuyYes + effectiveBuyNo
-  effectiveShortRevenue: number; // effectiveSellYes + effectiveSellNo
-  // 套利利润
-  longArbProfit: number;  // 1 - effectiveLongCost (> 0 可套利)
-  shortArbProfit: number; // effectiveShortRevenue - 1 (> 0 可套利)
-  yesSpread: number;      // YES.ask - YES.bid (市场效率指标)
-}
-```
+### TradingService
 
-### TradingClient - Order Execution
+Order management using `@polymarket/clob-client`.
 
 ```typescript
-import { TradingClient, RateLimiter } from '@catalyst-team/poly-sdk';
+import { TradingService } from '@catalyst-team/poly-sdk';
 
-const rateLimiter = new RateLimiter();
-const tradingClient = new TradingClient(rateLimiter, {
+const trading = new TradingService(rateLimiter, cache, {
   privateKey: process.env.POLYMARKET_PRIVATE_KEY!,
 });
+await trading.initialize();
 
-await tradingClient.initialize();
-console.log(`Wallet: ${tradingClient.getAddress()}`);
+// ===== Limit Orders =====
 
-// GTC Limit Order (stays until filled or cancelled)
-const order = await tradingClient.createOrder({
+// GTC: Good Till Cancelled
+const gtcOrder = await trading.createLimitOrder({
   tokenId: yesTokenId,
   side: 'BUY',
   price: 0.45,
@@ -320,8 +285,8 @@ const order = await tradingClient.createOrder({
   orderType: 'GTC',
 });
 
-// GTD Limit Order (expires at timestamp)
-const gtdOrder = await tradingClient.createOrder({
+// GTD: Good Till Date (expires at timestamp)
+const gtdOrder = await trading.createLimitOrder({
   tokenId: yesTokenId,
   side: 'BUY',
   price: 0.45,
@@ -330,406 +295,297 @@ const gtdOrder = await tradingClient.createOrder({
   expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour
 });
 
-// FOK Market Order (fill entirely or cancel)
-const marketOrder = await tradingClient.createMarketOrder({
+// ===== Market Orders =====
+
+// FOK: Fill Or Kill (fill entirely or cancel)
+const fokOrder = await trading.createMarketOrder({
   tokenId: yesTokenId,
   side: 'BUY',
   amount: 10, // $10 USDC
   orderType: 'FOK',
 });
 
-// FAK Market Order (partial fill ok)
-const fakOrder = await tradingClient.createMarketOrder({
+// FAK: Fill And Kill (partial fill ok)
+const fakOrder = await trading.createMarketOrder({
   tokenId: yesTokenId,
   side: 'SELL',
   amount: 10, // 10 shares
   orderType: 'FAK',
 });
 
-// Order management
-const openOrders = await tradingClient.getOpenOrders();
-await tradingClient.cancelOrder(orderId);
-await tradingClient.cancelAllOrders();
+// ===== Order Management =====
+const openOrders = await trading.getOpenOrders();
+await trading.cancelOrder(orderId);
+await trading.cancelAllOrders();
 
-// Get trade history
-const trades = await tradingClient.getTrades();
+// ===== Rewards (Market Making Incentives) =====
+const isScoring = await trading.isOrderScoring(orderId);
+const rewards = await trading.getCurrentRewards();
+const earnings = await trading.getEarnings('2024-12-07');
 ```
 
-### Rewards - Market Making Incentives
+---
 
-```typescript
-// Check if your orders are earning rewards
-const isScoring = await tradingClient.isOrderScoring(orderId);
-
-// Get markets with active reward programs
-const rewards = await tradingClient.getCurrentRewards();
-for (const reward of rewards) {
-  console.log(`${reward.question}`);
-  console.log(`  Max Spread: ${reward.rewardsMaxSpread}`);
-  console.log(`  Min Size: ${reward.rewardsMinSize}`);
-}
+### MarketService
 
-// Get your daily earnings
-const earnings = await tradingClient.getTotalEarningsForDay('2024-12-07');
-console.log(`Total earned: $${earnings.totalEarnings}`);
+Market data, K-lines, orderbook analysis.
 
-// Check balance and allowance
-const balance = await tradingClient.getBalanceAllowance('COLLATERAL');
-console.log(`USDC Balance: ${balance.balance}`);
-```
+```typescript
+import { MarketService } from '@catalyst-team/poly-sdk';
 
-### RealtimeService - WebSocket Subscriptions
+// Get unified market
+const market = await sdk.markets.getMarket('btc-100k-2024');
 
-⚠️ **重要：Orderbook 自动排序**
+// Get K-Lines
+const klines = await sdk.markets.getKLines(conditionId, '1h', { limit: 100 });
 
-Polymarket CLOB API 返回的 orderbook 顺序与标准预期相反：
-- **bids**: 升序排列 (最低价在前 = 最差价)
-- **asks**: 降序排列 (最高价在前 = 最差价)
+// Get dual K-Lines (YES + NO) with spread analysis
+const dual = await sdk.markets.getDualKLines(conditionId, '1h');
+console.log(dual.yes);              // YES token candles
+console.log(dual.no);               // NO token candles
+console.log(dual.spreadAnalysis);   // Historical spread (trade prices)
+console.log(dual.realtimeSpread);   // Real-time spread (orderbook)
 
-我们的 SDK **自动规范化** orderbook 数据：
-- **bids**: 降序排列 (最高价在前 = 最佳买价)
-- **asks**: 升序排列 (最低价在前 = 最佳卖价)
+// Get processed orderbook
+const orderbook = await sdk.markets.getProcessedOrderbook(conditionId);
 
-这意味着你可以安全地使用 `bids[0]` 和 `asks[0]` 获取最优价格：
+// Quick real-time spread check
+const spread = await sdk.markets.getRealtimeSpread(conditionId);
+if (spread.longArbProfit > 0.005) {
+  console.log(`Long arb: buy YES@${spread.yesAsk} + NO@${spread.noAsk}`);
+}
 
-```typescript
-const book = await sdk.clobApi.getOrderbook(conditionId);
-const bestBid = book.bids[0]?.price;  // ✅ 最高买价 (最佳 bid)
-const bestAsk = book.asks[0]?.price;  // ✅ 最低卖价 (最佳 ask)
-
-// WebSocket 更新同样自动排序
-wsManager.on('bookUpdate', (update) => {
-  const bestBid = update.bids[0]?.price;  // ✅ 已排序
-  const bestAsk = update.asks[0]?.price;  // ✅ 已排序
-});
+// Detect market signals
+const signals = await sdk.markets.detectMarketSignals(conditionId);
 ```
 
-```typescript
-import { WebSocketManager, RealtimeService } from '@catalyst-team/poly-sdk';
+#### Understanding Polymarket Orderbook
 
-const wsManager = new WebSocketManager();
-const realtime = new RealtimeService(wsManager);
+**Important**: Polymarket orderbooks have a mirror property:
 
-// Subscribe to market updates
-const subscription = await realtime.subscribeMarket(yesTokenId, noTokenId, {
-  onPriceUpdate: (update) => {
-    console.log(`${update.assetId}: ${update.price}`);
-  },
-  onBookUpdate: (update) => {
-    console.log(`Best bid: ${update.bids[0]?.price}`);
-  },
-  onLastTrade: (trade) => {
-    console.log(`Trade: ${trade.side} ${trade.size} @ ${trade.price}`);
-  },
-  onPairUpdate: (update) => {
-    console.log(`YES + NO = ${update.spread}`);
-    if (update.spread < 0.99) console.log('ARB opportunity!');
-  },
-});
+```
+Buy YES @ P = Sell NO @ (1-P)
+```
 
-// Get cached prices
-const price = realtime.getPrice(yesTokenId);
+This means the **same order appears in both orderbooks**. Simple addition causes double-counting:
 
-// Cleanup
-await subscription.unsubscribe();
-```
+```typescript
+// WRONG: Double counts mirror orders
+const askSum = YES.ask + NO.ask;  // ~1.998, not ~1.0
 
-### CTFClient - On-Chain Token Operations (Split/Merge/Redeem)
+// CORRECT: Use effective prices
+import { getEffectivePrices, checkArbitrage } from '@catalyst-team/poly-sdk';
 
-The CTF (Conditional Token Framework) client enables on-chain operations for Polymarket's conditional tokens.
+const effective = getEffectivePrices(yesAsk, yesBid, noAsk, noBid);
+// effective.effectiveBuyYes = min(YES.ask, 1 - NO.bid)
+// effective.effectiveBuyNo = min(NO.ask, 1 - YES.bid)
 
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  CTF 核心操作快速参考                                                          │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  操作         │ 功能                    │ 典型场景                           │
-├──────────────┼────────────────────────┼──────────────────────────────────────┤
-│  Split       │ USDC → YES + NO        │ 市场做市：创建代币库存                 │
-│  Merge       │ YES + NO → USDC        │ 套利：买入双边后合并获利               │
-│  Redeem      │ 胜出代币 → USDC         │ 结算：市场结束后兑换获胜代币            │
-└─────────────────────────────────────────────────────────────────────────────┘
+const arb = checkArbitrage(yesAsk, noAsk, yesBid, noBid);
+if (arb) {
+  console.log(`${arb.type} arb: ${(arb.profit * 100).toFixed(2)}% profit`);
+}
 ```
 
-**核心用途：**
-- **Arbitrage (套利)**: 当 YES + NO 买入成本 < $1 时，Merge 获利
-- **Market Making (做市)**: Split USDC 创建代币库存进行双边报价
-- **Redemption (结算)**: 市场结束后 Redeem 胜出代币获取 USDC
+---
+
+### OnchainService
+
+Unified interface for all on-chain operations: CTF + Approvals + Swaps.
 
 ```typescript
-import { CTFClient, CTF_CONTRACT, USDC_CONTRACT } from '@catalyst-team/poly-sdk';
+import { OnchainService } from '@catalyst-team/poly-sdk';
 
-const ctf = new CTFClient({
+const onchain = new OnchainService({
   privateKey: process.env.POLYMARKET_PRIVATE_KEY!,
   rpcUrl: 'https://polygon-rpc.com', // optional
 });
 
-console.log(`Wallet: ${ctf.getAddress()}`);
-console.log(`USDC Balance: ${await ctf.getUsdcBalance()}`);
-```
-
-#### Split: USDC → YES + NO Tokens
-
-```typescript
-// Split 100 USDC into 100 YES + 100 NO tokens
-const splitResult = await ctf.split(conditionId, '100');
-console.log(`TX: ${splitResult.txHash}`);
-console.log(`Created ${splitResult.yesTokens} YES + ${splitResult.noTokens} NO`);
-```
+// Check if ready for CTF trading
+const status = await onchain.checkReadyForCTF('100');
+if (!status.ready) {
+  console.log('Issues:', status.issues);
+  await onchain.approveAll();
+}
 
-#### Merge: YES + NO → USDC
+// ===== CTF Operations =====
 
-⚠️ **重要：两种 Merge 方法**
+// Split: USDC -> YES + NO tokens
+const splitResult = await onchain.split(conditionId, '100');
 
-| 方法 | 适用场景 | 推荐 |
-|------|----------|------|
-| `mergeByTokenIds()` | **Polymarket CLOB 市场** | ✅ 推荐 |
-| `merge()` | 标准 Gnosis CTF 市场 | ❌ Polymarket 慎用 |
+// Merge: YES + NO -> USDC (for arbitrage)
+const mergeResult = await onchain.mergeByTokenIds(conditionId, tokenIds, '100');
 
-```typescript
-// ✅ 推荐：Polymarket 市场使用 mergeByTokenIds
-const tokenIds = {
-  yesTokenId: market.tokens[0].tokenId,  // 从 CLOB API 获取
-  noTokenId: market.tokens[1].tokenId,
-};
-const mergeResult = await ctf.mergeByTokenIds(conditionId, tokenIds, '100');
-console.log(`TX: ${mergeResult.txHash}`);
-console.log(`Received ${mergeResult.usdcReceived} USDC`);
-
-// ⚠️ 标准 CTF 方法（可能无法正确检查 Polymarket 余额）
-// const mergeResult = await ctf.merge(conditionId, '100');
-```
+// Redeem: Winning tokens -> USDC (after resolution)
+const redeemResult = await onchain.redeemByTokenIds(conditionId, tokenIds);
 
-#### Redeem: Winning Tokens → USDC
+// ===== DEX Swaps (QuickSwap V3) =====
 
-⚠️ **重要：两种 Redeem 方法**
+// Swap MATIC to USDC.e (required for CTF)
+await onchain.swap('MATIC', 'USDC_E', '50');
 
-Polymarket 使用自定义的 token ID，与标准 CTF position ID 计算方式不同：
+// Get balances
+const balances = await onchain.getBalances();
+console.log(`USDC.e: ${balances.usdcE}`);
+```
 
-| 方法 | 适用场景 | Token ID 来源 |
-|------|----------|---------------|
-| `redeemByTokenIds()` | **Polymarket CLOB 市场** ✅ | CLOB API 返回的 tokenId |
-| `redeem()` | 标准 Gnosis CTF 市场 | `keccak256(collectionId, conditionId, indexSet)` |
+**Note**: Polymarket CTF requires **USDC.e** (0x2791...), not native USDC.
 
-```typescript
-// ✅ 推荐：Polymarket 市场使用 redeemByTokenIds
-const tokenIds = {
-  yesTokenId: '25064375110792967023484002819116042931016336431092144471807003884255851454283',
-  noTokenId: '98190367690492181203391990709979106077460946443309150166954079213761598385827',
-};
-const result = await ctf.redeemByTokenIds(conditionId, tokenIds);
-console.log(`Redeemed ${result.tokensRedeemed} ${result.outcome} tokens`);
-console.log(`Received ${result.usdcReceived} USDC`);
-
-// ❌ 不要用于 Polymarket：redeem() 使用计算的 position ID
-// const result = await ctf.redeem(conditionId);  // 可能找不到余额
-```
+---
 
-**为什么 Polymarket token ID 不同？**
-- Polymarket 在 CTF 之上包装了一层 ERC-1155 tokens
-- CLOB API 返回的 `tokenId` (如 `"25064375..."`) 与标准 CTF 计算的 position ID 不同
-- 必须使用 CLOB API 的 token ID 才能正确查询余额和 redeem
+### RealtimeServiceV2
 
-#### Position Queries
+WebSocket real-time data using `@polymarket/real-time-data-client`.
 
 ```typescript
-// Get token balances
-const balances = await ctf.getPositionBalance(conditionId);
-console.log(`YES: ${balances.yesBalance}, NO: ${balances.noBalance}`);
-
-// Check if market is resolved
-const resolution = await ctf.getMarketResolution(conditionId);
-if (resolution.isResolved) {
-  console.log(`Winner: ${resolution.winningOutcome}`);
-}
+import { RealtimeServiceV2 } from '@catalyst-team/poly-sdk';
 
-// Gas estimation
-const splitGas = await ctf.estimateSplitGas(conditionId, '100');
-const mergeGas = await ctf.estimateMergeGas(conditionId, '100');
-```
+const realtime = new RealtimeServiceV2({
+  autoReconnect: true,
+  pingInterval: 5000,
+});
 
-#### Arbitrage Flow
+// Connect and subscribe
+realtime.connect();
+realtime.subscribeMarket([yesTokenId, noTokenId]);
 
-⚠️ **注意：必须使用有效价格计算套利，不能简单相加 ask/bid**
+// Event-based API
+realtime.on('priceUpdate', (update) => {
+  console.log(`${update.assetId}: ${update.price}`);
+  console.log(`Midpoint: ${update.midpoint}, Spread: ${update.spread}`);
+});
 
-由于 Polymarket 的镜像订单特性（见上文），正确的套利计算方式如下：
+realtime.on('bookUpdate', (update) => {
+  // Orderbook is auto-normalized:
+  // bids: descending (best first), asks: ascending (best first)
+  console.log(`Best bid: ${update.bids[0]?.price}`);
+  console.log(`Best ask: ${update.asks[0]?.price}`);
+});
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│ LONG ARB (effectiveLongCost < $1):                          │
-│   有效买入成本:                                               │
-│     effectiveBuyYes = min(YES.ask, 1 - NO.bid)              │
-│     effectiveBuyNo = min(NO.ask, 1 - YES.bid)               │
-│   操作:                                                      │
-│     1. 用有效价格买入 YES + NO                               │
-│     2. CTF Merge → $1 USDC                                  │
-│     3. Profit = 1 - effectiveLongCost                       │
-├─────────────────────────────────────────────────────────────┤
-│ SHORT ARB (effectiveShortRevenue > $1):                      │
-│   有效卖出收入:                                               │
-│     effectiveSellYes = max(YES.bid, 1 - NO.ask)             │
-│     effectiveSellNo = max(NO.bid, 1 - YES.ask)              │
-│   操作:                                                      │
-│     1. CTF Split $1 → 1 YES + 1 NO                          │
-│     2. 用有效价格卖出 YES + NO                               │
-│     3. Profit = effectiveShortRevenue - 1                   │
-└─────────────────────────────────────────────────────────────┘
-```
+realtime.on('lastTrade', (trade) => {
+  console.log(`Trade: ${trade.side} ${trade.size} @ ${trade.price}`);
+});
 
-```typescript
-import { checkArbitrage, getEffectivePrices } from '@catalyst-team/poly-sdk';
+// Get cached prices
+const price = realtime.getPrice(yesTokenId);
+const book = realtime.getBook(yesTokenId);
 
-// checkArbitrage 内部使用有效价格计算
-const arb = checkArbitrage(yesAsk, noAsk, yesBid, noBid);
-if (arb?.type === 'long') {
-  console.log(arb.description); // "Buy YES @ 0.48 + NO @ 0.50, Merge for $1"
-  // Buy both tokens at effective prices, then merge
-  await tradingClient.createMarketOrder({ tokenId: yesTokenId, side: 'BUY', amount: 100 });
-  await tradingClient.createMarketOrder({ tokenId: noTokenId, side: 'BUY', amount: 100 });
-  await ctf.merge(conditionId, '100');
-}
+// Cleanup
+realtime.disconnect();
 ```
 
-### BridgeClient - Cross-Chain Deposits
+---
 
-Bridge assets from multiple chains (Ethereum, Solana, Bitcoin) to Polygon USDC.e for Polymarket trading.
+### WalletService
 
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  跨链充值流程                                                                 │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  1. 获取充值地址 → 2. 发送资产到地址 → 3. 自动桥接 → 4. USDC.e 到账           │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
+Wallet analysis and smart money scoring.
 
 ```typescript
-import {
-  BridgeClient,
-  SUPPORTED_CHAINS,
-  depositUsdc,
-  swapAndDeposit,
-} from '@catalyst-team/poly-sdk';
+// Get top traders
+const traders = await sdk.wallets.getTopTraders(10);
 
-// Get deposit addresses for your wallet
-const bridge = new BridgeClient();
-const addresses = await bridge.createDepositAddresses(walletAddress);
-console.log(`EVM chains: ${addresses.address.evm}`);
-console.log(`Solana: ${addresses.address.svm}`);
-console.log(`Bitcoin: ${addresses.address.btc}`);
-
-// Get supported assets
-const assets = await bridge.getSupportedAssets();
-for (const asset of assets) {
-  console.log(`${asset.chainName} ${asset.tokenSymbol}: min ${asset.minDepositUsd} USD`);
-}
+// Get wallet profile with smart score
+const profile = await sdk.wallets.getWalletProfile('0x...');
+console.log(`Smart Score: ${profile.smartScore}/100`);
+console.log(`Win Rate: ${profile.winRate}%`);
+console.log(`Total PnL: $${profile.totalPnL}`);
 
-// Direct USDC deposit from Ethereum
-const depositResult = await depositUsdc(signer, '100', walletAddress);
-console.log(`Deposited: ${depositResult.txHash}`);
+// Detect sell activity (for follow-wallet strategy)
+const sellResult = await sdk.wallets.detectSellActivity(
+  '0x...',
+  conditionId,
+  Date.now() - 24 * 60 * 60 * 1000 // since 24h ago
+);
+if (sellResult.isSelling) {
+  console.log(`Sold ${sellResult.percentageSold}%`);
+}
 
-// Swap ETH to USDC and deposit
-const swapResult = await swapAndDeposit(signer, {
-  tokenIn: 'ETH',
-  amountIn: '0.1',
-  targetAddress: walletAddress,
-});
-console.log(`Swapped & deposited: ${swapResult.usdcAmount}`);
+// Track group sell ratio
+const groupSell = await sdk.wallets.trackGroupSellRatio(
+  ['0x...', '0x...'],
+  conditionId,
+  peakValue,
+  sinceTimestamp
+);
 ```
 
-### SwapService - DEX Swaps on Polygon
-
-Swap tokens on Polygon using QuickSwap V3. Essential for converting tokens to USDC.e for CTF operations.
+---
 
-⚠️ **USDC vs USDC.e for Polymarket CTF**
+### SmartMoneyService
 
-| Token | Address | Polymarket CTF |
-|-------|---------|----------------|
-| USDC.e | `0x2791...` | ✅ **Required** |
-| USDC (Native) | `0x3c49...` | ❌ Not accepted |
+Smart money detection and **real-time auto copy trading**.
 
 ```typescript
-import { SwapService, POLYGON_TOKENS } from '@catalyst-team/poly-sdk';
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
 
-const swapService = new SwapService(signer);
+// One line to get started (recommended)
+const sdk = await PolymarketSDK.create({ privateKey: '0x...' });
+// SDK is initialized and WebSocket connected
 
-// Check balances
-const balances = await swapService.getBalances();
-for (const b of balances) {
-  console.log(`${b.symbol}: ${b.balance}`);
-}
+// Get smart money wallets
+const wallets = await sdk.smartMoney.getSmartMoneyList(50);
 
-// Swap native USDC to USDC.e for CTF operations
-const swapResult = await swapService.swap('USDC', 'USDC_E', '100');
-console.log(`Swapped: ${swapResult.amountOut} USDC.e`);
+// Check if address is smart money
+const isSmartMoney = await sdk.smartMoney.isSmartMoney('0x...');
 
-// Swap MATIC to USDC.e
-const maticSwap = await swapService.swap('MATIC', 'USDC_E', '50');
+// Subscribe to smart money trades
+const sub = sdk.smartMoney.subscribeSmartMoneyTrades(
+  (trade) => {
+    console.log(`${trade.traderName} ${trade.side} ${trade.outcome} @ $${trade.price}`);
+  },
+  { filterAddresses: ['0x...'], minSize: 10 }
+);
 
-// Get quote before swapping
-const quote = await swapService.getQuote('WETH', 'USDC_E', '0.1');
-console.log(`Expected output: ${quote.estimatedAmountOut} USDC.e`);
+// ===== Auto Copy Trading =====
+// Real-time copy trading - when smart money trades, copy immediately
 
-// Transfer USDC.e (for CTF operations)
-await swapService.transferUsdcE(recipientAddress, '100');
-```
+const subscription = await sdk.smartMoney.startAutoCopyTrading({
+  // Target selection
+  topN: 50,                    // Follow top 50 traders from leaderboard
+  // targetAddresses: ['0x...'], // Or specify addresses directly
 
-### AuthorizationService - Trading Approvals
+  // Order settings
+  sizeScale: 0.1,              // Copy 10% of their trade size
+  maxSizePerTrade: 10,         // Max $10 per trade
+  maxSlippage: 0.03,           // 3% slippage tolerance
+  orderType: 'FOK',            // FOK or FAK
 
-Manage ERC20 and ERC1155 approvals required for trading on Polymarket.
-
-```typescript
-import { AuthorizationService } from '@catalyst-team/poly-sdk';
+  // Filters
+  minTradeSize: 5,             // Only copy trades > $5
+  sideFilter: 'BUY',           // Only copy BUY trades (optional)
 
-const authService = new AuthorizationService(signer);
+  // Testing
+  dryRun: true,                // Set false for real trades
 
-// Check all allowances
-const status = await authService.checkAllowances();
-console.log(`Wallet: ${status.wallet}`);
-console.log(`USDC Balance: ${status.usdcBalance}`);
-console.log(`Trading Ready: ${status.tradingReady}`);
+  // Callbacks
+  onTrade: (trade, result) => {
+    console.log(`Copied ${trade.traderName}: ${result.success ? '✅' : '❌'}`);
+  },
+  onError: (error) => console.error(error),
+});
 
-if (!status.tradingReady) {
-  console.log('Issues:', status.issues);
+console.log(`Tracking ${subscription.targetAddresses.length} wallets`);
 
-  // Set up all required approvals
-  const result = await authService.approveAll();
-  console.log(result.summary);
-}
+// Get stats
+const stats = subscription.getStats();
+console.log(`Detected: ${stats.tradesDetected}, Executed: ${stats.tradesExecuted}`);
 
-// Check individual allowances
-for (const allowance of status.erc20Allowances) {
-  console.log(`${allowance.contract}: ${allowance.approved ? '✅' : '❌'}`);
-}
+// Stop
+subscription.stop();
+sdk.stop();
 ```
 
-### ArbitrageService - 套利服务
+> **Note**: Polymarket minimum order size is **$1**. Orders below $1 will be automatically skipped.
 
-实时套利检测与执行，支持市场扫描、自动再平衡、智能清仓。
+📁 **Full examples**: See [scripts/smart-money/](scripts/smart-money/) for complete working scripts:
+- `04-auto-copy-trading.ts` - Full-featured auto copy trading
+- `05-auto-copy-simple.ts` - Simplified SDK usage
+- `06-real-copy-test.ts` - Real trading test
 
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  核心功能                                                                     │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  • scanMarkets()     - 扫描市场找套利机会                                      │
-│  • start(market)     - 启动实时监控 + 自动执行                                 │
-│  • clearPositions()  - 智能清仓 (活跃市场卖出, 已结算市场 redeem)                │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  自动再平衡 (Rebalancer)                                                      │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  套利需要 USDC + YES/NO Token，Rebalancer 自动维持资金比例：                    │
-│  • USDC 比例 < 20%  → 自动 Merge (YES+NO → USDC)                             │
-│  • USDC 比例 > 80%  → 自动 Split (USDC → YES+NO)                             │
-│  • 冷却机制：两次操作间隔 ≥ 30s，检测间隔 10s                                   │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  执行安全 (Partial Fill Protection)                                          │
-├─────────────────────────────────────────────────────────────────────────────┤
-│  套利需要同时买入 YES 和 NO，但订单可能部分成交：                                 │
-│  • sizeSafetyFactor=0.8 → 只使用 80% 的盘口深度，降低滑点风险                   │
-│  • autoFixImbalance=true → 如果只成交一侧，自动卖出多余的 token                 │
-│  • imbalanceThreshold=5 → YES-NO 差额超过 $5 时触发修复                        │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
+---
+
+### ArbitrageService
 
-#### 完整工作流
+Real-time arbitrage detection, execution, and position management.
 
 ```typescript
 import { ArbitrageService } from '@catalyst-team/poly-sdk';
@@ -739,20 +595,17 @@ const arbService = new ArbitrageService({
   profitThreshold: 0.005,  // 0.5% minimum profit
   minTradeSize: 5,         // $5 minimum
   maxTradeSize: 100,       // $100 maximum
-  autoExecute: true,       // Automatically execute opportunities
-
-  // Rebalancer config
-  enableRebalancer: true,  // Auto-rebalance position
-  minUsdcRatio: 0.2,       // Min 20% USDC (Split if below)
-  maxUsdcRatio: 0.8,       // Max 80% USDC (Merge if above)
-  targetUsdcRatio: 0.5,    // Target 50% when rebalancing
-  imbalanceThreshold: 5,   // Max YES-NO difference before fix
-  rebalanceInterval: 10000, // Check every 10s
-  rebalanceCooldown: 30000, // Min 30s between actions
-
-  // Execution safety (prevents YES ≠ NO from partial fills)
+  autoExecute: true,       // Auto-execute opportunities
+
+  // Rebalancer: auto-maintain USDC/token ratio
+  enableRebalancer: true,
+  minUsdcRatio: 0.2,       // Min 20% USDC
+  maxUsdcRatio: 0.8,       // Max 80% USDC
+  targetUsdcRatio: 0.5,    // Target when rebalancing
+
+  // Execution safety
   sizeSafetyFactor: 0.8,   // Use 80% of orderbook depth
-  autoFixImbalance: true,  // Auto-sell excess if one side fails
+  autoFixImbalance: true,  // Auto-fix partial fills
 });
 
 // Listen for events
@@ -762,321 +615,203 @@ arbService.on('opportunity', (opp) => {
 
 arbService.on('execution', (result) => {
   if (result.success) {
-    console.log(`✅ Executed: $${result.profit.toFixed(2)} profit`);
+    console.log(`Executed: $${result.profit.toFixed(2)} profit`);
   }
 });
 
-arbService.on('rebalance', (result) => {
-  console.log(`🔄 Rebalance: ${result.action.type} ${result.action.amount}`);
-});
+// ===== Workflow =====
 
-// ========== Step 1: 扫描市场 ==========
+// 1. Scan markets for opportunities
 const results = await arbService.scanMarkets({ minVolume24h: 5000 }, 0.005);
-console.log(`Found ${results.filter(r => r.arbType !== 'none').length} opportunities`);
 
-// 或者一键扫描+启动最佳市场
+// 2. Start monitoring best market
 const best = await arbService.findAndStart(0.005);
-if (!best) {
-  console.log('No arbitrage opportunities found');
-  process.exit(0);
-}
-console.log(`🎯 Started: ${best.market.name} (+${best.profitPercent.toFixed(2)}%)`);
+console.log(`Started: ${best.market.name} (+${best.profitPercent.toFixed(2)}%)`);
 
-// ========== Step 2: 运行套利 ==========
-// 服务现在自动监控并执行套利...
-// 运行一段时间后:
-await new Promise(resolve => setTimeout(resolve, 60 * 60 * 1000)); // 1 hour
+// 3. Run for a while...
+await new Promise(r => setTimeout(r, 60 * 60 * 1000)); // 1 hour
 
-// ========== Step 3: 停止并清算 ==========
+// 4. Stop and clear positions
 await arbService.stop();
-console.log('Stats:', arbService.getStats());
-
-// 智能清仓: 活跃市场 merge+sell, 已结算市场 redeem
 const clearResult = await arbService.clearPositions(best.market, true);
-console.log(`✅ Recovered: $${clearResult.totalUsdcRecovered.toFixed(2)}`);
+console.log(`Recovered: $${clearResult.totalUsdcRecovered.toFixed(2)}`);
 ```
 
-#### 手动选择市场
+---
 
-```typescript
-// 如果不用 scanMarkets，可以手动构建 market config
-const market = {
-  name: 'Will BTC reach $100k?',
-  conditionId: '0x...',
-  yesTokenId: '12345...',
-  noTokenId: '67890...',
-  outcomes: ['Yes', 'No'] as [string, string],
-};
-
-await arbService.start(market);
-```
+## Low-Level Clients
 
-#### 批量清仓
+For advanced users who need direct API access:
 
 ```typescript
-// 多个市场一起清仓
-const markets = [market1, market2, market3];
-const results = await arbService.clearAllPositions(markets, true);
-const total = results.reduce((sum, r) => sum + r.totalUsdcRecovered, 0);
-console.log(`Total recovered: $${total.toFixed(2)}`);
+import {
+  DataApiClient,    // Positions, trades, leaderboard
+  GammaApiClient,   // Markets, events, search
+  SubgraphClient,   // On-chain data via Goldsky
+  CTFClient,        // CTF contract operations
+  BridgeClient,     // Cross-chain deposits
+  SwapService,      // DEX swaps on Polygon
+} 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 (on-chain data)
+const userPositions = await sdk.subgraph.getUserPositions(address);
+const isResolved = await sdk.subgraph.isConditionResolved(conditionId);
+const globalOI = await sdk.subgraph.getGlobalOpenInterest();
 ```
 
-#### 仅监控模式
+---
 
+## Breaking Changes (v0.3.0)
+
+### `UnifiedMarket.tokens` is now an Array
+
+**Before (v0.2.x)**:
 ```typescript
-// No private key = monitoring only, no execution
-const arbService = new ArbitrageService({
-  profitThreshold: 0.003,
-  enableLogging: true,
-});
+// Object with yes/no properties
+const yesPrice = market.tokens.yes.price;
+const noPrice = market.tokens.no.price;
+```
 
-arbService.on('opportunity', (opp) => {
-  // Log opportunities for analysis without executing
-  console.log(`Found ${opp.type} arb: ${opp.profitPercent.toFixed(2)}%`);
-  console.log(`  ${opp.description}`);
-});
+**After (v0.3.0)**:
+```typescript
+// Array of MarketToken objects
+const yesToken = market.tokens.find(t => t.outcome === 'Yes');
+const noToken = market.tokens.find(t => t.outcome === 'No');
 
-await arbService.start(market);
+const yesPrice = yesToken?.price;
+const noPrice = noToken?.price;
 ```
 
-## Price Utilities
+### Migration Guide
 
 ```typescript
-import {
-  roundPrice,
-  validatePrice,
-  calculateBuyAmount,
-  getEffectivePrices,  // For Polymarket mirror orderbook
-  checkArbitrage,
-  formatUSDC,
-  calculatePnL,
-  type TickSize,
-} from '@catalyst-team/poly-sdk';
+// Helper function for migration
+function getTokenPrice(market: UnifiedMarket, outcome: 'Yes' | 'No'): number {
+  return market.tokens.find(t => t.outcome === outcome)?.price ?? 0;
+}
 
-// Round price to tick size
-const tickSize: TickSize = '0.01';
-roundPrice(0.523, tickSize, 'floor'); // 0.52
-roundPrice(0.523, tickSize, 'ceil');  // 0.53
+// Usage
+const yesPrice = getTokenPrice(market, 'Yes');
+const noPrice = getTokenPrice(market, 'No');
+```
 
-// Validate price
-const validation = validatePrice(0.525, tickSize);
-if (!validation.valid) {
-  console.log(validation.error);
-}
+**Why the change?** The array format better supports multi-outcome markets and is more consistent with the Polymarket API response format.
 
-// Calculate order cost
-const cost = calculateBuyAmount(0.52, 100); // $52
-console.log(formatUSDC(cost)); // "$52.00"
+---
 
-// Get effective prices (considering Polymarket mirror orders)
-const effective = getEffectivePrices(yesAsk, yesBid, noAsk, noBid);
-console.log(`Effective buy YES: ${effective.effectiveBuyYes}`);  // min(YES.ask, 1 - NO.bid)
-console.log(`Effective buy NO: ${effective.effectiveBuyNo}`);    // min(NO.ask, 1 - YES.bid)
+## Examples
 
-// Check for arbitrage (uses effective prices internally)
-const arb = checkArbitrage(
-  yesAsk, noAsk,  // Ask prices
-  yesBid, noBid   // Bid prices
-);
-if (arb) {
-  console.log(`${arb.type} arb: ${(arb.profit * 100).toFixed(2)}% profit`);
-  console.log(arb.description);  // "Buy YES @ 0.48 + NO @ 0.50, Merge for $1"
-}
+Run examples with:
 
-// Calculate PnL
-const pnl = calculatePnL(0.40, 0.55, 100, 'long');
-console.log(`PnL: ${formatUSDC(pnl.pnl)} (${pnl.pnlPercent.toFixed(1)}%)`);
+```bash
+pnpm example:basic        # Basic usage
+pnpm example:smart-money  # Smart money analysis
+pnpm example:trading      # Trading orders
+pnpm example:realtime     # WebSocket feeds
+pnpm example:arb-service  # Arbitrage service
 ```
 
-## K-Line Intervals
+| Example | Description |
+|---------|-------------|
+| [01-basic-usage.ts](examples/01-basic-usage.ts) | Get markets, orderbooks, detect arbitrage |
+| [02-smart-money.ts](examples/02-smart-money.ts) | Top traders, wallet profiles, smart scores |
+| [03-market-analysis.ts](examples/03-market-analysis.ts) | Market signals, volume analysis |
+| [04-kline-aggregation.ts](examples/04-kline-aggregation.ts) | Build OHLCV candles from trades |
+| [05-follow-wallet-strategy.ts](examples/05-follow-wallet-strategy.ts) | Track smart money, detect exits |
+| [06-services-demo.ts](examples/06-services-demo.ts) | All SDK services in action |
+| [07-realtime-websocket.ts](examples/07-realtime-websocket.ts) | Live price feeds, orderbook updates |
+| [08-trading-orders.ts](examples/08-trading-orders.ts) | GTC, GTD, FOK, FAK order types |
+| [09-rewards-tracking.ts](examples/09-rewards-tracking.ts) | Market maker incentives, earnings |
+| [10-ctf-operations.ts](examples/10-ctf-operations.ts) | Split, merge, redeem tokens |
+| [11-live-arbitrage-scan.ts](examples/11-live-arbitrage-scan.ts) | Scan markets for opportunities |
+| [12-trending-arb-monitor.ts](examples/12-trending-arb-monitor.ts) | Real-time trending monitor |
+| [13-arbitrage-service.ts](examples/13-arbitrage-service.ts) | Full arbitrage workflow |
 
-Supported intervals: `30s`, `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `12h`, `1d`
+---
 
-```typescript
-import type { KLineInterval } from '@catalyst-team/poly-sdk';
+## API Reference
 
-const interval: KLineInterval = '1h';
-const candles = await sdk.markets.getKLines(conditionId, interval);
-```
+For detailed API documentation, see:
+
+- [docs/00-design.md](docs/00-design.md) - Architecture design
+- [docs/02-API.md](docs/02-API.md) - Complete API reference
+- [docs/01-polymarket-orderbook-arbitrage.md](docs/01-polymarket-orderbook-arbitrage.md) - Orderbook mirror & arbitrage
 
-## Types
+### Type Exports
 
 ```typescript
 import type {
-  // Core
+  // Core types
   UnifiedMarket,
-  PriceUpdate,
-  BookUpdate,
+  MarketToken,
   ProcessedOrderbook,
   ArbitrageOpportunity,
-  EffectivePrices,           // Effective prices for Polymarket mirror orderbook
+  EffectivePrices,
 
-  // K-Lines & Spread
+  // Trading
+  Side,
+  OrderType,
+  Order,
+  OrderResult,
+  LimitOrderParams,
+  MarketOrderParams,
+
+  // K-Lines
   KLineInterval,
   KLineCandle,
   DualKLineData,
-  SpreadDataPoint,           // Historical spread (trade prices)
+  SpreadDataPoint,
+
+  // WebSocket
+  PriceUpdate,
+  BookUpdate,
+  OrderbookSnapshot,
 
   // Wallet
   WalletProfile,
   SellActivityResult,
 
-  // Trading
-  Side,
-  OrderType,
-  OrderParams,
-  MarketOrderParams,
-  Order,
-  OrderResult,
-  TradeInfo,
-
-  // Rewards
-  UserEarning,
-  MarketReward,
+  // Smart Money
+  SmartMoneyWallet,
+  SmartMoneyTrade,
+  AutoCopyTradingOptions,
+  AutoCopyTradingStats,
+  AutoCopyTradingSubscription,
 
   // CTF
-  CTFConfig,
   SplitResult,
   MergeResult,
   RedeemResult,
-  PositionBalance,
-  MarketResolution,
-  TokenIds,
-
-  // Bridge
-  BridgeSupportedAsset,
-  DepositAddress,
-  DepositStatus,
-  DepositResult,
-  SwapAndDepositResult,
-
-  // Swap
-  SupportedToken,
-  SwapQuote,
-  SwapResult,
-  TokenBalance,
-
-  // Authorization
-  AllowanceInfo,
-  AllowancesResult,
-  ApprovalTxResult,
-
-  // ArbitrageService
+
+  // Arbitrage
   ArbitrageMarketConfig,
   ArbitrageServiceConfig,
-  ArbitrageServiceOpportunity,
-  ArbitrageExecutionResult,
-  OrderbookState,
-  BalanceState,
-  RebalanceAction,
-  RebalanceResult,
-  SettleResult,
-  // ArbitrageService - Scanning
-  ScanCriteria,
   ScanResult,
-  // ArbitrageService - Smart clearing
   ClearPositionResult,
-  ClearAction,
-
-  // Price Utils
-  TickSize,
-
-  // API types
-  Position,
-  Trade,
-  LeaderboardEntry,
-  GammaMarket,
-  ClobMarket,
-  Orderbook,
 } from '@catalyst-team/poly-sdk';
 ```
 
-## Error Handling
-
-```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('Market not found');
-    } else if (error.code === ErrorCode.RATE_LIMITED) {
-      console.log('Rate limited, retry later');
-    }
-  }
-}
-
-// Auto-retry with exponential backoff
-const result = await withRetry(() => sdk.getMarket(slug), {
-  maxRetries: 3,
-  baseDelay: 1000,
-});
-```
-
-## Rate Limiting
-
-Built-in rate limiting per API type:
-- Data API: 10 req/sec
-- Gamma API: 10 req/sec
-- CLOB API: 5 req/sec
-
-```typescript
-import { RateLimiter, ApiType } from '@catalyst-team/poly-sdk';
-
-// Custom rate limiter
-const limiter = new RateLimiter({
-  [ApiType.DATA]: { maxConcurrent: 5, minTime: 200 },
-  [ApiType.GAMMA]: { maxConcurrent: 5, minTime: 200 },
-  [ApiType.CLOB]: { maxConcurrent: 2, minTime: 500 },
-});
-```
-
-## Caching
-
-Built-in TTL-based caching:
-
-```typescript
-// Clear all cache
-sdk.clearCache();
-
-// Invalidate specific market
-sdk.invalidateMarketCache(conditionId);
-```
-
-## Examples
-
-| Example | Description | Source |
-|---------|-------------|--------|
-| [Basic Usage](examples/01-basic-usage.ts) | Get markets, orderbooks, detect arbitrage | `pnpm example:basic` |
-| [Smart Money](examples/02-smart-money.ts) | Top traders, wallet profiles, smart scores | `pnpm example:smart-money` |
-| [Market Analysis](examples/03-market-analysis.ts) | Market signals, volume analysis | `pnpm example:market-analysis` |
-| [K-Line Aggregation](examples/04-kline-aggregation.ts) | Build OHLCV candles from trades | `pnpm example:kline` |
-| [Follow Wallet](examples/05-follow-wallet-strategy.ts) | Track smart money positions, detect exits | `pnpm example:follow-wallet` |
-| [Services Demo](examples/06-services-demo.ts) | All SDK services in action | `pnpm example:services` |
-| [Realtime WebSocket](examples/07-realtime-websocket.ts) | Live price feeds, orderbook updates | `pnpm example:realtime` |
-| [Trading Orders](examples/08-trading-orders.ts) | GTC, GTD, FOK, FAK order types | `pnpm example:trading` |
-| [Rewards Tracking](examples/09-rewards-tracking.ts) | Market maker incentives, earnings | `pnpm example:rewards` |
-| [CTF Operations](examples/10-ctf-operations.ts) | Split, merge, redeem tokens | `pnpm example:ctf` |
-| [Live Arbitrage Scan](examples/11-live-arbitrage-scan.ts) | Scan real markets for opportunities | `pnpm example:live-arb` |
-| [Trending Arb Monitor](examples/12-trending-arb-monitor.ts) | Real-time trending markets monitor | `pnpm example:trending-arb` |
-
-Run any example:
-
-```bash
-pnpm example:basic
-pnpm example:smart-money
-pnpm example:trading
-# etc.
-```
+---
 
 ## Dependencies
 
-- `@nevuamarkets/poly-websockets` - WebSocket client
+- `@polymarket/clob-client` - Official CLOB trading client
+- `@polymarket/real-time-data-client` - Official WebSocket client
+- `ethers@5` - Blockchain interactions
 - `bottleneck` - Rate limiting
-- `ethers` - Blockchain interactions (for CTFClient)
+
+---
 
 ## License
 
-Private
+MIT