wiz-trader 0.34.0__tar.gz → 0.36.0__tar.gz

{wiz_trader-0.34.0/src/wiz_trader.egg-info → wiz_trader-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wiz_trader
-Version: 0.34.0
+Version: 0.36.0
 Summary: A Python SDK for connecting to the Wizzer.
 Home-page: https://bitbucket.org/wizzer-tech/quotes_sdk.git
 Author: Pawan Wagh
@@ -38,6 +38,7 @@ Dynamic: requires-python
     - [Callbacks](#callbacks)
     - [Subscribing to Instruments](#subscribing-to-instruments)
     - [Unsubscribing from Instruments](#unsubscribing-from-instruments)
+    - [Account Events](#account-events)
     - [Handling WebSocket Connection](#handling-websocket-connection)
     - [Complete Examples](#quotes-client-examples)
 5. [Wizzer Client](#wizzer-client)
@@ -253,6 +254,347 @@ ws.unsubscribe(["NSE:RELIANCE:2885"])
 - Can be called multiple times for different instrument sets
 - No callback fired for unsubscribed instruments
 
+### Account Events
+
+The QuotesClient now supports automatic reception of account-related events (orders, trades, positions, holdings) from the quotes server. These events are automatically pushed to SDK users via dedicated callback handlers based on the event type.
+
+#### Event Handlers
+
+Register event handlers to receive real-time updates for your account activity:
+
+```python
+def on_order(ws, order):
+    print(f"Order event: {order}")
+
+def on_trade(ws, trade):
+    print(f"Trade event: {trade}")
+
+def on_position(ws, position):
+    print(f"Position event: {position}")
+
+def on_holding(ws, holding):
+    print(f"Holding event: {holding}")
+
+# Register event handlers
+client.on_order = on_order
+client.on_trade = on_trade
+client.on_position = on_position
+client.on_holding = on_holding
+```
+
+#### Key Features
+
+- **Automatic Event Reception**: No explicit subscription needed - events are automatically sent based on your JWT token's account ID and strategy ID
+- **Optional Handlers**: Events are silently dropped if no handler is registered - you only receive what you need
+- **Message Normalization**: The SDK automatically handles different message formats and delivers clean, flattened event data to your handlers
+- **Error Resilience**: Handler exceptions are caught and logged without breaking the event flow
+- **Backward Compatible**: Existing tick and Greeks functionality remains unchanged
+
+#### Event Data Structure
+
+All event handlers receive flattened event data with the event type preserved:
+
+```python
+# Example order event data
+{
+    "_id": "order_01k10np7weemkv812nx55bppw5",
+    "accountEntityType": "client",
+    "accountId": "user_01j9brznsffphvzqn9gzyj1frw",
+    "avgPrice": 72.65,
+    "broker": "wizzer",
+    "brokerOrderId": "dssorder_175344314711184",
+    "brokerTimestamp": "2025-07-25T11:32:28.147Z",
+    "cancelledQty": 0,
+    "completedAt": "2025-07-25T11:32:28.147Z",
+    "createdAt": "2025-07-25T11:32:27.722Z",
+    "disclosedQty": 0,
+    "exchange": "NSE",
+    "exchangeOrderId": "dssx_1753443147",
+    "exchangeToken": 11184,
+    "exchangeUpdateTimestamp": "2025-07-25T11:32:28.147Z",
+    "executionType": "regular",
+    "filledQty": 1,
+    "guid": "t0lVueivgBgcEh2k_BP",
+    "instrumentType": "EQLC",
+    "isDealer": false,
+    "isOrderModified": false,
+    "legs": [],
+    "marginUsed": 0,
+    "meta": {
+        "dss": {"orderId": "order_01k10np7weemkv812nx55bppw5"},
+        "source": "wizzer.dss",
+        "wizzer": {"mode": "paper_trading"}
+    },
+    "orderType": "MARKET",
+    "parentOrderId": "",
+    "pendingQty": 1,
+    "placedBy": "user_01j9brznsffphvzqn9gzyj1frw",
+    "price": 0,
+    "product": "CNC",
+    "qty": 1,
+    "remarks": "",
+    "segment": "NSECM",
+    "slPrice": 0,
+    "slTriggerPrice": 0,
+    "sqOffHoldingId": "",
+    "sqOffPositionId": "",
+    "status": "COMPLETED",
+    "stoploss": 0,
+    "stoplossOrderId": "",
+    "strategy": {
+        "id": "stgy_01jtn7t3erf8ss78spqy40k8en",
+        "identifier": "S-608377",
+        "name": "Test 1122"
+    },
+    "target": 0,
+    "targetOrderId": "",
+    "tradingSymbol": "IDFCFIRSTB",
+    "transactionType": "BUY",
+    "triggerId": "",
+    "triggerPrice": 0,
+    "updatedAt": "2025-07-25T11:32:28.254Z",
+    "userId": "user_01j9brznsffphvzqn9gzyj1frw",
+    "validity": "DAY",
+    "variety": "REGULAR"
+}
+
+# Example trade event data
+{
+    "_id": "trade_01k10np8rqef793zr93ctqj0wt",
+    "accountId": "user_01j9brznsffphvzqn9gzyj1frw",
+    "avgPrice": 72.65,
+    "broker": "wizzer",
+    "brokerOrderId": "dssorder_175344314711184",
+    "createdAt": "2025-07-25T11:32:28.567Z",
+    "exchange": "NSE",
+    "exchangeOrderId": "dssx_1753443147",
+    "exchangeTimestamp": "2025-07-25T11:32:28.147Z",
+    "exchangeToken": 11184,
+    "isDividend": false,
+    "meta": {
+        "dss": {"orderId": "order_01k10np7weemkv812nx55bppw5"},
+        "source": "wizzer.dss",
+        "wizzer": {"mode": "paper_trading"}
+    },
+    "orderId": "order_01k10np7weemkv812nx55bppw5",
+    "orderType": "MARKET",
+    "parentOrderId": "",
+    "parentTradeId": "",
+    "product": "CNC",
+    "qty": 1,
+    "segment": "NSECM",
+    "strategy": {
+        "id": "stgy_01jtn7t3erf8ss78spqy40k8en",
+        "identifier": "S-608377",
+        "name": "Test 1122"
+    },
+    "tradeId": "dsstrade_50PccSfWvsCg-Cr5dQE",
+    "tradingSymbol": "IDFCFIRSTB",
+    "transactionType": "BUY",
+    "updatedAt": "2025-07-25T11:32:28.567Z",
+    "userId": "user_01j9brznsffphvzqn9gzyj1frw"
+}
+
+# Example position event data
+{
+    "_id": "pos_01k10np8t7e0fs63q52hacbx8m",
+    "accountEntityType": "client",
+    "accountId": "user_01j9brznsffphvzqn9gzyj1frw",
+    "bep": 0,
+    "broker": "wizzer",
+    "buyAvgPrice": 72.65,
+    "buyOrders": ["order_01k10np7weemkv812nx55bppw5"],
+    "buyQty": 1,
+    "buyTrades": ["trade_01k10np8rqef793zr93ctqj0wt"],
+    "buyValue": 72.65,
+    "closePrice": 0,
+    "createdAt": "2025-07-25T11:32:28.614Z",
+    "exchange": "NSE",
+    "exchangeToken": 11184,
+    "instrumentType": "EQLC",
+    "lotSize": 1,
+    "meta": {
+        "source": "wizzer.dss",
+        "wizzer": {"mode": "paper_trading"}
+    },
+    "netQty": 1,
+    "pnlPercentage": 0,
+    "product": "CNC",
+    "realisedPnlToday": 0,
+    "segment": "NSECM",
+    "sellAvgPrice": 0,
+    "sellOrders": [],
+    "sellQty": 0,
+    "sellTrades": [],
+    "sellValue": 0,
+    "slPrice": null,
+    "slTriggerPrice": null,
+    "status": "open",
+    "stoploss": 0,
+    "strategy": {
+        "id": "stgy_01jtn7t3erf8ss78spqy40k8en",
+        "identifier": "S-608377",
+        "name": "Test 1122"
+    },
+    "target": 0,
+    "tradingSymbol": "IDFCFIRSTB",
+    "unrealisedPnlToday": 0,
+    "updatedAt": "2025-07-25T11:32:28.614Z",
+    "userId": "user_01j9brznsffphvzqn9gzyj1frw"
+}
+
+# Example holding event data
+{
+    "_id": "holding_01k10np8t7e0fs63q52hacbx8m",
+    "accountEntityType": "client",
+    "accountId": "user_01j9brznsffphvzqn9gzyj1frw",
+    "bep": 0,
+    "broker": "wizzer",
+    "buyAvgPrice": 72.65,
+    "buyOrders": ["order_01k10np7weemkv812nx55bppw5"],
+    "buyQty": 1,
+    "buyTrades": ["trade_01k10np8rqef793zr93ctqj0wt"],
+    "buyValue": 72.65,
+    "closePrice": 0,
+    "createdAt": "2025-07-25T11:32:28.614Z",
+    "exchange": "NSE",
+    "exchangeToken": 11184,
+    "instrumentType": "EQLC",
+    "lotSize": 1,
+    "meta": {
+        "source": "wizzer.dss",
+        "wizzer": {"mode": "paper_trading"}
+    },
+    "netQty": 1,
+    "pnlPercentage": 0,
+    "product": "CNC",
+    "realisedPnlToday": 0,
+    "segment": "NSECM",
+    "sellAvgPrice": 0,
+    "sellOrders": [],
+    "sellQty": 0,
+    "sellTrades": [],
+    "sellValue": 0,
+    "slPrice": null,
+    "slTriggerPrice": null,
+    "status": "open",
+    "stoploss": 0,
+    "strategy": {
+        "id": "stgy_01jtn7t3erf8ss78spqy40k8en",
+        "identifier": "S-608377",
+        "name": "Test 1122"
+    },
+    "target": 0,
+    "tradingSymbol": "IDFCFIRSTB",
+    "unrealisedPnlToday": 0,
+    "updatedAt": "2025-07-25T11:32:28.614Z",
+    "userId": "user_01j9brznsffphvzqn9gzyj1frw"
+}
+```
+
+#### Complete Event Handling Example
+
+```python
+from wiz_trader import QuotesClient
+
+# Initialize client
+client = QuotesClient(
+    base_url="wss://websocket-url/quotes",
+    token="your-jwt-token",
+    log_level="info"
+)
+
+def on_order(ws, order):    
+    # React to order status changes
+    if order['status'] == ORDER_STATUS_COMPLETED:
+        print(f"Order {order['_id']} completed!")
+    elif order['status'] == ORDER_STATUS_REJECTED:
+        print(f"Order {order['_id']} rejected: {order.get('remarks', 'Unknown')}")
+
+def on_trade(ws, trade):
+    print(f"Trade executed: {trade['qty']} x {trade['tradingSymbol']} @ {trade['avgPrice']}")
+
+def on_position(ws, position):
+    print(f"Position update: {position['tradingSymbol']} = {position['netQty']} (PnL: {position.get('unrealisedPnlToday', 0)})")
+
+def on_holding(ws, holding):
+    print(f"Holding update: {holding['tradingSymbol']} = {holding['netQty']}")
+
+def on_connect(ws):
+    print("Connected! Ready to receive events.")
+    # Also subscribe to some ticks if needed
+    ws.subscribe(["NSE:SBIN:3045"], mode="ticks")
+
+# Register all handlers
+client.on_order = on_order
+client.on_trade = on_trade
+client.on_position = on_position
+client.on_holding = on_holding
+client.on_connect = on_connect
+
+# Connect and receive events
+client.connect()
+```
+
+#### Event-Driven Trading Strategy Example
+
+```python
+class EventDrivenStrategy:
+    def __init__(self):
+        self.orders = {}
+        self.positions = {}
+        self.pending_orders = set()
+    
+    def on_order_event(self, ws, order):
+        order_id = order['_id']
+        self.orders[order_id] = order
+        
+        # Track pending orders
+        if order['status'] == ORDER_STATUS_OPEN:
+            self.pending_orders.add(order_id)
+        elif order_id in self.pending_orders:
+            self.pending_orders.remove(order_id)
+        
+        # Log order lifecycle
+        print(f"Order {order_id}: {order['status']}")
+        
+        # React to rejections
+        if order['status'] == ORDER_STATUS_REJECTED:
+            print(f"Order rejected! Reason: {order.get('remarks', 'Unknown')}")
+            # Implement retry logic or alternative strategy
+    
+    def on_position_event(self, ws, position):
+        symbol = position['tradingSymbol']
+        self.positions[symbol] = position
+        
+        # Monitor position changes
+        print(f"Position {symbol}: Qty={position['netQty']}, PnL={position.get('unrealisedPnlToday', 0)}")
+        
+        # Implement stop-loss or take-profit logic
+        pnl = position.get('unrealisedPnlToday', 0)
+        if pnl < -100:  # Stop loss at -100
+            print(f"Stop loss triggered for {symbol}")
+            # Place exit order
+        elif pnl > 200:  # Take profit at 200
+            print(f"Take profit triggered for {symbol}")
+            # Place exit order
+    
+    def on_trade_event(self, ws, trade):
+        print(f"Trade executed: {trade['qty']} @ {trade['avgPrice']}")
+        # Update internal trade log, calculate VWAP, etc.
+
+# Initialize strategy
+strategy = EventDrivenStrategy()
+
+# Set up client with strategy handlers
+client = QuotesClient(base_url="wss://...", token="...")
+client.on_order = strategy.on_order_event
+client.on_position = strategy.on_position_event
+client.on_trade = strategy.on_trade_event
+
+client.connect()
+```
+
 ### Complete Examples
 
 #### Blocking Example
@@ -425,6 +767,7 @@ Available constants:
 - Transaction types: `TRANSACTION_TYPE_BUY`, `TRANSACTION_TYPE_SELL`
 - Product types: `PRODUCT_CNC`, `PRODUCT_MIS`, `PRODUCT_NRML`
 - Order types: `ORDER_TYPE_MARKET`, `ORDER_TYPE_LIMIT`, `ORDER_TYPE_SL`, `ORDER_TYPE_SLM`
+- Order status: `ORDER_STATUS_OPEN`, `ORDER_STATUS_CANCELLED`, `ORDER_STATUS_REJECTED`, `ORDER_STATUS_PENDING`, `ORDER_STATUS_COMPLETED`
 - Validity types: `VALIDITY_DAY`, `VALIDITY_IOC`, `VALIDITY_GTT`
 - Variety types: `VARIETY_REGULAR`, `VARIETY_AMO`, `VARIETY_BO`, `VARIETY_CO`
 - Exchanges: `EXCHANGE_NSE`, `EXCHANGE_BSE`, `EXCHANGE_WZR`
@@ -3663,3 +4006,243 @@ results = client.run_screener(
     limit=10
 )
 ```
+
+## KV Store Integration
+
+The WizzerClient includes comprehensive Key-Value (KV) store functionality for persistent data management. This feature allows you to store configuration data, state information, user preferences, and other persistent data associated with your trading strategies.
+
+### Supported Data Types
+
+The KV store supports all JSON-serializable data types:
+
+- **STRING**: Text values (`"production"`, `"user123"`)
+- **NUMBER**: Integer and float values (`42`, `150.25`)
+- **BOOLEAN**: True/false values (`True`, `False`)
+- **ARRAY**: Lists of values (`["AAPL", "GOOGL", "MSFT"]`)
+- **OBJECT**: Dictionaries/objects (`{"positions": 30, "cash": 50000}`)
+
+### Available Constants
+
+```python
+client.KV_TYPE_STRING   # "string"
+client.KV_TYPE_NUMBER   # "number" 
+client.KV_TYPE_BOOLEAN  # "boolean"
+client.KV_TYPE_ARRAY    # "array"
+client.KV_TYPE_OBJECT   # "object"
+```
+
+### Core CRUD Operations
+
+#### Create Key-Value Pair
+
+```python
+# Store different data types
+client.create_kv("environment", "production")
+client.create_kv("trade_count", 42)
+client.create_kv("is_active", True)
+client.create_kv("symbols", ["AAPL", "GOOGL", "MSFT"])
+
+# Store complex configuration with TTL (expires in 1 hour)
+config = {
+    "risk_level": "medium",
+    "max_positions": 10,
+    "stop_loss_pct": 0.05,
+    "take_profit_pct": 0.15
+}
+client.create_kv("strategy_config", config, ttl=3600)
+```
+
+#### Retrieve Key-Value Pair
+
+```python
+# Get a single KV pair
+data = client.get_kv("strategy_config")
+print(data["value"])          # The stored object
+print(data["type"])           # "object"
+print(data["ttl"])            # Remaining time to live (if set)
+
+# Access nested values
+risk_level = data["value"]["risk_level"]  # "medium"
+```
+
+#### Update Key-Value Pair (Complete Replacement)
+
+```python
+# Complete replacement of existing key
+new_config = {"risk_level": "high", "max_positions": 5}
+client.update_kv("strategy_config", new_config, ttl=1800)
+```
+
+#### Patch Key-Value Pair (Partial Update)
+
+```python
+# For objects - merges with existing data
+client.patch_kv("strategy_config", {"last_updated": "2024-01-15"})
+
+# For non-objects - replaces entirely  
+client.patch_kv("trade_count", 50)
+
+# Update only TTL
+client.patch_kv("strategy_config", ttl=7200)
+```
+
+#### Delete Key-Value Pair
+
+```python
+response = client.delete_kv("old_config")
+if response["success"]:
+    print("Key deleted successfully")
+```
+
+### List Operations
+
+#### Get All KV Pairs (with values)
+
+```python
+# Get first page (20 items)
+kvs = client.get_all_kvs(page_no=1)
+
+# Get all pages automatically
+all_kvs = client.get_all_kvs(paginate=True)
+
+for kv in all_kvs:
+    print(f"Key: {kv['key']}")
+    print(f"Type: {kv['type']}")
+    print(f"Value: {kv['value']}")
+```
+
+#### Get Keys Only (memory efficient)
+
+```python
+# Get all keys without values (faster for large datasets)
+keys = client.get_kv_keys(paginate=True)
+
+for key_info in keys:
+    print(f"Key: {key_info['key']}, Type: {key_info['type']}")
+    if 'ttl' in key_info:
+        print(f"  TTL: {key_info['ttl']} seconds remaining")
+```
+
+### Advanced Usage Examples
+
+#### Strategy Configuration Management
+
+```python
+# Store strategy parameters
+params = {
+    "moving_average_period": 20,
+    "rsi_oversold": 30,
+    "rsi_overbought": 70,
+    "position_size": 0.02
+}
+client.create_kv("strategy_params", params)
+
+# Update specific parameters using patch (merges with existing)
+client.patch_kv("strategy_params", {"moving_average_period": 50})
+```
+
+#### State Persistence
+
+```python
+# Save current portfolio state
+portfolio_state = {
+    "cash_balance": 50000,
+    "open_positions": 5,
+    "daily_pnl": 1250.75,
+    "last_updated": "2024-01-15T15:30:00Z"
+}
+client.create_kv("portfolio_state", portfolio_state, ttl=3600)
+
+# Update state periodically
+client.patch_kv("portfolio_state", {
+    "daily_pnl": 1500.25,
+    "last_updated": "2024-01-15T16:00:00Z"
+})
+```
+
+#### Feature Flags
+
+```python
+# Enable/disable features dynamically
+features = {
+    "advanced_charts": True,
+    "paper_trading": True,
+    "options_trading": False,
+    "algo_trading": True
+}
+client.create_kv("feature_flags", features)
+
+# Toggle a feature
+client.patch_kv("feature_flags", {"options_trading": True})
+```
+
+#### Data Caching with TTL
+
+```python
+# Cache market data with short TTL (5 minutes)
+market_status = {
+    "nse_open": True,
+    "bse_open": True,
+    "last_checked": "2024-01-15T09:15:00Z"
+}
+client.create_kv("market_status", market_status, ttl=300)
+```
+
+### Object Merge Behavior
+
+For OBJECT type data, the `patch_kv` method performs intelligent merging:
+
+```python
+# Initial object
+client.create_kv("user_prefs", {
+    "theme": "dark",
+    "notifications": True,
+    "language": "en"
+})
+
+# Patch merges new fields with existing ones
+client.patch_kv("user_prefs", {
+    "notifications": False,  # Updates existing field
+    "timezone": "UTC"        # Adds new field
+})
+
+# Result: {"theme": "dark", "notifications": False, "language": "en", "timezone": "UTC"}
+```
+
+### Delete All KV Pairs
+
+The `delete_all_kv` method allows you to remove all key-value pairs for a strategy at once:
+
+```python
+# Delete all KV pairs for the current strategy
+response = client.delete_all_kv()
+print(f"Deleted {response['deleted']} key-value pairs")
+
+# Example response:
+# {
+#     "success": True,
+#     "deleted": 15,
+#     "message": "Successfully deleted 15 key-value pairs"
+# }
+
+# Common usage - reset strategy state before reinitialization
+def reset_strategy_state():
+    """Reset all persistent state for the strategy."""
+    # Clear all existing KV pairs
+    result = client.delete_all_kv()
+    print(f"Cleared {result['deleted']} KV pairs")
+    
+    # Reinitialize with default configuration
+    client.create_kv("config", {
+        "mode": "production",
+        "risk_percentage": 0.02,
+        "max_positions": 10
+    })
+    client.create_kv("state", {
+        "initialized": True,
+        "start_time": datetime.now().isoformat()
+    })
+    print("Strategy state reset successfully")
+
+# Use with caution - this operation cannot be undone!
+```