fiale-plus · bearmug · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -42,6 +42,13 @@ Creates the MCP server, registers tools and resources, handles tool calls via st
 **CLI** — `src/cli.ts`
 Standalone CLI using Node's built-in `util.parseArgs`. Reuses the same tool classes. Output formats: JSON (default), CSV, table. No `cache.startCleanup()` (CLI is short-lived).
 
+Experimental CLI commands require `TV_EXPERIMENTAL_ENABLED=1`:
+```bash
+TV_EXPERIMENTAL_ENABLED=1 tradingview-cli experimental bars BINANCE:BTCUSDT --timeframe 60
+TV_EXPERIMENTAL_ENABLED=1 tradingview-cli experimental stream-quotes NASDAQ:AAPL --duration 10
+TV_EXPERIMENTAL_ENABLED=1 tradingview-cli experimental stream-bars BINANCE:BTCUSDT --timeframe 1 --duration 30
+```
+
 **CLI Helpers** (`src/cli/`)
 - `parseArgs.ts` - Option configs, input builders, preset merging
 - `formatters.ts` - JSON/CSV/table output formatters
@@ -56,11 +63,23 @@ Standalone CLI using Node's built-in `util.parseArgs`. Reuses the same tool clas
 - `ta.ts` - Technical analysis summary and ranking via scanner Recommend.All/Other/MA fields
 - `types.ts` - TypeScript interfaces for API requests/responses
 
+**WebSocket Layer** (`src/ws/`) — EXPERIMENTAL
+- `types.ts` - Bar, Quote, Timeframe, and configuration types
+- `errors.ts` - TvWsError, ConnectionError, AuthError, SymbolError, TimeoutError
+- `protocol.ts` - Packet encode/decode, session ID generation, message creation helpers
+- `auth.ts` - Auth token handling and experimental feature gating
+- `client.ts` - TvWsClient WebSocket connection with session dispatch
+- `session.ts` - ChartSession and QuoteSession for bar data and quote streaming
+- `parser.ts` - Bar and quote data parsing from raw WebSocket messages
+- `index.ts` - Barrel export for the ws module
+
 **Tools** (`src/tools/`)
 - `screen.ts` - Stock/forex/crypto/ETF screening and symbol lookup. Contains `OPERATOR_MAP` for filter operators and `DEFAULT_COLUMNS`/`EXTENDED_COLUMNS` for response fields
 - `search.ts` - Symbol search tool wrapper (MCP + CLI)
 - `metainfo.ts` - Market metainfo tool wrapper
 - `ta.ts` - Technical analysis summary (`get_ta_summary`) and ranking (`rank_by_ta`) tool wrappers
+- `bars.ts` - Experimental `experimental_get_bars` tool (WebSocket, gated by TV_EXPERIMENTAL_ENABLED)
+- `stream.ts` - Experimental `experimental_stream_quotes` and `experimental_stream_bars` tools (WebSocket, gated)
 - `fields.ts` - Field metadata and listing (~100 fields across fundamental/technical/performance categories, for stock/etf/crypto/forex asset types)
 
 **Resources** (`src/resources/`)
@@ -82,6 +101,9 @@ Standalone CLI using Node's built-in `util.parseArgs`. Reuses the same tool clas
 9. `get_market_metainfo` - Get metadata about a market screener and available fields
 10. `get_ta_summary` - TradingView-style technical analysis summary with buy/sell/neutral labels
 11. `rank_by_ta` - Rank symbols by weighted TA scores across timeframes
+12. `experimental_get_bars` - [EXPERIMENTAL] Fetch historical OHLCV bars via WebSocket (requires `TV_EXPERIMENTAL_ENABLED=1`)
+13. `experimental_stream_quotes` - [EXPERIMENTAL] Stream real-time quotes (bounded duration) via WebSocket (requires `TV_EXPERIMENTAL_ENABLED=1`)
+14. `experimental_stream_bars` - [EXPERIMENTAL] Stream bar updates (bounded duration) via WebSocket (requires `TV_EXPERIMENTAL_ENABLED=1`)
 
 ### Filter Operators
 `OPERATOR_MAP` in `src/tools/screen.ts` maps 18 MCP operators to TradingView API operations:
@@ -104,6 +126,13 @@ Environment variables (set in `.mcp.json`):
 - `CACHE_TTL_SECONDS` - Cache duration (default: 300)
 - `RATE_LIMIT_RPM` - Requests per minute (default: 10)
 
+Experimental (WebSocket features):
+- `TV_EXPERIMENTAL_ENABLED` - Enable experimental tools (default: false, set to `1` or `true` to enable)
+- `TV_SESSION_ID` - TradingView session ID for authenticated access
+- `TV_SESSION_SIGN` - TradingView session signature
+- `TV_WS_TIMEOUT_MS` - WebSocket timeout in milliseconds (default: 10000)
+- `TV_WS_ENDPOINT` - WebSocket server: `data`, `prodata`, or `widgetdata` (default: `data`)
+
 ## Testing
 
 Tests use Node's built-in test runner with tsx. Test files are in `src/tests/` with `.test.ts` suffix.

