@vesper85/strategy-sdk 0.1.0 → 0.1.3

package/README.md

@@ -24,7 +24,7 @@ yarn add @osiris-ai/strategy-sdk
 
 ## Quick Start
 
-### 1. Create a Strategy (Tick-Based)
+### 1. Create a Tick-Based Strategy
 
 ```typescript
 import type { OsirisContext, CodeStrategy } from '@osiris-ai/strategy-sdk';
@@ -45,41 +45,72 @@ export default class MyStrategy implements CodeStrategy {
 }
 ```
 
-### 2. Run the Strategy
+### 2. Create an Event-Based Strategy
+
+```typescript
+import type { 
+    CodeStrategy, 
+    EventSubscription, 
+    StrategyEvent, 
+    OsirisContext 
+} from '@osiris-ai/strategy-sdk';
+
+export class PriceAlertStrategy implements CodeStrategy {
+    // Define what events to subscribe to
+    subscriptions: EventSubscription[] = [
+        {
+            type: 'price',
+            market: 'BTC-USD',
+            conditions: { priceChangePercent: 5 }
+        }
+    ];
+
+    // Called when subscribed events occur
+    async onEvent(event: StrategyEvent, osiris: OsirisContext): Promise<void> {
+        osiris.log(`Price event for ${event.market}: ${event.data.price}`);
+    }
+}
+```
+
+### 3. Run the Strategy
 
 ```typescript
 import {
     createOsirisContext,
     createConsoleLogger,
-    runStrategy,
+    createStrategyEngine,
+    createEventRunner,
     PrivateKeySigner,
 } from '@osiris-ai/strategy-sdk';
-import MyStrategy from './my-strategy';
 
 async function main() {
     const logger = createConsoleLogger();
 
-    // Create signer
     const signer = new PrivateKeySigner({
         privateKey: process.env.PRIVATE_KEY!,
     });
 
-    // Create context
     const context = createOsirisContext({
         strategyId: 'my-strategy',
-        market: 'hyperliquid', // or 'polymarket'
+        market: 'hyperliquid',
         userAddress: signer.getAddress()!,
         signer,
     });
 
-    // Create strategy instance
-    const strategy = new MyStrategy();
-
-    // Run strategy once
-    await runStrategy(strategy, { logger }, context);
+    // For tick-based strategies
+    const engine = createStrategyEngine(strategy, {
+        logger,
+        tickIntervalMs: 60000,
+    }, context);
+    engine.start();
+
+    // For event-based strategies
+    const runner = createEventRunner(strategy, {
+        logger,
+        eventSourceUrl: 'wss://events.example.com/ws',
+    }, context);
+    runner.start();
 }
-
-main();
 ```
 
 ## Execution Modes
@@ -102,7 +133,7 @@ import { createStrategyEngine } from '@osiris-ai/strategy-sdk';
 
 const engine = createStrategyEngine(strategy, {
     logger,
-    strategyId: 'my-strategy', // Optional, for logging
+    strategyId: 'my-strategy',
     tickIntervalMs: 60000, // Run every 60 seconds
 }, context);
 
@@ -112,7 +143,7 @@ engine.start();
 
 ### Event-Based Execution (Real-time WebSocket)
 
-Reacts to real-time events from your WebSocket server. Best for reactive strategies (price alerts, arbitrage, etc.)
+Reacts to real-time events from WebSocket streams. Best for strategies that need immediate response to market changes.
 
 ```typescript
 interface CodeStrategy {
@@ -121,55 +152,262 @@ interface CodeStrategy {
 }
 ```
 
