@catalyst-team/poly-sdk 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,17 +1,17 @@
-# @prediction-router/poly-sdk
+# @catalyst-team/poly-sdk
 
 Unified SDK for Polymarket APIs - Data API, Gamma API, CLOB API, and WebSocket real-time updates.
 
 ## Installation
 
 ```bash
-pnpm add @prediction-router/poly-sdk
+pnpm add @catalyst-team/poly-sdk
 ```
 
 ## Quick Start
 
 ```typescript
-import { PolymarketSDK } from '@prediction-router/poly-sdk';
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
 
 const sdk = new PolymarketSDK();
 
@@ -33,29 +33,39 @@ if (arb) {
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                      PolymarketSDK                          │
-├─────────────────────────────────────────────────────────────┤
-│  Layer 3: Services                                          │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
-│  │WalletService│  │MarketService│  │  RealtimeService    │  │
-│  │ - profiles  │  │ - K-Lines   │  │  - subscriptions    │  │
-│  │ - sell det. │  │ - signals   │  │  - price cache      │  │
-│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
-├─────────────────────────────────────────────────────────────┤
-│  Layer 2: API Clients                                       │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐  │
-│  │ DataAPI  │  │ GammaAPI │  │ CLOB API │  │  WebSocket  │  │
-│  │positions │  │ markets  │  │ orderbook│  │  real-time  │  │
-│  │ trades   │  │ events   │  │ trading  │  │  prices     │  │
-│  └──────────┘  └──────────┘  └──────────┘  └─────────────┘  │
-├─────────────────────────────────────────────────────────────┤
-│  Layer 1: Infrastructure                                    │
-│  ┌────────────┐  ┌─────────┐  ┌──────────┐  ┌────────────┐  │
-│  │RateLimiter │  │  Cache  │  │  Errors  │  │   Types    │  │
-│  │per-API     │  │TTL-based│  │ retry    │  │ unified    │  │
-│  └────────────┘  └─────────┘  └──────────┘  └────────────┘  │
-└─────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                             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   │   │
+│  └────────────┘  └─────────┘  └──────────┘  └────────────┘ └──────────────┘   │
+└──────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ## API Clients
@@ -197,7 +207,7 @@ const bidSum = YES.bid + NO.bid;  // ≈ 0.001-0.002，而非 ≈ 1.0
 
 **正确做法：使用有效价格 (Effective Prices)**
 ```typescript
-import { getEffectivePrices, checkArbitrage } from '@prediction-router/poly-sdk';
+import { getEffectivePrices, checkArbitrage } from '@catalyst-team/poly-sdk';
 
 // 计算考虑镜像后的最优价格
 const effective = getEffectivePrices(yesAsk, yesBid, noAsk, noBid);
