{"id":30865030,"url":"https://github.com/pmall/spread-scanner","last_synced_at":"2025-10-11T17:46:27.281Z","repository":{"id":312767005,"uuid":"1048585178","full_name":"pmall/spread-scanner","owner":"pmall","description":"CLI tool for analyzing options spreads, calculating probabilities, and providing market data snapshots.","archived":false,"fork":false,"pushed_at":"2025-09-04T15:58:55.000Z","size":79,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-04T17:44:17.527Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pmall.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T17:20:51.000Z","updated_at":"2025-09-04T15:58:59.000Z","dependencies_parsed_at":"2025-09-04T17:44:19.101Z","dependency_job_id":null,"html_url":"https://github.com/pmall/spread-scanner","commit_stats":null,"previous_names":["pmall/risk-ratio","pmall/spread-scanner"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pmall/spread-scanner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmall%2Fspread-scanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmall%2Fspread-scanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmall%2Fspread-scanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmall%2Fspread-scanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pmall","download_url":"https://codeload.github.com/pmall/spread-scanner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmall%2Fspread-scanner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279008136,"owners_count":26084397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-07T20:20:26.320Z","updated_at":"2025-10-11T17:46:27.253Z","avatar_url":"https://github.com/pmall.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spread Scanner\n\nThis is a CLI tool designed to help analyze options spreads, calculate probabilities, and provide snapshots of market data.\n\n## 🎯 Core Concept\n\nThis tool leverages the collective wisdom embedded in implied volatility to provide more accurate, probabilistic assessments of price movements and position risks. It uses a polynomial regression model to fit a smooth curve to the market's implied volatility smile, ensuring a robust and continuous probability distribution.\n\n## 🔑 Key Concepts\n\n### Position\n\nIn this tool, a `Position` is a generalized representation of an options trade, encompassing both multi-leg spreads and single-leg options. It is defined by:\n\n- `type`: Call or Put.\n- `side`: Debit (long) or Credit (short).\n- `longStrike`: The strike price of the long option leg.\n- `shortStrike`: The strike price of the short option leg.\n- `netPremium`: The net premium paid or received for the position.\n- `isSpread`: A boolean indicating whether the position is a true multi-leg spread or a single option (where one leg is virtual).\n\nThis abstraction allows the core analysis engine to process various option strategies uniformly.\n\n## ✨ Features\n\nThis CLI tool provides the following commands:\n\n- `list-expirations`: Lists available expiration dates for a given instrument.\n- `snapshot`: Fetches and displays the raw options chain data for a specific instrument and expiration.\n- `probabilities`: Computes and displays the probabilistic price distribution for an underlying asset at a given expiration.\n- `analyze-option`: Analyzes a single option position (long or short), providing detailed risk/reward and probabilistic metrics.\n- `analyze-spread`: Analyzes a single, user-defined vertical spread, providing detailed risk/reward and probabilistic metrics.\n\n## 🔬 Methodology\n\nTo ensure a smooth and consistent probability curve and accurate probabilistic calculations, the tool implements the following process:\n\n1.  **Fetch Data**: It retrieves the full option chain (strikes, and implied volatilities) for a given asset and expiration.\n2.  **Fit Volatility Smile**: It performs a 2nd-degree polynomial regression on the implied volatilities as a function of their log-moneyness (`log(strike/current_price)`). This fits a smooth curve to the raw market data, accounting for the volatility smile/skew.\n3.  **Generate Dense Probability Grid**: Using the fitted volatility model, it generates a dense grid of price points (not just strike prices) and calculates their cumulative probabilities. This provides a more accurate representation of the continuous probability distribution.\n4.  **Calculate Probabilities**: It uses this smoothed volatility model to calculate the cumulative probability (`P(price \u003c= K)`) for any given price, resulting in a robust and continuous probability distribution.\n\nThis method allows for the accurate pricing of any price, not just those actively traded, and forms a solid basis for calculating expected returns and losses for any options position.\n\n## 🚀 Installation\n\n1.  **Clone the repository:**\n    ```bash\n    git clone \u003crepository-url\u003e\n    cd spread-scanner\n    ```\n2.  **Install dependencies:**\n    ```bash\n    npm install\n    ```\n3.  **Configure environment variables:**\n    Create a `.env` file in the project root based on `.env.example` (if applicable):\n    ```\n    # .env.example\n    DERIBIT_API_URL=https://www.deribit.com/api/v2\n    ```\n    Copy this content to a new file named `.env`.\n\n## ⚙️ Configuration\n\nApplication-wide configuration values are defined in `src/config.ts`. This file centralizes settings for API endpoints and filtering options.\n\n```typescript\nexport const config = {\n  deribit: {\n    apiUrl: process.env.DERIBIT_API_URL || \"https://www.deribit.com/api/v2\",\n  },\n};\n```\n\nYou can modify these values directly in `src/config.ts` to adjust the behavior of the CLI tool.\n\n## 💡 Usage Examples\n\nAll commands are run using `npm run cli -- \u003ccommand\u003e [arguments] [options]`.\n\n### 1. `list-expirations`\n\nLists available expiration dates for a given instrument.\n\n```bash\nnpm run cli -- list-expirations deribit SOL-USDC\n```\n\nExample Output:\n\n```\nAvailable expirations for SOL-USDC from deribit:\n2025-09-03\n2025-09-04\n2025-09-05\n...\n```\n\n### 2. `snapshot`\n\nFetches and displays the raw options chain data for a specific instrument and expiration.\n\n```bash\nnpm run cli -- snapshot deribit SOL-USDC 2025-09-03\n```\n\nExample Output (truncated):\n\n```\nOption chain for SOL-USDC on 2025-09-03 from deribit:\n{\n  strike: 176,\n  type: 'call',\n  impliedVolatility: 117.19,\n  volume: 0,\n  openInterest: 0,\n  bidPrice: 0,\n  askPrice: 0,\n  lastPrice: 0,\n  expiration: '2025-09-03T08:00:00.000Z',\n  instrument_name: 'SOL_USDC-3SEP25-176-C'\n}\n...\n```\n\n### 3. `probabilities`\n\nComputes and displays the probabilistic price distribution for an underlying asset at a given expiration, specifically for the available strike prices.\n\n```bash\nnpm run cli -- probabilities deribit SOL-USDC 2025-09-03\n```\n\nExample Output (truncated):\n\n```\nAnalyzing SOL-USDC options for expiration: 2025-09-03 from deribit:\nCurrent Price: 175.20\nTotal Options: 104\nFiltered Options: 104\n\nPrice Probability Distribution:\nStrike   P(\u003c=K)    1-P(\u003c=K)\n140.00   0.1898    0.8102\n150.00   0.2933    0.7067\n160.00   0.4015    0.5985\n170.00   0.5089    0.4911\n180.00   0.6123    0.3877\n190.00   0.7088    0.2912\n200.00   0.7939    0.2061\n...\n```\n\n### 4. `analyze-option`\n\nAnalyzes a single option position (long or short), providing detailed risk/reward and probabilistic metrics. This command reuses the underlying spread analysis engine by treating a single option as a \"virtual\" spread with one real leg and one theoretical, far out-of-the-money leg.\n\n- **Usage:**\n\n  ```bash\n  npm run cli -- analyze-option \u003csource\u003e \u003cinstrument\u003e \u003cexpiration\u003e --type \u003ccall|put\u003e --strike \u003ck\u003e --side \u003cdebit|credit\u003e [--virtual-strike-offset \u003cpercentage\u003e]\n  ```\n\n  - `\u003csource\u003e`: Data source (e.g., `deribit`).\n  - `\u003cinstrument\u003e`: Instrument to analyze (e.g., `SOL-USDC`).\n  - `\u003cexpiration\u003e`: Expiration date (YYYY-MM-DD).\n  - `--type \u003ccall|put\u003e`: **(Required)** Type of the option (call or put).\n  - `--strike \u003ck\u003e`: **(Required)** The strike price of the single option.\n  - `--side \u003cdebit|credit\u003e`: **(Required)** Whether the option position is a debit (long) or credit (short) strategy.\n  - `--virtual-strike-offset \u003cpercentage\u003e`: **(Optional)** Percentage offset from the current price to determine the virtual strike for the \"other\" leg. Defaults to `90` (i.e., 90% away from the current price).\n\n- **Virtual Leg Concept:**\n  To leverage the existing spread analysis engine, a single option is modeled as a spread where one leg is the actual option you specify, and the other is a \"virtual\" leg. This virtual leg is placed far out-of-the-money (OTM) so its impact on the overall payoff is negligible for realistic price movements.\n  - For a **long option (debit)**, the virtual leg is a short option placed far OTM to cap theoretical profit (e.g., a long call is paired with a short call far above the current price).\n  - For a **short option (credit)**, the virtual leg is a long option placed far OTM to cap theoretical loss (e.g., a short call is paired with a long call far above the current price).\n\n- **Output Metrics:**\n  The command provides a comprehensive analysis including:\n  - **Net Premium:** The raw premium paid (debit) or received (credit) for the position.\n  - **Max Profit / Max Loss:** The maximum possible profit and loss for the trade, accounting for the premium.\n  - **Expected Payoff at Expiration / Expected Loss at Expiration:** The probability-weighted intrinsic value of the position at expiration, _before_ accounting for the premium.\n  - **Expected PnL:** The overall expected profit or loss of the trade, accounting for the premium. This is the most direct measure of the trade's expected financial outcome.\n  - **Risk/Reward Ratio:** The ratio of expected payoff/loss to premium/risk.\n  - **Probability of Profit:** The chance that the position will expire profitably.\n  - **Break-Even Price:** The underlying price at which the trade neither makes nor loses money.\n\n### 5. `analyze-spread`\n\nAnalyzes a single, user-defined vertical spread, providing detailed risk/reward and probabilistic metrics.\n\n- **Usage:**\n\n  ```bash\n  npm run cli -- analyze-spread \u003csource\u003e \u003cinstrument\u003e \u003cexpiration\u003e --type \u003ccall|put\u003e --strikes \u003ck1,k2\u003e --side \u003cdebit|credit\u003e\n  ```\n\n  - `\u003csource\u003e`: Data source (e.g., `deribit`).\n  - `\u003cinstrument\u003e`: Instrument to analyze (e.g., `SOL-USDC`).\n  - `\u003cexpiration\u003e`: Expiration date (YYYY-MM-DD).\n  - `--type \u003ccall|put\u003e`: **(Required)** Type of the spread's options.\n  - `--strikes \u003ck1,k2\u003e`: **(Required)** The two strike prices, comma-separated (e.g., `100,110`).\n  - `--side \u003cdebit|credit\u003e`: **(Required)** Whether the spread is a debit or credit strategy.\n\n- **Output Metrics:**\n  The command provides a comprehensive analysis including:\n  - **Net Premium:** The raw premium paid (debit) or received (credit) for the position.\n  - **Max Profit / Max Loss:** The maximum possible profit and loss for the trade, accounting for the premium.\n  - **Expected Payoff at Expiration / Expected Loss at Expiration:** The probability-weighted intrinsic value of the position at expiration, _before_ accounting for the premium.\n  - **Expected PnL:** The overall expected profit or loss of the trade, accounting for the premium. This is the most direct measure of the trade's expected financial outcome.\n  - **Risk/Reward Ratio:** The ratio of expected payoff/loss to premium/risk.\n  - **Probability of Profit:** The chance that the position will expire profitably.\n  - **Break-Even Price:** The underlying price at which the trade neither makes nor loses money.\n\n## 💻 Technology Stack\n\n- **Language**: TypeScript (strict type checking)\n- **Runtime**: Node.js (for CLI)\n- **Package Manager**: npm\n\n## 🔮 Future Extensions\n\nThis project is designed with extensibility in mind. Future phases include:\n\n- **Scan Spreads Command**: Implement a command to scan all possible vertical spreads for a given instrument and expiration, filter them, and rank them to find the most promising opportunities.\n- **Web Interface Integration**: Develop a Next.js-based web interface with interactive charts and dashboards.\n- **Additional Data Sources**: Integrate with other exchanges like Binance, Interactive Brokers, etc.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmall%2Fspread-scanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpmall%2Fspread-scanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmall%2Fspread-scanner/lists"}