{"id":34532584,"url":"https://github.com/pkjmesra/pkbrokers","last_synced_at":"2026-03-02T19:01:22.921Z","repository":{"id":311108930,"uuid":"1032117204","full_name":"pkjmesra/PKBrokers","owner":"pkjmesra","description":"A simple python library to connect to various brokers using standard user credentials, fetch the instruments (trading symbols), indices and their ticks during as well as off market hours.","archived":false,"fork":false,"pushed_at":"2026-02-26T16:41:47.000Z","size":94126,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-26T17:37:59.182Z","etag":null,"topics":["algo-trading","brokers","kite","zerodha"],"latest_commit_sha":null,"homepage":"","language":"Python","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/pkjmesra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"github":"pkjmesra","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":"pkjmes","custom":null}},"created_at":"2025-08-04T20:44:12.000Z","updated_at":"2026-02-26T16:45:42.000Z","dependencies_parsed_at":"2025-12-01T05:04:22.727Z","dependency_job_id":null,"html_url":"https://github.com/pkjmesra/PKBrokers","commit_stats":null,"previous_names":["pkjmesra/pkbrokers"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/pkjmesra/PKBrokers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkjmesra%2FPKBrokers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkjmesra%2FPKBrokers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkjmesra%2FPKBrokers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkjmesra%2FPKBrokers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pkjmesra","download_url":"https://codeload.github.com/pkjmesra/PKBrokers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkjmesra%2FPKBrokers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30016506,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T17:00:27.440Z","status":"ssl_error","status_checked_at":"2026-03-02T17:00:03.402Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["algo-trading","brokers","kite","zerodha"],"created_at":"2025-12-24T05:51:51.655Z","updated_at":"2026-03-02T19:01:22.911Z","avatar_url":"https://github.com/pkjmesra.png","language":"Python","funding_links":["https://github.com/sponsors/pkjmesra","https://otechie.com/pkjmes"],"categories":[],"sub_categories":[],"readme":"\n# PKBrokers\n\n[![MADE-IN-INDIA][MADE-IN-INDIA-badge]][MADE-IN-INDIA] [![GitHub release (latest by date)][GitHub release (latest by date)-badge]][GitHub release (latest by date)] [![Downloads][Downloads-badge]][Downloads] ![latest download][Latest-Downloads-badge] [![Docker Pulls][Docker Pulls-badge]][Docker Status]\n\n| Platforms | [![Windows][Windows-badge]][Windows] | [![Linux(x64)][Linux-badge_x64]][Linux_x64] [![Linux(arm64)][Linux-badge_arm64]][Linux_arm64] | [![Mac OS(x64)][Mac OS-badge_x64]][Mac OS_x64] [![Mac OS(arm64)][Mac OS-badge_arm64]][Mac OS_arm64] | [![Docker Status][Docker Status-badge]][Docker Status] |\n| :-------------: | :-----------------: | :-----------------: | :-----------------: | :-----------------: |\n| Package / Docs | [![Documentation][Documentation-badge]][Documentation] [![OpenSSF Best Practices][OpenSSF-Badge]][OpenSSF-pkbrokers] | [![PyPI][pypi-badge]][pypi] | [![is wheel][wheel-badge]][pypi] | ![github license][github-license] |\n| Tests/Code-Quality | [![CodeFactor][Codefactor-badge]][Codefactor] | [![Coverage Status][Coverage-Status-badge]][Coverage-Status] | [![codecov][codecov-badge]][codecov] | [![After Market][After Market-badge]][After Market] |\n\n---\n\n## Table of Contents\n\n- [What is PKBrokers?](#what-is-pkbrokers)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Architecture Overview](#architecture-overview)\n- [Core Modules](#core-modules)\n  - [In-Memory Candle Store](#1-in-memory-candle-store)\n  - [Data Manager](#2-data-manager)\n  - [Kite Instruments](#3-kite-instruments)\n  - [Tick Watcher](#4-tick-watcher)\n  - [Local Candle Database](#5-local-candle-database)\n  - [Telegram Bots](#6-telegram-bots)\n  - [Authentication](#7-authentication)\n  - [GitHub Actions Workflows](#8-github-actions-workflows)\n  - [PKL Generator Script](#9-pkl-generator-script)\n- [API Reference](#api-reference)\n- [Environment Variables](#environment-variables)\n- [Contributing](#contributing)\n- [Related Projects](#related-projects)\n\n---\n\n## What is PKBrokers?\n\n**PKBrokers** is a high-performance Python library for connecting to stock brokers (primarily Zerodha's Kite Connect) to fetch real-time market data, instruments, and ticks. Key features include:\n\n- 🚀 **High-Performance Candle Store** - O(1) access to OHLCV candles across 10 timeframes\n- 📊 **Real-Time Tick Processing** - WebSocket-based tick aggregation\n- 💾 **Multi-Source Data Management** - SQLite, Turso, pickle files, and Kite API\n- 🤖 **Telegram Bot Integration** - Distribute tick data via Telegram\n- 🔐 **Automated Authentication** - TOTP-based Kite login\n- 📦 **24/7 Data Availability** - GitHub-based data persistence\n\nThis library is part of the [PKScreener](https://github.com/pkjmesra/PKScreener) ecosystem.\n\n---\n\n## Installation\n\n### From PyPI\n\n```bash\npip install pkbrokers\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/pkjmesra/pkbrokers.git\ncd pkbrokers\npip install -r requirements.txt\npip install -e .\n```\n\n### Requirements\n\n- Python 3.9+\n- Zerodha Kite Connect account (for real-time data)\n- See `requirements.txt` for dependencies\n\n---\n\n## Quick Start\n\n### High-Performance Data Provider\n\n```python\nfrom pkbrokers.kite import get_candle_store, HighPerformanceDataProvider\n\n# Get singleton candle store\nstore = get_candle_store()\n\n# Or use high-level data provider\nprovider = HighPerformanceDataProvider()\n\n# Get 5-minute candles for any stock\ndf = provider.get_stock_data(\"RELIANCE\", interval=\"5m\", count=50)\n\n# Get current day's OHLCV\nohlcv = provider.get_current_ohlcv(\"TCS\")\nprint(f\"Open: {ohlcv['open']}, High: {ohlcv['high']}, Low: {ohlcv['low']}, Close: {ohlcv['close']}\")\n```\n\n### Data Manager (Multi-Source)\n\n```python\nfrom pkbrokers.kite.datamanager import InstrumentDataManager\n\n# Initialize manager\nmanager = InstrumentDataManager()\n\n# Execute data synchronization\nsuccess = manager.execute()\n\nif success:\n    # Access stock data\n    reliance = manager.pickle_data[\"RELIANCE\"]\n    df = pd.DataFrame(\n        data=reliance['data'],\n        columns=reliance['columns'],\n        index=reliance['index']\n    )\n    print(f\"Shape: {df.shape}\")\n```\n\n### Kite Authentication\n\n```python\nfrom pkbrokers.kite.examples.externals import kite_auth\n\n# Authenticate and get access token\n# Requires KUSER, KPWD, KTOTP environment variables\nkite_auth()\n\n# Token is now available as KTOKEN\nfrom PKDevTools.classes.Environment import PKEnvironment\ntoken = PKEnvironment().KTOKEN\n```\n\n---\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                            PKBrokers Architecture                           │\n├─────────────────────────────────────────────────────────────────────────────┤\n│                                                                             │\n│  ┌────────────────────────────────────────────────────────────────┐         │\n│  │                     Application Layer                          │         │\n│  │            PKScreener | Custom Applications                    │         │\n│  └─────────────────────────────┬──────────────────────────────────┘         │\n│                                │                                            │\n│  ┌─────────────────────────────▼──────────────────────────────────┐         │\n│  │                      Data Provider API                         │         │\n│  │   HighPerformanceDataProvider | InstrumentDataManager          │         │\n│  └─────────────────────────────┬──────────────────────────────────┘         │\n│                                │                                            │\n│       ┌────────────────────────┼────────────────────────┐                   │\n│       │                        │                        │                   │\n│  ┌────▼────┐           ┌───────▼───────┐        ┌───────▼───────┐           │\n│  │InMemory │           │  Local SQLite │        │ Remote Data   │           │\n│  │Candle   │           │  Database     │        │ (GitHub/Turso)│           │\n│  │Store    │           │               │        │               │           │\n│  └────┬────┘           └───────────────┘        └───────────────┘           │\n│       │                                                                     │\n│  ┌────▼──────────────────────────────────────────────────────────-┐         │\n│  │                    Tick Processing Layer                       │         │\n│  │   KiteTokenWatcher | CandleAggregator | TickProcessor          │         │\n│  └────────────────────────────┬───────────────────────────────────┘         │\n│                               │                                             │\n│  ┌────────────────────────────▼───────────────────────────────────┐         │\n│  │                     WebSocket Layer                            │         │\n│  │          ZerodhaWebSocketClient | KiteTicker                   │         │\n│  └────────────────────────────┬───────────────────────────────────┘         │\n│                               │                                             │\n│  ┌────────────────────────────▼───────────────────────────────────┐         │\n│  │                  Kite Connect API / Authentication             │         │\n│  │            Authenticator | KiteInstruments                     │         │\n│  └────────────────────────────────────────────────────────────────┘         │\n│                                                                             │\n│  ┌────────────────────────────────────────────────────────────────┐         │\n│  │                      Bot Layer (Telegram)                      │         │\n│  │         PKTickBot | Orchestrator | Consumer                    │         │\n│  └────────────────────────────────────────────────────────────────┘         │\n│                                                                             │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\nSee more details on [Architecture](https://github.com/pkjmesra/PKBrokers/blob/main/docs/ARCHITECTURE.md)\n---\n\n## Core Modules\n\n### 1. In-Memory Candle Store\n\nHigh-performance, in-memory OHLCV storage with O(1) access to all timeframes.\n\n```python\nfrom pkbrokers.kite.inMemoryCandleStore import InMemoryCandleStore, get_candle_store\n\n# Get singleton instance\nstore = get_candle_store()\n\n# Process incoming tick\nstore.process_tick({\n    'instrument_token': 256265,\n    'last_price': 21500.50,\n    'volume': 1000000,\n    'timestamp': datetime.now()\n})\n\n# Get completed candles\ncandles = store.get_candles(\n    instrument_token=256265,\n    interval='5m',\n    count=50\n)\n\n# Get current forming candle\ncurrent = store.get_current_candle(\n    instrument_token=256265,\n    interval='5m'\n)\n\n# Export to ticks.json\nstore.save_ticks_json(\"/path/to/ticks.json\")\n\n# Get statistics\nstats = store.get_stats()\nprint(f\"Instruments: {stats['instrument_count']}\")\nprint(f\"Ticks processed: {stats['ticks_processed']}\")\n```\n\n#### Supported Timeframes\n\n| Interval | Description | Max Candles Stored |\n|----------|-------------|-------------------|\n| `1m` | 1 minute | 375 (full day) |\n| `2m` | 2 minutes | 188 |\n| `3m` | 3 minutes | 125 |\n| `4m` | 4 minutes | 94 |\n| `5m` | 5 minutes | 75 |\n| `10m` | 10 minutes | 38 |\n| `15m` | 15 minutes | 25 |\n| `30m` | 30 minutes | 13 |\n| `60m` | 60 minutes | 7 |\n| `day` | Daily | 1 |\n\n#### Features\n\n- **O(1) Access**: Instant lookup via hash-based indexing\n- **No Rate Limits**: Unlike Yahoo Finance\n- **Auto-Persistence**: Saves to disk every 5 minutes\n- **Memory Efficient**: ~100MB for 2000 instruments\n- **Thread-Safe**: Lock-protected operations\n\n---\n\n### 2. Data Manager\n\nComprehensive data synchronization from multiple sources.\n\n```python\nfrom pkbrokers.kite.datamanager import InstrumentDataManager\n\nmanager = InstrumentDataManager()\n\n# Set specific stocks (optional)\nmanager.list_stock_codes = [\"RELIANCE\", \"TCS\", \"INFY\"]\n\n# Execute synchronization\n# Priority: SQLite → InMemoryCandleStore → Kite API → Pickle files\nsuccess = manager.execute()\n\n# Access data\nif success:\n    for symbol, data in manager.pickle_data.items():\n        df = pd.DataFrame(\n            data=data['data'],\n            columns=data['columns'],\n            index=data['index']\n        )\n        print(f\"{symbol}: {len(df)} rows\")\n```\n\n#### Data Source Priority\n\n1. **During Market Hours**:\n   - Local SQLite database\n   - InMemoryCandleStore (real-time ticks)\n   - Kite API (authenticated)\n   - GitHub ticks.json\n\n2. **After Market Hours**:\n   - Local pickle files\n   - Remote GitHub pickle files\n\n---\n\n### 3. Kite Instruments\n\nManage instrument data from Kite Connect API.\n\n```python\nfrom pkbrokers.kite.instruments import KiteInstruments, Instrument\n\n# Initialize with credentials\nkite = KiteInstruments(\n    api_key=\"your_api_key\",\n    access_token=\"your_access_token\"\n)\n\n# Sync instruments from Kite API\nkite.sync_instruments(force_fetch=True)\n\n# Get instrument count\ncount = kite.get_instrument_count()\nprint(f\"Total instruments: {count}\")\n\n# Get NSE stocks only\nequities = kite.get_equities(only_nse_stocks=True)\n\n# Get instrument tokens for subscription\ntokens = kite.get_instrument_tokens(equities)\n\n# Fetch instrument by token\ninstrument = kite.get_instrument(256265)  # NIFTY 50\nprint(f\"Symbol: {instrument.tradingsymbol}\")\n```\n\n#### Instrument Model\n\n```python\n@dataclass\nclass Instrument:\n    instrument_token: int      # Unique identifier\n    exchange_token: str        # Exchange-specific token\n    tradingsymbol: str         # Trading symbol (e.g., 'RELIANCE')\n    name: Optional[str]        # Full name\n    last_price: Optional[float]\n    expiry: Optional[str]      # For derivatives\n    strike: Optional[float]    # For options\n    tick_size: float\n    lot_size: int\n    instrument_type: str       # EQ, FUT, OPT, INDEX\n    segment: str               # NSE, BSE\n    exchange: str\n    last_updated: str\n    nse_stock: bool\n```\n\n---\n\n### 4. Tick Watcher\n\nWebSocket-based real-time tick processing.\n\n```python\nfrom pkbrokers.kite.kiteTokenWatcher import KiteTokenWatcher\n\n# Initialize watcher\nwatcher = KiteTokenWatcher()\n\n# Start watching (blocking)\ntry:\n    watcher.watch(test_mode=False)\nexcept KeyboardInterrupt:\n    watcher.stop()\n```\n\n#### Command-Line Usage\n\n```bash\n# Start tick watcher\npkkite --ticks\n\n# Test mode (3 minutes)\npkkite --ticks --test\n\n# Authenticate first\npkkite --auth\n\n# Fetch historical data\npkkite --history=5minute\n```\n\n---\n\n### 5. Local Candle Database\n\nSQLite-based candle storage for persistence.\n\n```python\nfrom pkbrokers.kite.localCandleDatabase import LocalCandleDatabase\n\n# Initialize database\ndb = LocalCandleDatabase()\n\n# Save daily candle\ndb.save_daily_candle(\n    symbol=\"RELIANCE\",\n    date=date.today(),\n    open_price=2500.0,\n    high_price=2550.0,\n    low_price=2480.0,\n    close_price=2530.0,\n    volume=1000000\n)\n\n# Load candles\ncandles = db.load_daily_candles(\"RELIANCE\", days=30)\n\n# Save intraday candles\ndb.save_intraday_candle(\n    symbol=\"RELIANCE\",\n    timestamp=datetime.now(),\n    interval=\"5m\",\n    open_price=2500.0,\n    high_price=2510.0,\n    low_price=2495.0,\n    close_price=2505.0,\n    volume=50000\n)\n```\n\n---\n\n### 6. Telegram Bots\n\n#### PKTickBot\n\nTelegram bot for distributing tick data.\n\n```python\nfrom pkbrokers.bot.tickbot import PKTickBot\n\nbot = PKTickBot(\n    bot_token=\"your_bot_token\",\n    ticks_file_path=\"/path/to/ticks.json\",\n    chat_id=\"-1001234567890\"\n)\n\n# Start bot (blocking)\nbot.run()\n```\n\n**Available Commands**:\n| Command | Description |\n|---------|-------------|\n| `/ticks` | Get zipped ticks.json file |\n| `/db` | Get local SQLite database |\n| `/status` | Check bot and data status |\n| `/top` | Get top 20 ticking symbols |\n| `/token` | Get current KTOKEN |\n| `/refresh_token` | Generate new KTOKEN |\n| `/restart` | Refresh token and restart watcher |\n| `/test_ticks` | Start 3-minute tick test |\n| `/help` | Show help message |\n\n#### Orchestrator\n\nMulti-process orchestrator for bot and data management.\n\n```python\nfrom pkbrokers.bot.orchestrator import Orchestrator\n\norchestrator = Orchestrator()\n\n# Check if market is open\nif orchestrator.should_run_kite_process():\n    orchestrator.start_kite_process()\n```\n\n---\n\n### 7. Authentication\n\nAutomated Kite Connect authentication using TOTP.\n\n```python\nfrom pkbrokers.kite.authenticator import KiteAuthenticator\n\nauth = KiteAuthenticator(\n    user_id=\"your_user_id\",\n    password=\"your_password\",\n    totp_secret=\"your_totp_secret\",\n    api_key=\"your_api_key\"\n)\n\n# Get access token\naccess_token = auth.authenticate()\n\n# Token is automatically saved to environment\n```\n\n**Environment Variables Required**:\n- `KUSER`: Kite user ID\n- `KPWD`: Kite password\n- `KTOTP`: TOTP secret key\n- `KAPI`: Kite API key\n\n---\n\n### 8. GitHub Actions Workflows\n\nPKBrokers includes automated GitHub Actions workflows for OHLCV data collection.\n\n#### History Data Workflow\n\nThe `w1-workflow-history-data-child.yml` workflow fetches historical data from Kite API and saves to PKScreener.\n\n**Triggering with `--history=day`**:\n```bash\n# Via pkkite CLI\npkkite --history=day --pastoffset=0 --verbose\n```\n\n**What happens**:\n1. Fetches all NSE instrument tokens (~2000 stocks)\n2. Calls Kite Historical API for each instrument (rate-limited: 3 req/sec)\n3. Saves to local SQLite database (`instrument_history.db`)\n4. Exports to pkl files (`stock_data_DDMMYYYY.pkl`)\n5. Commits to [PKScreener actions-data-download branch](https://github.com/pkjmesra/PKScreener/tree/actions-data-download/actions-data-download)\n\n**Data Flow**:\n```\nKite API → SQLite DB → PKL Export → Git Commit → PKScreener Branch\n```\n\n**PKL Files Saved to PKScreener**:\n- `actions-data-download/stock_data_DDMMYYYY.pkl` - Daily candles\n- `actions-data-download/daily_candles.pkl` - Latest daily data\n- `results/Data/` - Secondary storage location\n\n**Programmatic Trigger**:\n```python\nfrom pkbrokers.bot.dataSharingManager import DataSharingManager\n\nmanager = DataSharingManager()\nmanager.trigger_history_download_workflow(past_offset=5)  # Fetch last 5 days\n```\n\nSee [ARCHITECTURE.md](docs/ARCHITECTURE.md#github-actions-workflows) for detailed workflow documentation.\n\n---\n\n### 9. PKL Generator Script\n\nUnified script for generating pkl files from **ticks.json** OR **SQLite database** with historical data merge.\n\n```bash\n# From ticks.json (default - used by Ticks Runner)\npython pkbrokers/scripts/generate_pkl_from_ticks.py --data-dir results/Data --verbose\n\n# From SQLite database (used by History Data Child workflow)\npython pkbrokers/scripts/generate_pkl_from_ticks.py --from-db --data-dir results/Data --verbose\n```\n\n```python\n# Programmatic usage\nfrom pkbrokers.scripts.generate_pkl_from_ticks import (\n    download_historical_pkl,\n    download_ticks_json,\n    load_from_sqlite,\n    find_sqlite_database,\n    convert_ticks_to_candles,\n    merge_candles,\n    save_pkl_files\n)\n\n# From ticks.json\nhistorical = download_historical_pkl()  # ~37MB from GitHub\nticks = download_ticks_json()           # Today's ticks\ncandles = convert_ticks_to_candles(ticks)\nmerged = merge_candles(historical, candles)\nsave_pkl_files(merged, \"results/Data\")\n\n# From SQLite database\ndb_path = find_sqlite_database()\ndb_candles = load_from_sqlite(db_path)\nmerged = merge_candles(historical, db_candles)\nsave_pkl_files(merged, \"results/Data\")\n```\n\n**What it does**:\n1. Loads new data from ticks.json OR SQLite database\n2. Downloads historical pkl (~37MB) from [PKScreener actions-data-download](https://github.com/pkjmesra/PKScreener/tree/actions-data-download/actions-data-download)\n3. Converts data to candle format\n4. Merges today's data with historical (~2000 stocks × 2+ years)\n5. Saves both intraday and daily pkl files (~37MB+)\n\n**Output Files**:\n| File | Description |\n|------|-------------|\n| `stock_data_DDMMYYYY.pkl` | Daily candles merged with historical |\n| `daily_candles.pkl` | Same as above (generic name) |\n| `intraday_stock_data_DDMMYYYY.pkl` | Today's intraday data only |\n| `intraday_1m_candles.pkl` | Same as above (generic name) |\n\n---\n\n## API Reference\n\n### Main Exports\n\n```python\nfrom pkbrokers.kite import (\n    # Candle Store\n    InMemoryCandleStore,\n    get_candle_store,\n    \n    # Data Providers\n    HighPerformanceDataProvider,\n    InstrumentDataManager,\n    \n    # Instruments\n    KiteInstruments,\n    Instrument,\n    \n    # Tick Processing\n    KiteTokenWatcher,\n    CandleAggregator,\n    \n    # Database\n    LocalCandleDatabase,\n    \n    # Authentication\n    KiteAuthenticator,\n)\n\nfrom pkbrokers.bot import (\n    PKTickBot,\n    Orchestrator,\n)\n```\n\n### Module Structure\n\n```\npkbrokers/\n├── __init__.py\n├── bot/\n│   ├── __init__.py\n│   ├── consumer.py          # Data consumer\n│   ├── orchestrator.py      # Multi-process orchestrator\n│   └── tickbot.py           # Telegram tick bot\n├── kite/\n│   ├── __init__.py\n│   ├── authenticator.py     # Kite authentication\n│   ├── candleAggregator.py  # Tick → Candle aggregation\n│   ├── datamanager.py       # Multi-source data manager\n│   ├── databasewriter.py    # Database writer\n│   ├── inMemoryCandleStore.py  # In-memory candle store\n│   ├── instrumentHistory.py # Historical data\n│   ├── instruments.py       # Instrument management\n│   ├── kiteTokenWatcher.py  # WebSocket tick watcher\n│   ├── localCandleDatabase.py  # SQLite candle storage\n│   ├── tickProcessor.py     # Tick processing\n│   ├── ticks.py             # Tick utilities\n│   ├── trader.py            # Trading operations\n│   ├── zerodhaWebSocketClient.py  # WebSocket client\n│   └── examples/\n│       ├── externals.py     # External helpers\n│       └── pkkite.py        # CLI entry point\n└── scripts/\n    └── publish_candle_data.py  # Data publishing\n```\n\n---\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `KUSER` | Yes* | Kite user ID |\n| `KPWD` | Yes* | Kite password |\n| `KTOTP` | Yes* | TOTP secret for 2FA |\n| `KAPI` | Yes* | Kite API key |\n| `KTOKEN` | Auto | Access token (auto-generated) |\n| `TOKEN` | Yes** | Telegram bot token |\n| `CHAT_ID` | Yes** | Default Telegram chat ID |\n| `TURSO_DB_URL` | No | Turso database URL |\n| `TURSO_DB_AUTH_TOKEN` | No | Turso auth token |\n\n*Required for Kite Connect features  \n**Required for Telegram bot features\n\n---\n\n## Contributing\n\n### Development Setup\n\n```bash\ngit clone https://github.com/pkjmesra/pkbrokers.git\ncd pkbrokers\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\npip install -e .\n```\n\n### Running Tests\n\n```bash\npytest test/\npytest --cov=pkbrokers test/\n```\n\n### Code Style\n\n```bash\nruff check pkbrokers/\nruff format pkbrokers/\n```\n\n---\n\n## Related Projects\n\n- [PKScreener](https://github.com/pkjmesra/PKScreener) - Stock screening application\n- [PKDevTools](https://github.com/pkjmesra/PKDevTools) - Common development tools\n- [PKNSETools](https://github.com/pkjmesra/PKNSETools) - NSE market data tools\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n---\n\n[![Star History Chart](https://api.star-history.com/svg?repos=pkjmesra/pkbrokers\u0026type=Date)](https://star-history.com/#pkjmesra/pkbrokers\u0026Date)\n\n[MADE-IN-INDIA-badge]: https://img.shields.io/badge/MADE%20WITH%20%E2%9D%A4%20IN-INDIA-orange\n[MADE-IN-INDIA]: https://en.wikipedia.org/wiki/India\n[Windows-badge]: https://img.shields.io/badge/Windows-0078D6?logo=windows\u0026logoColor=white\n[Windows]: https://github.com/pkjmesra/pkbrokers/releases/download/0.1.20250914.18/pkkite.exe\n[Linux-badge_x64]: https://img.shields.io/badge/Linux(x64)-FCC624?logo=linux\u0026logoColor=black\n[Linux_x64]: https://github.com/pkjmesra/pkbrokers/releases/download/0.1.20250914.18/pkkite_x64.bin\n[Linux-badge_arm64]: https://img.shields.io/badge/Linux(arm64)-FCC624?logo=linux\u0026logoColor=black\n[Linux_arm64]: https://github.com/pkjmesra/pkbrokers/releases/download/0.1.20250914.18/pkkite_arm64.bin\n[Mac OS-badge_x64]: https://img.shields.io/badge/mac%20os(x64)-D3D3D3?logo=apple\u0026logoColor=000000\n[Mac OS_x64]: https://github.com/pkjmesra/pkbrokers/releases/download/0.1.20250914.18/pkkite_x64.run\n[Mac OS-badge_arm64]: https://img.shields.io/badge/mac%20os(arm64)-D3D3D3?logo=apple\u0026logoColor=000000\n[Mac OS_arm64]: https://github.com/pkjmesra/pkbrokers/releases/download/0.1.20250914.18/pkkite_arm64.run\n[GitHub release (latest by date)-badge]: https://img.shields.io/github/v/release/pkjmesra/pkbrokers\n[GitHub release (latest by date)]: https://github.com/pkjmesra/pkbrokers/releases/latest\n[pypi-badge]: https://img.shields.io/pypi/v/pkbrokers.svg?style=flat-square\n[pypi]: https://pypi.python.org/pypi/pkbrokers\n[wheel-badge]: https://img.shields.io/pypi/wheel/pkbrokers.svg?style=flat-square\n[github-license]: https://img.shields.io/github/license/pkjmesra/pkbrokers\n[Downloads-badge]: https://static.pepy.tech/personalized-badge/pkbrokers?period=total\u0026units=international_system\u0026left_color=black\u0026right_color=brightgreen\u0026left_text=Total%20Downloads\n[Downloads]: https://pepy.tech/project/pkbrokers\n[Latest-Downloads-badge]: https://img.shields.io/github/downloads-pre/pkjmesra/pkbrokers/latest/total?logo=github\n[Coverage-Status-badge]: https://coveralls.io/repos/github/pkjmesra/pkbrokers/badge.svg?kill_cache=1\n[Coverage-Status]: https://coveralls.io/github/pkjmesra/pkbrokers?branch=main\n[codecov-badge]: https://codecov.io/gh/pkjmesra/pkbrokers/branch/main/graph/badge.svg\n[codecov]: https://codecov.io/gh/pkjmesra/pkbrokers\n[Documentation-badge]: https://readthedocs.org/projects/pkbrokers/badge/?version=latest\n[Documentation]: https://pkbrokers.readthedocs.io/en/latest/?badge=latest\n[Docker Status-badge]: https://img.shields.io/docker/automated/pkjmesra/pkbrokers.svg\n[Docker Status]: https://hub.docker.com/repository/docker/pkjmesra/pkbrokers\n[Docker Pulls-badge]: https://img.shields.io/docker/pulls/pkjmesra/pkbrokers.svg\n[Codefactor-badge]: https://www.codefactor.io/repository/github/pkjmesra/pkbrokers/badge\n[Codefactor]: https://www.codefactor.io/repository/github/pkjmesra/pkbrokers\n[After Market-badge]: https://github.com/pkjmesra/pkbrokers/actions/workflows/w9-workflow-download-data.yml/badge.svg\n[After Market]: https://github.com/pkjmesra/pkbrokers/actions/workflows/w9-workflow-download-data.yml\n[OpenSSF-Badge]: https://www.bestpractices.dev/projects/10011/badge\n[OpenSSF-pkbrokers]: https://www.bestpractices.dev/projects/10011\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkjmesra%2Fpkbrokers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpkjmesra%2Fpkbrokers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkjmesra%2Fpkbrokers/lists"}