@@ -288,7 +298,7 @@ interface OrderbookSummary {
 ### TradingClient - Order Execution
 
 ```typescript
-import { TradingClient, RateLimiter } from '@prediction-router/poly-sdk';
+import { TradingClient, RateLimiter } from '@catalyst-team/poly-sdk';
 
 const rateLimiter = new RateLimiter();
 const tradingClient = new TradingClient(rateLimiter, {
@@ -392,7 +402,7 @@ wsManager.on('bookUpdate', (update) => {
 ```
 
 ```typescript
-import { WebSocketManager, RealtimeService } from '@prediction-router/poly-sdk';
+import { WebSocketManager, RealtimeService } from '@catalyst-team/poly-sdk';
 
 const wsManager = new WebSocketManager();
 const realtime = new RealtimeService(wsManager);
@@ -421,15 +431,29 @@ const price = realtime.getPrice(yesTokenId);
 await subscription.unsubscribe();
 ```
 
-### CTFClient - On-Chain Token Operations
+### CTFClient - On-Chain Token Operations (Split/Merge/Redeem)
 
-The CTF (Conditional Token Framework) client enables on-chain operations for Polymarket's conditional tokens. This is essential for:
-- **Arbitrage**: Merge tokens when buying YES + NO < $1
-- **Market Making**: Split USDC to create inventory
-- **Redemption**: Claim winnings after market resolution
+The CTF (Conditional Token Framework) client enables on-chain operations for Polymarket's conditional tokens.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  CTF 核心操作快速参考                                                          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  操作         │ 功能                    │ 典型场景                           │
+├──────────────┼────────────────────────┼──────────────────────────────────────┤
+│  Split       │ USDC → YES + NO        │ 市场做市：创建代币库存                 │
+│  Merge       │ YES + NO → USDC        │ 套利：买入双边后合并获利               │
+│  Redeem      │ 胜出代币 → USDC         │ 结算：市场结束后兑换获胜代币            │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+**核心用途：**
+- **Arbitrage (套利)**: 当 YES + NO 买入成本 < $1 时，Merge 获利
+- **Market Making (做市)**: Split USDC 创建代币库存进行双边报价
+- **Redemption (结算)**: 市场结束后 Redeem 胜出代币获取 USDC
 
 ```typescript
-import { CTFClient, CTF_CONTRACT, USDC_CONTRACT } from '@prediction-router/poly-sdk';
+import { CTFClient, CTF_CONTRACT, USDC_CONTRACT } from '@catalyst-team/poly-sdk';
 
 const ctf = new CTFClient({
   privateKey: process.env.POLYMARKET_PRIVATE_KEY!,
@@ -451,11 +475,25 @@ console.log(`Created ${splitResult.yesTokens} YES + ${splitResult.noTokens} NO`)
 
 #### Merge: YES + NO → USDC
 
+⚠️ **重要：两种 Merge 方法**
+
+| 方法 | 适用场景 | 推荐 |
+|------|----------|------|
+| `mergeByTokenIds()` | **Polymarket CLOB 市场** | ✅ 推荐 |
+| `merge()` | 标准 Gnosis CTF 市场 | ❌ Polymarket 慎用 |
+
 ```typescript
-// Merge 100 YES + 100 NO → 100 USDC (for arbitrage)
-const mergeResult = await ctf.merge(conditionId, '100');
+// ✅ 推荐：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
@@ -535,7 +573,7 @@ const mergeGas = await ctf.estimateMergeGas(conditionId, '100');
 ```
 
 ```typescript
-import { checkArbitrage, getEffectivePrices } from '@prediction-router/poly-sdk';
+import { checkArbitrage, getEffectivePrices } from '@catalyst-team/poly-sdk';
 
 // checkArbitrage 内部使用有效价格计算
 const arb = checkArbitrage(yesAsk, noAsk, yesBid, noBid);
@@ -548,44 +586,254 @@ if (arb?.type === 'long') {
 }
 ```
 
-### ArbitrageService - Automated Arbitrage
+### BridgeClient - Cross-Chain Deposits
+
+Bridge assets from multiple chains (Ethereum, Solana, Bitcoin) to Polygon USDC.e for Polymarket trading.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  跨链充值流程                                                                 │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  1. 获取充值地址 → 2. 发送资产到地址 → 3. 自动桥接 → 4. USDC.e 到账           │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+```typescript
+import {
+  BridgeClient,
+  SUPPORTED_CHAINS,
+  depositUsdc,
+  swapAndDeposit,
+} from '@catalyst-team/poly-sdk';
+
+// 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`);
+}
+
+// Direct USDC deposit from Ethereum
+const depositResult = await depositUsdc(signer, '100', walletAddress);
+console.log(`Deposited: ${depositResult.txHash}`);
+
+// Swap ETH to USDC and deposit
+const swapResult = await swapAndDeposit(signer, {
+  tokenIn: 'ETH',
+  amountIn: '0.1',
+  targetAddress: walletAddress,
+});
+console.log(`Swapped & deposited: ${swapResult.usdcAmount}`);
+```
+
+### SwapService - DEX Swaps on Polygon
 
-The ArbitrageService combines TradingClient and CTFClient for automated arbitrage detection and execution.
+Swap tokens on Polygon using QuickSwap V3. Essential for converting tokens to USDC.e for CTF operations.
 
-**内部使用有效价格计算**，自动处理 Polymarket 的镜像订单特性。
+⚠️ **USDC vs USDC.e for Polymarket CTF**
 
-详细的套利计算原理见: [docs/01-polymarket-orderbook-arbitrage.md](docs/01-polymarket-orderbook-arbitrage.md)
+| Token | Address | Polymarket CTF |
+|-------|---------|----------------|
+| USDC.e | `0x2791...` | ✅ **Required** |
+| USDC (Native) | `0x3c49...` | ❌ Not accepted |
 
 ```typescript
-import { ArbitrageService, TradingClient, CTFClient, RateLimiter } from '@prediction-router/poly-sdk';
+import { SwapService, POLYGON_TOKENS } from '@catalyst-team/poly-sdk';
 
