wiz-trader 0.16.0__tar.gz → 0.18.0__tar.gz

{wiz_trader-0.16.0/src/wiz_trader.egg-info → wiz_trader-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wiz_trader
-Version: 0.16.0
+Version: 0.18.0
 Summary: A Python SDK for connecting to the Wizzer.
 Home-page: https://bitbucket.org/wizzer-tech/quotes_sdk.git
 Author: Pawan Wagh
@@ -47,6 +47,7 @@ Dynamic: requires-python
     - [Order Management](#order-management)
     - [Portfolio Management](#portfolio-management)
     - [Basket Management](#basket-management)
+    - [Instrument Management](#instrument-management)
     - [Complete Examples](#wizzer-client-examples)
 6. [Common Use Cases](#common-use-cases)
 7. [Error Handling](#error-handling)
@@ -633,6 +634,587 @@ rebalance_response = client.rebalance_basket(
 )
 ```
 
+### Instrument Management
+## Instrument Data APIs
+
+### Get Instrument Metrics
+
+Fetch detailed information and metrics for specific instruments:
+
+```python
+# Get metrics for a single equity instrument
+equity_info = client.get_instrument_metrics(identifiers=["NSE:SBIN:3045"])
+print(f"SBIN Last Price: {equity_info[0]['ltp']}")
+print(f"SBIN 52-week High: {equity_info[0]['week52High']}")
+
+# Get metrics for multiple instruments of different types
+instruments_info = client.get_instrument_metrics(
+    identifiers=[
+        "NSE:AARTIIND:7",              # Equity
+        "NSE:NIFTY26DEC11000CE:61009", # Option
+        "NSE:SBIN25MAYFUT:57515"       # Future
+    ]
+)
+
+# Print detailed information for each instrument
+for instrument in instruments_info:
+    print(f"{instrument['tradingSymbol']} ({instrument['instrumentType']}):")
+    print(f"  LTP: {instrument['ltp']}")
+    print(f"  Exchange: {instrument['exchange']}")
+    print(f"  Segment: {instrument['segment']}")
+    if instrument.get('bhavcopy'):
+        print(f"  Volume: {instrument['bhavcopy']['volume']}")
+        print(f"  OHLC: {instrument['bhavcopy']['open']}/{instrument['bhavcopy']['high']}/"
+              f"{instrument['bhavcopy']['low']}/{instrument['bhavcopy']['close']}")
+```
+
+#### Response Structure for Instrument Metrics
+
+The `get_instrument_metrics` method returns a list of dictionaries, each with the following structure:
+
+```python
+[
+    {
+        # Instrument name if available
+        "name": "",
+        
+        # Trading symbol
+        "tradingSymbol": "AARTIIND",
+        
+        # Exchange code
+        "exchange": "NSE",
+        
+        # Bid price if available
+        "bid": 0,
+        
+        # Size of total bids at best bid price
+        "bidSize": 0,
+        
+        # Ask (offer) price
+        "ask": 0,
+        
+        # Size of total asks at best ask price
+        "askSize": 0,
+        
+        # Last traded price
+        "ltp": 450.05,
+        
+        # Trading volume
+        "volume": 0,
+        
+        # Lot size for the instrument
+        "lotSize": 1,
+        
+        # Mid price ((bid+ask)/2)
+        "mid": 0,
+        
+        # Market capitalization (for equities)
+        "marketCap": 0,
+        
+        # Dividend yield percentage (for equities)
+        "dividendYield": 0,
+        
+        # Last dividend date
+        "dividendDate": "",
+        
+        # Daily Open-High-Low-Close values
+        "ohlc": {
+            "open": 0,
+            "high": 0,
+            "low": 0,
+            "close": 0
+        },
+        
+        # Industry classification (for equities)
+        "industry": "",
+        
+        # Sector classification (for equities)
+        "sector": "",
+        
+        # Relevant indicators for underlying assets (for derivatives)
+        "underlyingIndicators": "",
+        
+        # Net change in price
+        "netChange": 0,
+        
+        # Net change in percentage
+        "netChangePercentage": 0,
+        
+        # Beta value (for equities)
+        "beta": 0,
+        
+        # Liquidity rating
+        "liquidityRating": 0,
+        
+        # Implied volatility metrics (for options)
+        "iv": {
+            "index": 0,
+            "indexRank": 0,
+            "percentile": 0,
+            "change5Days": 0,
+            "change30Days": 0,
+            "ivHvChange30Days": 0
+        },
+        
+        # Historical volatility metrics
+        "hv": {
+            "change30Days": 0,
+            "change60Days": 0,
+            "change90Days": 0
+        },
+        
+        # Minimum price movement
+        "tickSize": 0.05,
+        
+        # Previous day's trading summary
+        "bhavcopy": {
+            "open": 458.4,
+            "high": 470.9,
+            "low": 440.75,
+            "close": 448.55,
+            "volume": 3544523,
+            "turnover": 1632822505.15,
+            "totalTrades": 59999
+        },
+        
+        # Exchange token identifier
+        "exchangeToken": 7,
+        
+        # Market segment
+        "segment": "NSECM",
+        
+        # Whether the instrument is actively traded
+        "isTraded": false,
+        
+        # Complete instrument identifier
+        "identifier": "NSE:AARTIIND:7",
+        
+        # Instrument type code
+        "instrumentType": "EQLC",
+        
+        # Option type (for options) - CE or PE
+        "optionType": "",
+        
+        # Expiry date (for derivatives)
+        "expiry": "",
+        
+        # International Securities Identification Number
+        "isin": "INE769A01020",
+        
+        # Margin requirement percentage
+        "margin": 19.43,
+        
+        # 52-week high price
+        "week52High": 765.5,
+        
+        # 52-week low price
+        "week52Low": 344.2,
+        
+        # Maximum allowed trade volume
+        "maxTradeVolume": 2147483647,
+        
+        # Price band limits
+        "priceBand": {
+            "high": 493.4,
+            "low": 403.7,
+            "creditRating": {
+                "lower": 403.7,
+                "higher": 493.4
+            }
+        }
+    },
+    # Additional instruments...
+]
+```
+
+Note that certain fields may have zero or empty values if the data is not available from the exchange or if it's not applicable to that instrument type.
+
+### Options Chain
+
+#### Get Option Expiry List
+
+Fetch available expiry dates for an instrument's options:
+
+```python
+# For a stock
+expiry_list = client.get_option_expiry_list("NSE:SBIN:3045")
+
+# For an index
+nifty_expiry = client.get_option_expiry_list("NSE:NIFTY 50:26000")
+
+# Print all available expiry dates
+for expiry in expiry_list.get('expiryList', []):
+    print(f"{expiry['date']} - {expiry['contract']} " +
+          f"(Futures: {'Yes' if expiry['isFuturesExpiry'] else 'No'}, " +
+          f"Options: {'Yes' if expiry['isOptionsExpiry'] else 'No'})")
+```
+
+#### Response Structure
+
+The response is a JSON object with the following structure:
+
+```json
+{
+  "exchange": "NSE",                // Exchange of the instrument
+  "tradingSymbol": "SBIN",          // Trading symbol
+  "exchangeToken": 3045,            // Exchange token
+  "identifier": "NSE:SBIN:3045",    // Full identifier
+  "expiryList": [                   // Array of expiry objects
+    {
+      "date": "2025-05-29",         // Expiry date in YYYY-MM-DD format
+      "contract": "near_month",     // Contract type (see below)
+      "isFuturesExpiry": true,      // Whether futures expire on this date
+      "isOptionsExpiry": true       // Whether options expire on this date
+    },
+    // More expiry objects...
+  ]
+}
+```
+
+For index options like NIFTY, the response will typically include more expiry dates, including weekly options and longer-dated quarterly options.
+
+The `expiryList` array contains objects with the following fields:
+- `date`: The expiry date in YYYY-MM-DD format
+- `contract`: The type of contract (e.g., "near_month", "current_weekly")
+- `isFuturesExpiry`: Boolean indicating if futures expire on this date
+- `isOptionsExpiry`: Boolean indicating if options expire on this date
+
+#### Contract Types
+
+Each expiry date is categorized with a `contract` field that indicates the type of expiry. The possible contract types are:
+
+1. **Weekly Expiries (Thursdays/Wednesdays)**
+   - `current_weekly`: The first non-expiry Thursday of the current week
+
+2. **Monthly Expiries (last Wed/Thu of month)**
+   - `near_month`: Last Wed/Thu of this month (current month)
+   - `mid_month`: Last Wed/Thu of next month
+   - `far_month`: Last Wed/Thu of month after next
+
+3. **Weekly Ordinals Within Current Month**
+   - `first_weekly`: 1st non-expiry Thursday of current month
+   - `second_weekly`: 2nd non-expiry Thursday
+   - `third_weekly`: 3rd non-expiry Thursday
+   - `fourth_weekly`: 4th non-expiry Thursday
+   - `fifth_weekly`: 5th non-expiry Thursday (rare)
+
+4. **Weekly Ordinals in Mid-Month Slot (next month's week-trade dates)**
+   - `first_weekly_mid_month`: 1st Thursday of next month
+   - `second_weekly_mid_month`: 2nd Thursday of next month
+   - `third_weekly_mid_month`: 3rd Thursday of next month
+   - `fourth_weekly_mid_month`: 4th Thursday of next month
+   - `fifth_weekly_mid_month`: 5th Thursday of next month (rare)
+
+5. **Weekly Ordinals in Far-Month Slot (month-after-next)**
+   - `first_weekly_far_month`: 1st Thursday of month after next
+   - `second_weekly_far_month`: 2nd Thursday of month after next
+   - `third_weekly_far_month`: 3rd Thursday of month after next
+   - `fourth_weekly_far_month`: 4th Thursday of month after next
+   - `fifth_weekly_far_month`: 5th Thursday of month after next (rare)
+
+6. **Quarterly Expiries (last-Thu of Mar/Jun/Sep/Dec)**
+   - `first_quarter`: Last Thu of March (Q1)
+   - `second_quarter`: Last Thu of June (Q2)
+   - `third_quarter`: Last Thu of September (Q3)
+   - `fourth_quarter`: Last Thu of December (Q4)
+
+7. **Half-Yearly Expiries**
+   - `first_half_yearly`: Last Thu of June (H1)
+   - `second_half_yearly`: Last Thu of December (H2)
+
+8. **Year-Plus-N Quarterly/Half-Yearly (N = years ahead)**
+   - For quarterly options in future years:
+     - `first_quarter_1`: Q1 (March) of next year
+     - `second_quarter_1`: Q2 (June) of next year
+     - `third_quarter_1`: Q3 (September) of next year
+     - `fourth_quarter_1`: Q4 (December) of next year
+   - For half-yearly options in future years:
+     - `first_half_yearly_1`: H1 (June) of next year
+     - `second_half_yearly_1`: H2 (December) of next year
+   - This pattern continues with `_2`, `_3`, and `_4` suffixes for up to 4 years ahead
+
+9. **Special Case**
+   - `none`: No matching expiry category
+
+### Get Options Chain
+
+The Options Chain API provides detailed information about available option contracts for a specified instrument, including strike prices, premiums, and option Greeks.
+
+#### Constants
+
+The SDK provides constants for option types, moneyness, and expiry preferences to make your code more readable and type-safe:
+
+**Option Types:**
+```python
+client.OPTION_TYPE_CE  # Call option
+client.OPTION_TYPE_PE  # Put option
+```
+
+**Moneyness Types:**
+```python
+client.MONEYNESS_ATM  # At-the-money
+client.MONEYNESS_ITM  # In-the-money
+client.MONEYNESS_OTM  # Out-of-the-money
+```
+
+**Expiry Preferences:**
+```python
+# Common expiry preferences
+client.EXPIRY_CURRENT_WEEKLY  # Current week's expiry
+client.EXPIRY_NEAR_MONTH      # Current month's expiry
+client.EXPIRY_MID_MONTH       # Next month's expiry
+client.EXPIRY_FAR_MONTH       # Month after next expiry
+
+# Many more constants available for weekly, monthly, 
+# quarterly, and yearly expiries
+```
+
+#### Get Option Chain
+
+Fetch the option chain for a specific instrument using either an exact expiry date or a expiry preference:
+
+```python
+# Get ATM call options for SBIN with specific expiry date
+options = client.get_option_chain(
+    identifier="NSE:SBIN:3045",
+    expiry_date="2025-05-30",
+    option_type=[client.OPTION_TYPE_CE],  # Call options
+    moneyness=[client.MONEYNESS_ATM]      # At-the-money
+)
+print(f"Found {len(options['strikes'])} strikes")
+print(f"Current underlying price: {options['underlyingPrice']}")
+
+# Get both call and put options with expiry preference
+all_options = client.get_option_chain(
+    identifier="NSE:NIFTY 50:26000",
+    expiry_preference=client.EXPIRY_CURRENT_WEEKLY,  # Current week's expiry
+    option_type=[client.OPTION_TYPE_CE, client.OPTION_TYPE_PE],  # Both calls and puts
+    moneyness=[client.MONEYNESS_ATM, client.MONEYNESS_ITM, client.MONEYNESS_OTM]  # All moneyness types
+)
+
+# Print option chain details
+print(f"Resolved expiry: {all_options['resolvedExpiry']}")
+print(f"Underlying price: {all_options['underlyingPrice']}")
+print(f"Future price: {all_options['futurePrice']}")
+
+# Process options data
+for strike in all_options['strikes']:
+    print(f"{strike['tradingSymbol']} ({strike['moneyness']}): {strike['ltp']}")
+```
+
+#### Response Structure
+
+The `get_option_chain` method returns a dictionary with the following structure:
+
+```python
+{
+    # The actual expiry date that was resolved (may differ slightly from requested date)
+    "resolvedExpiry": "2025-05-29", 
+    
+    # Current price of the underlying stock/index
+    "underlyingPrice": 792.1,
+    
+    # Price of the corresponding futures contract (if applicable)
+    "futurePrice": 793.35,
+    
+    # Array of available strike prices matching the query criteria
+    "strikes": [
+        {
+            # The strike price of the option
+            "strikePrice": 790,
+            
+            # Option type: "CE" (Call) or "PE" (Put)
+            "optionType": "CE",
+            
+            # Exchange token for the option contract
+            "exchangeToken": 136169,
+            
+            # Exchange where the option is traded
+            "exchange": "NSE",
+            
+            # Trading symbol for the option contract
+            "tradingSymbol": "SBIN25MAY790CE",
+            
+            # Moneyness classification: "ATM", "ITM", or "OTM"
+            "moneyness": "ATM",
+            
+            # Expiry date of the option contract
+            "expiry": "2025-05-29",
+            
+            # Last traded price of the option
+            "ltp": 15.1,
+            
+            # Option Greeks and metrics (if available)
+            "metrics": {
+                # Option premium
+                "premium": 0,
+                
+                # Open interest
+                "oi": 0,
+                
+                # Implied volatility
+                "iv": 0,
+                
+                # Delta - rate of change of option price with respect to underlying
+                "delta": 0,
+                
+                # Gamma - rate of change of delta with respect to underlying
+                "gamma": 0,
+                
+                # Theta - rate of change of option price with respect to time
+                "theta": 0,
+                
+                # Vega - rate of change of option price with respect to volatility
+                "vega": 0,
+                
+                # Rho - rate of change of option price with respect to interest rate
+                "rho": 0
+            }
+        },
+        # Additional strikes...
+    ]
+}
+```
+
+#### Advanced Examples
+
+##### Finding a Straddle/Strangle
+
+```python
+def find_straddle_strangle(identifier, expiry):
+    """Find and analyze straddle/strangle opportunities."""
+    # Get the option chain
+    option_chain = client.get_option_chain(
+        identifier=identifier,
+        expiry_date=expiry,
+        option_type=[client.OPTION_TYPE_CE, client.OPTION_TYPE_PE],
+        moneyness=[client.MONEYNESS_ATM]
+    )
+    
+    # Find ATM call and put
+    calls = [s for s in option_chain["strikes"] if s["optionType"] == "CE"]
+    puts = [s for s in option_chain["strikes"] if s["optionType"] == "PE"]
+    
+    if not calls or not puts:
+        print("Couldn't find both call and put options")
+        return
+    
+    # For a straddle, we want the same strike price
+    atm_strike = calls[0]["strikePrice"]
+    atm_call = calls[0]
+    atm_put = next((p for p in puts if p["strikePrice"] == atm_strike), None)
+    
+    if atm_call and atm_put:
+        call_premium = atm_call["ltp"]
+        put_premium = atm_put["ltp"]
+        total_premium = call_premium + put_premium
+        
+        print(f"ATM Straddle Analysis for {identifier} (Expiry: {expiry})")
+        print(f"Underlying Price: {option_chain['underlyingPrice']}")
+        print(f"ATM Strike: {atm_strike}")
+        print(f"Call Premium: {call_premium}")
+        print(f"Put Premium: {put_premium}")
+        print(f"Total Premium: {total_premium}")
+        print(f"Breakeven Upper: {atm_strike + total_premium}")
+        print(f"Breakeven Lower: {atm_strike - total_premium}")
+        
+        # Calculate the percentage move needed for breakeven
+        pct_move = (total_premium / option_chain['underlyingPrice']) * 100
+        print(f"Required % Move for Breakeven: {pct_move:.2f}%")
+    
+    # For a strangle, we want OTM call and put
+    otm_options = client.get_option_chain(
+        identifier=identifier,
+        expiry_date=expiry,
+        option_type=[client.OPTION_TYPE_CE, client.OPTION_TYPE_PE],
+        moneyness=[client.MONEYNESS_OTM]
+    )
+    
+    otm_calls = sorted([s for s in otm_options["strikes"] if s["optionType"] == "CE"], 
+                       key=lambda x: x["strikePrice"])
+    otm_puts = sorted([s for s in otm_options["strikes"] if s["optionType"] == "PE"], 
+                      key=lambda x: x["strikePrice"], reverse=True)
+    
+    if otm_calls and otm_puts:
+        otm_call = otm_calls[0]  # First OTM call
+        otm_put = otm_puts[0]    # First OTM put
+        
+        call_premium = otm_call["ltp"]
+        put_premium = otm_put["ltp"]
+        total_premium = call_premium + put_premium
+        
+        print(f"\nOTM Strangle Analysis for {identifier} (Expiry: {expiry})")
+        print(f"Call Strike: {otm_call['strikePrice']} (Premium: {call_premium})")
+        print(f"Put Strike: {otm_put['strikePrice']} (Premium: {put_premium})")
+        print(f"Total Premium: {total_premium}")
+        print(f"Breakeven Upper: {otm_call['strikePrice'] + total_premium}")
+        print(f"Breakeven Lower: {otm_put['strikePrice'] - total_premium}")
+    
+    return option_chain
+
+# Example usage
+find_straddle_strangle("NSE:SBIN:3045", "2025-05-30")
+```
+
+##### Option Chain Visualization
+
+```python
+def visualize_option_chain(identifier, expiry):
+    """Create a visualization of the option chain."""
+    import matplotlib.pyplot as plt
+    import numpy as np
+    
+    # Get the option chain
+    option_chain = client.get_option_chain(
+        identifier=identifier,
+        expiry_date=expiry,
+        option_type=[client.OPTION_TYPE_CE, client.OPTION_TYPE_PE],
+        moneyness=[client.MONEYNESS_ATM, client.MONEYNESS_ITM, client.MONEYNESS_OTM]
+    )
+    
+    # Extract data
+    underlying_price = option_chain["underlyingPrice"]
+    
+    # Separate calls and puts
+    calls = sorted([s for s in option_chain["strikes"] if s["optionType"] == "CE"], 
+                  key=lambda x: x["strikePrice"])
+    puts = sorted([s for s in option_chain["strikes"] if s["optionType"] == "PE"], 
+                 key=lambda x: x["strikePrice"])
+    
+    # Extract strike prices and premiums
+    call_strikes = [c["strikePrice"] for c in calls]
+    call_premiums = [c["ltp"] for c in calls]
+    
+    put_strikes = [p["strikePrice"] for p in puts]
+    put_premiums = [p["ltp"] for p in puts]
+    
+    # Create figure and axis
+    fig, ax = plt.subplots(figsize=(12, 8))
+    
+    # Plot calls and puts
+    ax.plot(call_strikes, call_premiums, 'b-', marker='o', label='Calls')
+    ax.plot(put_strikes, put_premiums, 'r-', marker='o', label='Puts')
+    
+    # Add vertical line for current price
+    ax.axvline(x=underlying_price, color='g', linestyle='--', 
+               label=f'Current Price ({underlying_price})')
+    
+    # Add labels and title
+    ax.set_xlabel('Strike Price')
+    ax.set_ylabel('Premium')
+    ax.set_title(f'Option Chain for {identifier} (Expiry: {expiry})')
+    ax.legend()
+    ax.grid(True)
+    
+    plt.tight_layout()
+    plt.show()
+    
+    return option_chain
+
+# Example usage
+visualize_option_chain("NSE:NIFTY 50:26000", "2025-05-30")
+```
+
 ### Wizzer Client Examples
 
 #### Market Data and Analysis Example