+## Event Subscription Types
+
+The SDK uses a discriminated union for type-safe event subscriptions:
+
+### MarketSubscription
+
+Subscribe to market events (price, orderbook, trade, fill):
+
+```typescript
+{
+    type: 'price',  // or 'orderbook', 'trade', 'fill'
+    market: 'BTC-USD',
+    eventSource: 'polymarket',  // optional
+    conditions: {
+        priceChangePercent: 5,
+        volumeAbove: 10000,
+    }
+}
+```
+
+### WalletSubscription
+
+Subscribe to wallet analysis events (Osiris Pub/Sub only):
+
+```typescript
+{
+    type: 'wallet',
+    wallet: '0x1234567890abcdef...',
+    conditions: {
+        minWinRate: 60,
+        minTradeCount: 10,
+    }
+}
+```
+
+### OpportunitySubscription
+
+Subscribe to trading opportunities (Osiris Pub/Sub only):
+
+```typescript
+{
+    type: 'opportunity',
+    filter: 'wide_spread_markets',  // optional, defaults to 'all'
+    conditions: {
+        minScore: 70,
+    }
+}
+```
+
+### CustomSubscription
+
+Subscribe to custom topics:
+
+```typescript
+{
+    type: 'custom',
+    topic: 'custom:my-topic',
+}
+```
+
+## Event Sources
+
+### Osiris Pub/Sub
+
+Connect to Osiris analytics WebSocket for market analysis, wallet tracking, and opportunities:
+
+```typescript
+const runner = createEventRunner(strategy, {
+    logger,
+    eventSourceUrl: 'wss://your-osiris-server.com/ws',
+}, context);
+```
+
+**Supported topics:**
+- `market:{slug}` - Market analysis events
+- `wallet:{address}` - Wallet analysis events
+- `opps:{filter}` - Trading opportunities
+
+### Polymarket RTDS
+
+Connect directly to Polymarket's Real-Time Data Socket for live market data.
+
+#### Strategy-Based Usage
+
+Set `eventSource: 'polymarket'` in your subscriptions:
+
 ```typescript
-import { createEventRunner, type EventSubscription, type StrategyEvent } from '@osiris-ai/strategy-sdk';
+import type { 
+    CodeStrategy, 
+    EventSubscription, 
+    StrategyEvent,
+    CryptoPricesSubscription,
+    ActivitySubscription,
+    ClobMarketSubscription,
+    CommentsSubscription
+} from '@osiris-ai/strategy-sdk';
 
-class PriceAlertStrategy implements CodeStrategy {
+class MyPolymarketStrategy implements CodeStrategy {
     subscriptions: EventSubscription[] = [
-        {
-            type: 'price',
-            market: 'BTC-USD',
-            conditions: { priceChangePercent: 5 }
-        }
+        // Crypto price updates
+        { type: 'crypto_prices', symbol: 'btcusdt', eventSource: 'polymarket' },
+        
+        // Trade activity feed
+        { type: 'activity', messageType: '*', eventSource: 'polymarket' },
+        
+        // CLOB orderbook data (requires market condition ID)
+        { type: 'clob_market', marketId: 'condition-id', messageType: 'agg_orderbook', eventSource: 'polymarket' },
+        
+        // Comments and reactions
+        { type: 'comments', messageType: '*', eventSource: 'polymarket' },
     ];
 
     async onEvent(event: StrategyEvent, osiris: OsirisContext): Promise<void> {
-        osiris.log(`Price changed: ${event.data.changePercent}%`);
-        // React to price change...
+        const topic = event.data.raw?.topic;
+        
+        if (topic === 'crypto_prices') {
+            console.log(`BTC: $${event.data.price}`);
+        } else if (topic === 'activity') {
+            console.log(`Trade: ${event.data.side} ${event.data.size} @ ${event.data.price}`);
+        }
     }
 }
 
 const runner = createEventRunner(strategy, {
     logger,
-    eventSourceUrl: 'wss://your-event-server.com/ws',
-    strategyId: 'price-alert', // Optional
+    polymarket: {
+        walletAddress: '0x...',
+        // clobAuth: { key, secret, passphrase } for clob_user subscriptions
+    },
 }, context);
+```
+
+#### Polymarket Subscription Types
+
+| Type | Description | Auth Required |
+|------|-------------|---------------|
+| `crypto_prices` | Real-time BTC/ETH/etc prices | No |
+| `activity` | Global trade activity feed | No |
+| `clob_market` | Orderbook, price changes for specific market | No |
+| `comments` | Comments and reactions | No |
+| `rfq` | Request for Quote events | No |
+| `clob_user` | Your orders and trades | Yes (clobAuth) |
+
+#### CryptoPricesSubscription
 
-runner.start();
-// runner.stop();
+```typescript
+{
+    type: 'crypto_prices',
+    symbol: 'btcusdt',  // or 'ethusdt', etc.
+    eventSource: 'polymarket'
+}
 ```
 
-#### Event Types
+#### ActivitySubscription
 
 ```typescript
-type EventType = 'price' | 'orderbook' | 'time' | 'trade' | 'fill' | 'liquidation' | 'custom';
+{
+    type: 'activity',
+    eventSlug: 'will-bitcoin-hit-100k',  // optional filter
+    marketSlug: 'market-slug',           // optional filter
+    messageType: '*',                    // 'trades', 'positions', or '*'
+    eventSource: 'polymarket'
+}
 ```
 