-const rateLimiter = new RateLimiter();
-const tradingClient = new TradingClient(rateLimiter, { privateKey: '...' });
-const ctfClient = new CTFClient({ privateKey: '...' });
-const sdk = new PolymarketSDK();
+const swapService = new SwapService(signer);
+
+// Check balances
+const balances = await swapService.getBalances();
+for (const b of balances) {
+  console.log(`${b.symbol}: ${b.balance}`);
+}
+
+// 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`);
+
+// Swap MATIC to USDC.e
+const maticSwap = await swapService.swap('MATIC', 'USDC_E', '50');
+
+// Get quote before swapping
+const quote = await swapService.getQuote('WETH', 'USDC_E', '0.1');
+console.log(`Expected output: ${quote.estimatedAmountOut} USDC.e`);
+
+// Transfer USDC.e (for CTF operations)
+await swapService.transferUsdcE(recipientAddress, '100');
+```
+
+### AuthorizationService - Trading Approvals
+
+Manage ERC20 and ERC1155 approvals required for trading on Polymarket.
+
+```typescript
+import { AuthorizationService } from '@catalyst-team/poly-sdk';
+
+const authService = new AuthorizationService(signer);
+
+// 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}`);
 
-const arbService = new ArbitrageService(tradingClient, ctfClient, sdk.clobApi, {
-  minProfitThreshold: 0.005,  // 0.5% minimum (based on effective prices)
-  maxGasCost: 0.10,           // $0.10 max gas
-  dryRun: true,               // Simulation mode
+if (!status.tradingReady) {
+  console.log('Issues:', status.issues);
+
+  // Set up all required approvals
+  const result = await authService.approveAll();
+  console.log(result.summary);
+}
+
+// Check individual allowances
+for (const allowance of status.erc20Allowances) {
+  console.log(`${allowance.contract}: ${allowance.approved ? '✅' : '❌'}`);
+}
+```
+
+### ArbitrageService - 套利服务
+
+实时套利检测与执行，支持市场扫描、自动再平衡、智能清仓。
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  核心功能                                                                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  • 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 时触发修复                        │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+#### 完整工作流
+
+```typescript
+import { ArbitrageService } from '@catalyst-team/poly-sdk';
+
+const arbService = new ArbitrageService({
+  privateKey: process.env.POLY_PRIVKEY,
+  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)
+  sizeSafetyFactor: 0.8,   // Use 80% of orderbook depth
+  autoFixImbalance: true,  // Auto-sell excess if one side fails
+});
+
+// Listen for events
+arbService.on('opportunity', (opp) => {
+  console.log(`${opp.type.toUpperCase()} ARB: ${opp.profitPercent.toFixed(2)}%`);
+});
+
+arbService.on('execution', (result) => {
+  if (result.success) {
+    console.log(`✅ Executed: $${result.profit.toFixed(2)} profit`);
+  }
 });
 
-// Detect opportunity (uses effective prices internally)
-const opportunity = await arbService.detectOpportunity(conditionId);
-if (opportunity) {
-  console.log(`${opportunity.type} arb: ${opportunity.profitPercent.toFixed(2)}%`);
-  console.log(`Effective cost: ${opportunity.effectiveCost}`);
+arbService.on('rebalance', (result) => {
+  console.log(`🔄 Rebalance: ${result.action.type} ${result.action.amount}`);
+});
+
+// ========== Step 1: 扫描市场 ==========
+const results = await arbService.scanMarkets({ minVolume24h: 5000 }, 0.005);
+console.log(`Found ${results.filter(r => r.arbType !== 'none').length} opportunities`);
+
+// 或者一键扫描+启动最佳市场
+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)}%)`);
 
-// Scan multiple markets
-const opportunities = await arbService.scanMarkets(conditionIds);
+// ========== Step 2: 运行套利 ==========
+// 服务现在自动监控并执行套利...
+// 运行一段时间后:
+await new Promise(resolve => setTimeout(resolve, 60 * 60 * 1000)); // 1 hour
 
-// Execute (or simulate)
-const result = await arbService.execute({
-  conditionId,
-  amount: 100,  // $100 USDC
+// ========== Step 3: 停止并清算 ==========
+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)}`);
+```
+
+#### 手动选择市场
+
+```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);
+```
+
+#### 批量清仓
+
+```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)}`);
+```
+
+#### 仅监控模式
+
+```typescript
+// No private key = monitoring only, no execution
+const arbService = new ArbitrageService({
+  profitThreshold: 0.003,
+  enableLogging: true,
 });
-console.log(`Profit: $${result.netProfit.toFixed(4)}`);
+
+arbService.on('opportunity', (opp) => {
+  // Log opportunities for analysis without executing
+  console.log(`Found ${opp.type} arb: ${opp.profitPercent.toFixed(2)}%`);
+  console.log(`  ${opp.description}`);
+});
+
+await arbService.start(market);
 ```
 
 ## Price Utilities