diff --git a/README.md b/README.md
@@ -27,6 +27,7 @@
 - [CLI Usage](#cli-usage)
 - [Configuration](#configuration)
 - [MCP Tools](#mcp-tools)
+- [Experimental Lab Features](#experimental-lab-features)
 - [Screening Fields](#screening-fields)
 - [Pre-built Strategies](#pre-built-strategies)
 - [Investor Commands](#investor-commands)
@@ -45,6 +46,7 @@
 - **Symbol discovery** — search for TradingView symbols by name, ticker, or description via `search_symbols`
 - **Technical analysis** — TradingView-style buy/sell/neutral summaries and multi-timeframe TA ranking via `get_ta_summary` and `rank_by_ta`
 - **Market metadata** — discover available screener fields per market via `get_market_metainfo`
+- **Experimental WebSocket lab tools** — opt-in historical bars and bounded streams via `experimental_get_bars`, `experimental_stream_quotes`, and `experimental_stream_bars`
 - **9 investor workflow commands** — from `/due-diligence` to `/macro-dashboard` — built on top of the MCP tools
 - **Multi-asset coverage** — stocks, ETFs, forex, and crypto with asset-specific field discovery via `list_fields`
 - **Smart caching and rate limiting** — configurable TTL and requests-per-minute to keep usage responsible
@@ -106,6 +108,11 @@ tradingview-cli ta NASDAQ:AAPL NASDAQ:NVDA
 
 # Rank symbols by TA score
 tradingview-cli rank-ta NASDAQ:AAPL NASDAQ:MSFT NASDAQ:NVDA --timeframes 60,1D --weights '{"1D":3}'
+
+# Experimental WebSocket tools (requires TV_EXPERIMENTAL_ENABLED=1)
+tradingview-cli experimental bars BINANCE:BTCUSDT --timeframe 60
+tradingview-cli experimental stream-quotes NASDAQ:AAPL --duration 10
+tradingview-cli experimental stream-bars BINANCE:BTCUSDT --timeframe 1 --duration 30
 ```
 
 ### Output Formats
@@ -134,6 +141,9 @@ tradingview-cli screen stocks --preset value_stocks -f table
 | `metainfo <market> [opts]` | Get metadata about a market screener |
 | `ta <symbols...> [opts]` | Get technical analysis summary for symbols |
 | `rank-ta <symbols...> [opts]` | Rank symbols by weighted TA scores |
+| `experimental bars <symbol> [opts]` | Fetch historical OHLCV bars via TradingView WebSocket |
+| `experimental stream-quotes <symbol...> [opts]` | Stream bounded real-time quotes |
+| `experimental stream-bars <symbol> [opts]` | Stream bounded bar updates |
 | `fields [opts]` | List available screening fields |
 | `preset <name>` | Get a preset strategy's details |
 | `presets` | List all available presets |
@@ -199,12 +209,17 @@ Enable in `.claude/settings.local.json`:
 |---|---|---|
 | `CACHE_TTL_SECONDS` | `300` | How long to cache API responses (seconds) |
 | `RATE_LIMIT_RPM` | `10` | Maximum API requests per minute |
+| `TV_EXPERIMENTAL_ENABLED` | `false` | Enable experimental WebSocket tools (`1`/`true` to enable) |
+| `TV_WS_ENDPOINT` | `data` | WebSocket server: `data`, `prodata`, or `widgetdata` |
+| `TV_WS_TIMEOUT_MS` | `10000` | WebSocket connection timeout in milliseconds |
+| `TV_SESSION_ID` | — | TradingView session ID for authenticated access |
+| `TV_SESSION_SIGN` | — | TradingView session signature for authenticated access |
 
 ---
 
 ## MCP Tools
 
-Twelve tools are exposed to Claude:
+Fifteen tools are exposed to Claude:
 
 | Tool | Description | Key Parameters |
 |---|---|---|
@@ -220,6 +235,9 @@ Twelve tools are exposed to Claude:
 | `rank_by_ta` | Rank symbols by weighted TA scores across timeframes | `symbols`, `timeframes`, `weights` |
 | `get_preset` | Retrieve a pre-configured screening strategy by key | `preset_name` |
 | `list_presets` | List all available preset strategies with descriptions | — |
+| `experimental_get_bars` | Fetch historical OHLCV bars via WebSocket (experimental) | `symbol`, `timeframe`, `limit`, `extended_session` |
+| `experimental_stream_quotes` | Collect bounded quote updates via WebSocket (experimental) | `symbols`, `fields`, `duration_seconds` |
+| `experimental_stream_bars` | Collect bounded bar updates via WebSocket (experimental) | `symbol`, `timeframe`, `duration_seconds`, `mode` |
 
 ### Filter Structure
 
@@ -293,6 +311,33 @@ Returns ranked list with per-timeframe breakdown and weighted average score.
 
 ---
 
+## Experimental Lab Features
+
+These tools are opt-in and require `TV_EXPERIMENTAL_ENABLED=1`.
+
+### `experimental_get_bars`
+Fetch historical OHLCV bars via TradingView WebSocket.
+
+```json
+{ "symbol": "BINANCE:BTCUSDT", "timeframe": "60", "limit": 300, "extended_session": false }
+```
+
+### `experimental_stream_quotes`
+Collect bounded quote updates for one or more symbols.
+
+```json
+{ "symbols": ["NASDAQ:AAPL"], "fields": ["lp", "bid", "ask"], "duration_seconds": 10 }
+```
+
+### `experimental_stream_bars`
+Collect bounded bar updates in rolling or close-only mode.
+
+```json
+{ "symbol": "BINANCE:BTCUSDT", "timeframe": "1", "duration_seconds": 30, "mode": "rolling" }
+```
+
+---
+
 ## Screening Fields
 
 Use `list_fields` to browse fields. Pass `asset_type` to get tailored lists for each asset class.
@@ -431,6 +476,12 @@ Run a single test file:
 npm test -- fields.test.ts
 ```
 
+Run experimental lab integration tests:
+
+```bash
+npm run test:integration:lab
+```
+
 After making changes, restart Claude to reload the MCP server (no hot-reload).
 
 ### Adding a New Field