-#### Event Subscriptions
+#### ClobMarketSubscription
 
 ```typescript
-interface EventSubscription {
-    type: EventType;
-    market?: string;
-    conditions?: {
-        priceAbove?: number;
-        priceBelow?: number;
-        priceChangePercent?: number;
-        spreadAbove?: number;
-        volumeAbove?: number;
-        cron?: string;
-        interval?: number;
-    };
+{
+    type: 'clob_market',
+    marketId: '0x1234...condition-id',   // Market condition ID
+    messageType: 'agg_orderbook',        // 'price_change', 'last_trade_price', 'tick_size_change', '*'
+    eventSource: 'polymarket'
+}
+```
+
+#### ClobUserSubscription (Requires Auth)
+
+```typescript
+{
+    type: 'clob_user',
+    messageType: '*',  // 'order', 'trade', or '*'
+    eventSource: 'polymarket'
+}
+
+// Config with clobAuth:
+const runner = createEventRunner(strategy, {
+    logger,
+    polymarket: {
+        clobAuth: {
+            key: process.env.POLYMARKET_API_KEY!,
+            secret: process.env.POLYMARKET_API_SECRET!,
+            passphrase: process.env.POLYMARKET_PASSPHRASE!,
+        }
+    }
+}, context);
+```
+
+#### CommentsSubscription
+
+```typescript
+{
+    type: 'comments',
+    parentEntityId: 'market-id',     // optional filter
+    parentEntityType: 'market',      // optional filter
+    messageType: '*',                // 'comment_created', 'reaction_created', '*'
+    eventSource: 'polymarket'
+}
+```
+
+#### RfqSubscription
+
+```typescript
+{
+    type: 'rfq',
+    messageType: '*',
+    eventSource: 'polymarket'
+}
+
+## Type Guards
+
+Use type guards for runtime type checking:
+
+```typescript
+import { 
+    // Generic subscription types
+    isMarketSubscription, 
+    isWalletSubscription,
+    isOpportunitySubscription,
+    isCustomSubscription,
+    
+    // Polymarket RTDS subscription types
+    isClobMarketSubscription,
+    isClobUserSubscription,
+    isActivitySubscription,
+    isCommentsSubscription,
+    isCryptoPricesSubscription,
+    isRfqSubscription,
+    
+    // Source routing helpers
+    isPolymarketSubscription,
+    isOsirisSubscription
+} from '@osiris-ai/strategy-sdk';
+
+// Check if subscription is for Polymarket
+if (isPolymarketSubscription(subscription)) {
+    // Subscription will be routed to Polymarket RTDS
+}
+
+// Check specific Polymarket types
+if (isClobMarketSubscription(subscription)) {
+    console.log(subscription.marketId); // TypeScript knows this is ClobMarketSubscription
+}
+
+if (isCryptoPricesSubscription(subscription)) {
+    console.log(subscription.symbol); // TypeScript knows this is CryptoPricesSubscription
 }
 ```
 
@@ -179,20 +417,34 @@ interface EventSubscription {
 
 #### `CodeStrategy`
 
-Interface that all strategies must implement (choose one execution mode):
+Interface that all strategies must implement:
 
 ```typescript
 interface CodeStrategy {
-    // Tick-based (optional if using event-based)
+    // Tick-based execution
     shouldTrigger?(osiris: OsirisContext): Promise<boolean>;
     onTrigger?(osiris: OsirisContext): Promise<void>;
-    
-    // Event-based (optional if using tick-based)
+
+    // Event-based execution
     subscriptions?: EventSubscription[];
     onEvent?(event: StrategyEvent, osiris: OsirisContext): Promise<void>;
 }
 ```
 
+#### `StrategyEvent`
+
+Event passed to `onEvent` handler:
+
+```typescript
+interface StrategyEvent {
+    type: EventType;
+    timestamp: number;
+    market?: string;   // For market events
+    wallet?: string;   // For wallet events
+    data: EventData;
+}
+```
+
 #### `OsirisContext`
 
 The context object passed to your strategy methods:
@@ -203,21 +455,19 @@ interface OsirisContext {
     hyperliquid?: HyperliquidAPI;    // Available when market='hyperliquid'
     ta: TechnicalAnalysisAPI;        // Technical analysis functions
     state: OsirisState;              // State management
-    signer: SignerAPI;               // Transaction signer
-    log: (message: string, meta?: any) => void; // Logging function
+    signer?: SignerAPI;              // Transaction signer (if configured)
+    log: (message: string, meta?: any) => void;
 }
 ```
 
 ### State Management
 