@@ -600,7 +848,7 @@ import {
   formatUSDC,
   calculatePnL,
   type TickSize,
-} from '@prediction-router/poly-sdk';
+} from '@catalyst-team/poly-sdk';
 
 // Round price to tick size
 const tickSize: TickSize = '0.01';
@@ -642,7 +890,7 @@ console.log(`PnL: ${formatUSDC(pnl.pnl)} (${pnl.pnlPercent.toFixed(1)}%)`);
 Supported intervals: `30s`, `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `12h`, `1d`
 
 ```typescript
-import type { KLineInterval } from '@prediction-router/poly-sdk';
+import type { KLineInterval } from '@catalyst-team/poly-sdk';
 
 const interval: KLineInterval = '1h';
 const candles = await sdk.markets.getKLines(conditionId, interval);
@@ -690,13 +938,42 @@ import type {
   RedeemResult,
   PositionBalance,
   MarketResolution,
-
-  // Arbitrage
-  ArbitrageConfig,
-  ArbitrageOpportunity,
-  ArbitrageExecutionParams,
-  ArbitrageResult,
-  ArbitrageTransaction,
+  TokenIds,
+
+  // Bridge
+  BridgeSupportedAsset,
+  DepositAddress,
+  DepositStatus,
+  DepositResult,
+  SwapAndDepositResult,
+
+  // Swap
+  SupportedToken,
+  SwapQuote,
+  SwapResult,
+  TokenBalance,
+
+  // Authorization
+  AllowanceInfo,
+  AllowancesResult,
+  ApprovalTxResult,
+
+  // ArbitrageService
+  ArbitrageMarketConfig,
+  ArbitrageServiceConfig,
+  ArbitrageServiceOpportunity,
+  ArbitrageExecutionResult,
+  OrderbookState,
+  BalanceState,
+  RebalanceAction,
+  RebalanceResult,
+  SettleResult,
+  // ArbitrageService - Scanning
+  ScanCriteria,
+  ScanResult,
+  // ArbitrageService - Smart clearing
+  ClearPositionResult,
+  ClearAction,
 
   // Price Utils
   TickSize,
@@ -708,13 +985,13 @@ import type {
   GammaMarket,
   ClobMarket,
   Orderbook,
-} from '@prediction-router/poly-sdk';
+} from '@catalyst-team/poly-sdk';
 ```
 
 ## Error Handling
 
 ```typescript
-import { PolymarketError, ErrorCode, withRetry } from '@prediction-router/poly-sdk';
+import { PolymarketError, ErrorCode, withRetry } from '@catalyst-team/poly-sdk';
 
 try {
   const market = await sdk.getMarket('invalid-slug');
@@ -743,7 +1020,7 @@ Built-in rate limiting per API type:
 - CLOB API: 5 req/sec
 
 ```typescript
-import { RateLimiter, ApiType } from '@prediction-router/poly-sdk';
+import { RateLimiter, ApiType } from '@catalyst-team/poly-sdk';
 
 // Custom rate limiter
 const limiter = new RateLimiter({
@@ -779,9 +1056,8 @@ sdk.invalidateMarketCache(conditionId);
 | [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` |
-| [Arbitrage Service](examples/11-arbitrage-service.ts) | Detect and execute arbitrage | `pnpm example:arbitrage` |
-| [Live Arbitrage Scan](examples/12-live-arbitrage-scan.ts) | Scan real markets for opportunities | `pnpm example:live-arb` |
-| [Trending Arb Monitor](examples/13-trending-arb-monitor.ts) | Real-time trending markets monitor | `pnpm example:trending-arb` |
+| [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:
 

package/docs/00-design.md

@@ -176,7 +176,7 @@ await swapService.transferUsdcE(sessionWallet, '100');
 The `swapAndDeposit()` function combines swap and deposit in one operation:
 
 ```typescript
-import { swapAndDeposit } from '@prediction-router/poly-sdk';
+import { swapAndDeposit } from '@catalyst-team/poly-sdk';
 
 // Swap MATIC to USDC and deposit to Polymarket
 const result = await swapAndDeposit(signer, 'MATIC', '100', {