NEPSE Client

A comprehensive, production-ready Python client library for interacting with the Nepal Stock Exchange (NEPSE) API. Built with modern Python best practices, full type hints, and both synchronous and asynchronous support.

🌟 Features

• ✨ Dual API Support - Both synchronous and asynchronous clients for flexible integration
• 🔒 Smart Token Management - Automatic authentication with token refresh and caching
• 📊 Complete API Coverage - Access all NEPSE endpoints: market data, company info, floor sheets, news, and more
• 🛡️ Robust Error Handling - Comprehensive exception hierarchy with automatic retries
• 📝 Full Type Hints - Complete type annotations for excellent IDE support and type safety
• 🔄 Automatic Retry Logic - Built-in exponential backoff for network failures
• 📈 Progress Tracking - Optional progress bars for long-running operations
• 🧪 Well Tested - Comprehensive test suite with >80% coverage
• 🚀 Production Ready - Battle-tested, secure, and optimized for performance
• 📚 Excellent Documentation - Detailed docs, examples, and API reference

📦 Installation

From PyPI (Recommended)

pip install nepse-client

Using uv (Fast)

uv pip install nepse-client

From Source

git clone https://github.com/4mritgiri/NepseClient.git
cd nepse-client
pip install -e .

Development Installation

# Clone and install with dev dependencies
git clone https://github.com/4mritgiri/NepseClient.git
cd nepse-client
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

🚀 Quick Start

Synchronous Usage

from nepse_client import NepseClient

# Initialize client
client = NepseClient()

# Optional: Disable TLS verification (for testing only)
client.setTLSVerification(False)

# Get market status
market_status = client.getMarketStatus()
print(f"Market is: {market_status['isOpen']}")

# Get company details
nabil = client.getCompanyDetails('NABIL')
print(f"NABIL LTP: {nabil['lastTradedPrice']}")

# Get today's top gainers
gainers = client.getTopGainers()
for stock in gainers[:5]:
    print(f"{stock['symbol']}: +{stock['percentageChange']}%")

Asynchronous Usage

import asyncio
from nepse_client import AsyncNepseClient

async def main():
    # Initialize async client
    async with AsyncNepseClient() as client:
        # Optional: Disable TLS verification (for testing only)
        client.setTLSVerification(False)

        # Concurrent requests for better performance
        market_status, summary, gainers = await asyncio.gather(
            client.getMarketStatus(),
            client.getSummary(),
            client.getTopGainers()
        )

        print(f"Market: {market_status['isOpen']}")
        print(f"Turnover: {summary['totalTurnover']}")
        print(f"Top Gainer: {gainers[0]['symbol']}")

# Run async function
asyncio.run(main())

Context Manager Support

# Automatic resource cleanup with context manager
with NepseClient() as client:
    status = client.getMarketStatus()
    companies = client.getCompanyList()
# Client automatically closed

📖 API Documentation

Market Information

# Get market status (open/closed)
status = client.getMarketStatus()

# Get market summary (turnover, trades, etc.)
summary = client.getSummary()

# Get NEPSE index
index = client.getNepseIndex()

# Get sub-indices (sector indices)
sub_indices = client.getNepseSubIndices()

# Get live market data
live_market = client.getLiveMarket()

# Get price volume data
price_volume = client.getPriceVolume()

# Get supply and demand data
supply_demand = client.getSupplyDemand()

Company Information

# Get list of all companies
companies = client.getCompanyList()

# Get security list (non-delisted securities)
securities = client.getSecurityList()

# Get company details by symbol
details = client.getCompanyDetails('NABIL')

# Get company price history
from datetime import date, timedelta
end_date = date.today()
start_date = end_date - timedelta(days=365)

history = client.getCompanyPriceVolumeHistory(
    symbol='NABIL',
    start_date=start_date,
    end_date=end_date
)

# Get daily price graph data
graph = client.getDailyScripPriceGraph('NABIL')

# Get company financial details
financials = client.getCompanyFinancialDetails(company_id='123')

# Get company AGM information
agm = client.getCompanyAGM(company_id='123')

# Get company dividend information
dividend = client.getCompanyDividend(company_id='123')

# Get company market depth
market_depth = client.getCompanyMarketDepth(company_id='123')

Trading Data

# Get complete floor sheet (all trades)
floor_sheet = client.getFloorSheet()

# Get floor sheet with progress bar
floor_sheet = client.getFloorSheet(show_progress=True)

# Get floor sheet for specific company
company_trades = client.getFloorSheetOf(
    symbol='NABIL',
    business_date='2024-01-15'
)

# Get trading average
trading_avg = client.getTradingAverage(
    business_date='2024-01-15',
    nDays=180
)

# Get market depth for symbol
depth = client.getSymbolMarketDepth('NABIL')

Top Performers

# Get top gainers
gainers = client.getTopGainers()

# Get top losers
losers = client.getTopLosers()