-#### In Strategy
+#### In-Memory State (for testing)
 
 ```typescript
-// Get state
-const value = await osiris.state.get('myKey');
+import { MemoryStateManager } from '@osiris-ai/strategy-sdk';
 
-// Set state
-await osiris.state.set('myKey', { count: 42 });
+const stateManager = new MemoryStateManager();
 ```
 
 #### Redis State (for production)
@@ -232,83 +482,35 @@ const stateManager = new RedisStateManager(
 );
 
 await stateManager.connect();
-// ... use stateManager
-await stateManager.disconnect();
 ```
 
 ### Market APIs
 
-#### Polymarket Trading
-
-```typescript
-if (osiris.polymarket) {
-    // Initialize trading client (required before trading)
-    await osiris.polymarket.initializeTradingClient();
-    
-    // ============================================
-    // Convenience Trading Methods (Recommended)
-    // ============================================
-    
-    // Limit orders
-    await osiris.polymarket.buyLimit(tokenId, 0.65, 100);    // Buy 100 shares @ $0.65
-    await osiris.polymarket.sellLimit(tokenId, 0.70, 50);    // Sell 50 shares @ $0.70
-    
-    // Market orders (execute immediately)
-    await osiris.polymarket.buyMarket(tokenId, 100);         // Buy $100 worth
-    await osiris.polymarket.sellMarket(tokenId, 50);         // Sell 50 shares
-    
-    // ============================================
-    // Full Order Methods (More control)
-    // ============================================
-    
-    await osiris.polymarket.createLimitOrder({
-        tokenId: '0x...',
-        price: 0.65,
-        size: 100,
-        side: 'BUY',
-        feeRateBps: '0',
-    });
-    
-    await osiris.polymarket.createMarketOrder({
-        tokenId: '0x...',
-        amount: 100,
-        side: 'BUY',
-        slippageTolerance: 0.05,
-    });
-    
-    // Order management
-    const orders = await osiris.polymarket.getOpenOrders();
-    await osiris.polymarket.cancelOrder(orderId);
-    await osiris.polymarket.cancelAllOrders();
-    
-    // Market data
-    const market = await osiris.polymarket.getMarket('market-slug');
-    const markets = await osiris.polymarket.getMarkets({ active: true, limit: 50 });
-    const orderBook = await osiris.polymarket.getOrderBook(tokenId);
-}
-```
-
-#### Hyperliquid Trading
+#### Hyperliquid API
 
 ```typescript
 if (osiris.hyperliquid) {
-    // Get price
     const price = await osiris.hyperliquid.getPrice('BTC');
-
-    // Get position
     const position = await osiris.hyperliquid.getPosition('BTC');
-
-    // Get all positions
     const positions = await osiris.hyperliquid.getPositions();
+}
+```
 
-    // Get candle data
-    const candles = await osiris.hyperliquid.getCandleSnapshot(
-        'BTC', '1d', startTime, endTime
-    );
+#### Polymarket API
 
-    // Execute trades
-    await osiris.hyperliquid.buy('BTC', 0.1);
-    await osiris.hyperliquid.sell('BTC', 0.1);
+```typescript
+if (osiris.polymarket) {
+    const market = await osiris.polymarket.getMarket('market-slug');
+    const markets = await osiris.polymarket.getMarkets({ active: true });
+
+    // Trading (requires initialization)
+    await osiris.polymarket.initializeTradingClient();
+    await osiris.polymarket.createLimitOrder({
+        tokenId: 'token-id',
+        side: 'BUY',
+        price: 0.5,
+        size: 10,
+    });
 }
 ```
 
@@ -318,18 +520,13 @@ if (osiris.hyperliquid) {
 // Calculate RSI
 const rsi = osiris.ta.calculate('rsi_14', ohlcvData, { period: 14 });
 
-// Calculate MACD (returns [MACD, signal, histogram])
+// Calculate MACD
 const macd = osiris.ta.calculate('macd_12_26_9', ohlcvData, {
     fastPeriod: 12,
     slowPeriod: 26,
     signalPeriod: 9
 });
 
-// Get specific component from multi-value indicator
-const macdSignal = osiris.ta.calculate('macd_12_26_9', ohlcvData, {
-    component: 'signal'
-});
-
 // Available indicators:
 // Single-value: rsi, sma, ema, atr, adx, obv, cci, mfi, vwap, williams_r, roc, psar, wma
 // Multi-value: macd, bollinger_bands, stochastic, stochastic_rsi, keltner_channels
@@ -337,111 +534,44 @@ const macdSignal = osiris.ta.calculate('macd_12_26_9', ohlcvData, {
 
 ### Signing Transactions
 
-#### Using Private Key Signer
-
 ```typescript