# Get top 10 by trade volume
top_trade = client.getTopTenTradeScrips()

# Get top 10 by transaction count
top_transaction = client.getTopTenTransactionScrips()

# Get top 10 by turnover
top_turnover = client.getTopTenTurnoverScrips()

News and Announcements

# Get company news with pagination
news = client.getCompanyNewsList(
    page=1,
    page_size=100,
    is_strip_tags=True  # Remove HTML tags
)

# Get news and alerts
alerts = client.getNewsAndAlertList(
    page=1,
    page_size=100,
    is_strip_tags=True
)

# Get press releases
press_releases = client.getPressRelease()

# Get NEPSE notices
notices = client.getNepseNotice(page=0)

Other Data

# Get holiday list for specific year
holidays = client.getHolidayList(year=2025)

# Get debenture and bond list
debentures = client.getDebentureAndBondList(type='debenture')
bonds = client.getDebentureAndBondList(type='bond')

# Get price volume history for specific date
price_history = client.getPriceVolumeHistory(business_date='2024-01-15')

Advanced Features

Caching and ID Mappings

# Get company ID to symbol mapping (cached)
company_map = client.getCompanyIDKeyMap()

# Get security ID to symbol mapping (cached)
security_map = client.getSecurityIDKeyMap()

# Force update cache
company_map = client.getCompanyIDKeyMap(force_update=True)

# Get sector-wise scrips
sector_scrips = client.getSectorScrips()
# Returns: {'Commercial Banks': ['NABIL', 'SCB', ...], ...}

Custom Configuration

import logging

# Custom logger
logger = logging.getLogger('my_nepse_app')
logger.setLevel(logging.DEBUG)

# Initialize with custom settings
client = NepseClient(
    logger=logger,
    mask_request_data=True,  # Mask sensitive data in logs
    timeout=120.0            # Request timeout in seconds
)

# Disable TLS verification (not recommended for production)
client.setTLSVerification(False)

# Re-enable TLS verification
client.setTLSVerification(True)

🔥 Advanced Usage Examples

Portfolio Value Calculator

def calculate_portfolio_value(portfolio):
    """
    Calculate total portfolio value.

    Args:
        portfolio: Dict of {symbol: quantity}

    Returns:
        Total value in NPR
    """
    client = NepseClient()
    total = 0

    for symbol, quantity in portfolio.items():
        details = client.getCompanyDetails(symbol)
        price = float(details['lastTradedPrice'])
        value = price * quantity
        total += value
        print(f"{symbol}: {quantity} @ NPR {price} = NPR {value:,.2f}")

    return total

# Example
portfolio = {'NABIL': 100, 'NICA': 50, 'SCB': 75}
total_value = calculate_portfolio_value(portfolio)
print(f"\nTotal Portfolio Value: NPR {total_value:,.2f}")

Async Batch Operations

import asyncio
from nepse_client import AsyncNepseClient

async def fetch_multiple_companies(symbols):
    """Fetch details for multiple companies concurrently."""
    async with AsyncNepseClient() as client:
        # Create tasks for all symbols
        tasks = [client.getCompanyDetails(symbol) for symbol in symbols]

        # Fetch all concurrently
        results = await asyncio.gather(*tasks, return_exceptions=True)

        # Process results
        for symbol, result in zip(symbols, results):
            if isinstance(result, Exception):
                print(f"{symbol}: Error - {result}")
            else:
                ltp = result['lastTradedPrice']
                print(f"{symbol}: NPR {ltp}")

# Run
symbols = ['NABIL', 'NICA', 'SCB', 'EBL', 'ADBL']
asyncio.run(fetch_multiple_companies(symbols))

Real-time Market Monitoring

import asyncio
from nepse_client import AsyncNepseClient

async def monitor_market(interval=60):
    """Monitor market status continuously."""
    async with AsyncNepseClient() as client:
        while True:
            try:
                status = await client.getMarketStatus()
                summary = await client.getSummary()

                print(f"[{status['asOf']}] Market: {status['isOpen']}")
                print(f"Turnover: NPR {summary['totalTurnover']:,.2f}")

                await asyncio.sleep(interval)
            except KeyboardInterrupt:
                break
            except Exception as e:
                print(f"Error: {e}")
                await asyncio.sleep(interval)

asyncio.run(monitor_market())

🐛 Error Handling

The library provides a comprehensive exception hierarchy:

from nepse_client import (
    NepseError,                  # Base exception
    NepseClientError,            # 400 errors
    NepseAuthenticationError,    # 401 errors
    NepseBadGatewayError,        # 502 errors
    NepseServerError,            # 5xx errors
    NepseNetworkError,           # Network/connection errors
    NepseValidationError,        # Input validation errors
    NepseRateLimitError,         # Rate limit exceeded
    NepseDataNotFoundError,      # Data not found
    NepseTimeoutError,           # Request timeout
)

# Example error handling
try:
    data = client.getCompanyDetails('INVALID')
except NepseAuthenticationError:
    print("Authentication failed - token will auto-refresh")
except NepseDataNotFoundError:
    print("Company symbol not found")
except NepseRateLimitError as e:
    print(f"Rate limited - retry after {e.retry_after}s")
except NepseServerError as e:
    print(f"Server error: {e}")
except NepseError as e:
    print(f"NEPSE error: {e}")

🧪 Testing

# Install test dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage
pytest --cov=nepse_client --cov-report=html

# Run specific test file
pytest tests/test_sync_client.py -v

# Run only unit tests
pytest -m unit

# Run only integration tests
pytest -m integration

📊 Code Quality

This project maintains high code quality standards:

# Format code
black nepse_client tests examples
isort nepse_client tests examples

# Lint code
flake8 nepse_client tests --max-line-length=100

# Type check
mypy nepse_client --ignore-missing-imports

# Security check
bandit -r nepse_client

# Run all pre-commit hooks
pre-commit run --all-files

🏗️ Project Structure

nepse-client/
├── nepse_client/            # Main package
│   ├── __init__.py          # Package exports
│   ├── client.py            # Base client
│   ├── sync_client.py       # Sync implementation
│   ├── async_client.py      # Async implementation
│   ├── token_manager.py     # Token management
│   ├── dummy_id_manager.py  # Dummy ID management
│   ├── exceptions.py        # Custom exceptions
│   ├── py.typed             # Type hint marker
│   └── data/                # Configuration files
├── tests/                   # Test suite
├── examples/                # Usage examples
├── docs/                    # Documentation
├── .github/                 # GitHub Actions
│   ├── workflows/           # CI/CD pipelines
│   └── ISSUE_TEMPLATE/      # Issue templates
├── pyproject.toml           # Project config
└── README.md                # This file

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Getting Started

1. Fork the repository
2. Clone your fork: git clone https://github.com/yourusername/nepse-client.git
3. Create a branch: git checkout -b feature/amazing-feature
4. Install dev dependencies: pip install -e ".[dev]"
5. Install pre-commit: pre-commit install

Making Changes

1. Make your changes
2. Add tests for new functionality
3. Run tests: pytest
4. Run code quality checks: pre-commit run --all-files
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Create a Pull Request

Code Standards

• Follow PEP 8 style guide
• Use Black for formatting (line length: 100)
• Add type hints to all functions
• Write docstrings (Google style)
• Maintain test coverage above 80%
• Update documentation for new features

Pull Request Checklist

• Tests pass locally
• Code formatted with Black and isort
• Type hints added
• Documentation updated
• CHANGELOG.md updated
• No linting errors
• Test coverage maintained

See CONTRIBUTING.md for detailed guidelines.

📝 Development

Setup Development Environment

# Clone repository
git clone https://github.com/4mritgiri/NepseClient.git
cd nepse-client

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Verify installation
pytest --version
black --version

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=nepse_client --cov-report=term-missing

# Run specific test
pytest tests/test_sync_client.py::test_get_market_status

# Run in watch mode (requires pytest-watch)
ptw

Building Documentation

# Install documentation dependencies
pip install sphinx sphinx-rtd-theme

# Build HTML docs
cd docs
make html

# Open in browser
open _build/html/index.html  # macOS
xdg-open _build/html/index.html  # Linux

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Nepal Stock Exchange for providing the API
• All contributors who have helped improve this library
• The Python community for excellent tools and libraries

👨‍💻 Author

Amrit Giri

• GitHub: @4mritgiri
• Email: amritgiri.dev@gmail.com

🔗 Links

• 📦 PyPI Package
• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📋 Changelog
• 🤝 Contributing Guide

📈 Project Stats

💖 Support

If you find this library helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs and issues
• 💡 Suggesting new features
• 🤝 Contributing code improvements
• 📢 Sharing with others

🗺️ Roadmap

• WebSocket support for real-time data
• Data export utilities (CSV, Excel, JSON)
• Advanced filtering and sorting
• Rate limiting with automatic backoff
• Caching layer for repeated requests
• CLI tool for quick queries
• Django/Flask integration examples
• Interactive Jupyter notebook examples

❓ FAQ

Q: Is this library official?
A: No, this is an unofficial client library for the NEPSE API.

Q: Do I need an API key?
A: No, the NEPSE API doesn't require authentication keys. The client handles token management automatically.

Q: Can I use this in production?
A: Yes! The library is production-ready with comprehensive error handling, retries, and logging.

Q: Which Python versions are supported?
A: Python 3.8 and above are supported.

Q: How do I report a bug?
A: Please open an issue on GitHub Issues with details and a minimal reproduction example.

Q: Can I contribute?
A: Absolutely! Contributions are welcome. Please read CONTRIBUTING.md first.

Made with ❤️ for the Nepali Tech Community

If this project helps you, please consider giving it a ⭐!