-import { PrivateKeySigner, createOsirisContext } from '@osiris-ai/strategy-sdk';
+import { PrivateKeySigner, OsirisSigner } from '@osiris-ai/strategy-sdk';
 
+// Private key signer
 const signer = new PrivateKeySigner({
     privateKey: process.env.PRIVATE_KEY!,
 });
 
-const address = signer.getAddress();
-
-const context = createOsirisContext({
-    strategyId: 'my-strategy',
-    market: 'polymarket',
-    userAddress: address!,
-    signer,
-});
-```
-
-#### Using Osiris Hub Signer
-
-```typescript
-import { OsirisSigner, createOsirisContext } from '@osiris-ai/strategy-sdk';
-
-const signer = new OsirisSigner({
+// Osiris Hub signer (for managed wallets)
+const osirisSigner = new OsirisSigner({
     hubBaseUrl: 'https://api.osirislabs.xyz/v1',
-    accessToken: process.env.OSIRIS_ACCESS_TOKEN!,
-    connectionId: process.env.WALLET_CONNECTION_ID!,
+    accessToken: 'your-oauth-token',
+    connectionId: 'wallet-connection-id',
 });
 
+// Use in context
 const context = createOsirisContext({
     strategyId: 'my-strategy',
     market: 'polymarket',
-    userAddress: '0x...',
+    userAddress: signer.getAddress()!,
     signer,
-    polymarketOptions: {
-        useMcpForOrders: true,
-        mcpUrl: 'https://gateway.backend.osirislabs.xyz/@osiris/polymarket/mcp',
-        mcpAccessToken: process.env.MCP_ACCESS_TOKEN!,
-    },
 });
 ```
 
-### Logging
-
-```typescript
-import { createConsoleLogger } from '@osiris-ai/strategy-sdk';
-
-const logger = createConsoleLogger();
-```
-
 ## Examples
 
-See the `examples/` directory:
+See the `examples/` directory for complete working examples:
 
-- `example-rsi.ts` - RSI-based trading strategy (tick-based)
-- `example-polymarket.ts` - Polymarket arbitrage strategy (tick-based)
-- `example-event-strategy.ts` - Price alert strategy (event-based)
-- `example-usage.ts` - Complete usage examples
-- `example-signer.ts` - Signer usage examples
-
-## Strategy Patterns
-
-### Tick-Based Strategy Pattern
-
-```typescript
-class MyTickStrategy implements CodeStrategy {
-    async shouldTrigger(osiris: OsirisContext): Promise<boolean> {
-        // Called every tick - return true to execute
-        return true;
-    }
-
-    async onTrigger(osiris: OsirisContext): Promise<void> {
-        // Your trading logic
-    }
-}
-```
-
-### Event-Based Strategy Pattern
-
-```typescript
-class MyEventStrategy implements CodeStrategy {
-    subscriptions: EventSubscription[] = [
-        { type: 'price', market: 'BTC-USD', conditions: { priceChangePercent: 5 } }
-    ];
-
-    async onEvent(event: StrategyEvent, osiris: OsirisContext): Promise<void> {
-        // Triggered by real-time events
-        osiris.log(`Event: ${event.type} - ${JSON.stringify(event.data)}`);
-    }
-}
-```
+- `example-event-strategy.ts` - Event-based price alert strategy
+- `example-polymarket-events.ts` - Polymarket RTDS integration
 
 ## Best Practices
 
-1. **State Management**: Use `osiris.state` for persistent data that should survive restarts
-2. **Error Handling**: Always wrap API calls in try-catch blocks
-3. **Rate Limiting**: Be mindful of API rate limits when making frequent calls
-4. **Testing**: Use `MemoryStateManager` for testing, `RedisStateManager` for production
-5. **Logging**: Use `osiris.log()` for strategy-specific logs
-6. **Execution Mode**: Choose tick-based for polling, event-based for real-time reactions
-
-## TypeScript Support
-
-The SDK is written in TypeScript and provides full type definitions. All types are exported.
+1. **Choose the right execution mode**: Use tick-based for periodic checks, event-based for real-time reactions
+2. **State Management**: Use `osiris.state` for persistent data that should survive restarts
+3. **Error Handling**: Always wrap API calls in try-catch blocks
+4. **Rate Limiting**: Be mindful of API rate limits when making frequent calls
+5. **Testing**: Use `MemoryStateManager` for testing, `RedisStateManager` for production
 
 ## License