NEPSE API

An unofficial API service for Nepal Stock Exchange (NEPSE) that provides real-time market data through REST, WebSocket, and Model Context Protocol (MCP) endpoints.

⚠️ VERY IMPORTANT: Legal & Liability Disclaimer

This project is provided "AS IS" without any warranty of any kind, express or implied. By using this software or its hosted services, you are agreeing to accept all risks and responsibilities.

1. Strictly for Educational & Non-Commercial Use

This project and its associated services are intended strictly for educational, research, and personal, non-commercial purposes only.

• Commercial use is strictly prohibited. You may not use this software, its data, or its services to build commercial applications, for financial gain, or in any production trading system.
• For any commercial use of NEPSE data, you must obtain a license from the Nepal Stock Exchange or an authorized data provider.

2. No Guarantee of Accuracy or Reliability

The data is sourced from unofficial channels. The author does not guarantee the accuracy, completeness, timeliness, or reliability of any data provided. Do not use this for making financial decisions. Any financial loss or other damages resulting from the use of this software are solely your responsibility.

3. No Liability for Downtime or Bugs

The author is not liable for anything. This includes, but is not limited to:

• Bugs or Errors: The software may contain bugs. There is no obligation to provide patches or fixes.
• Server Downtime: The hosted services may be unavailable at any time without notice.
• Data Loss or Damages: The author is not responsible for any form of loss or damage resulting from the use of this project.

4. Hosted Service Is Unreliable and Provided "As-Is"

A free, hosted version of this API is provided as a convenience for testing and educational use.

• It runs on a free-tier Oracle Cloud server in India, which is known to terminate instances randomly and without warning.
• There is absolutely NO guarantee of uptime or availability. Do not rely on it for anything important. The author is not obligated to maintain this service or provide any support for it.

5. You Use It at Your Own Risk

This is a personal project that earns no money. By choosing to use this software, you acknowledge that you understand these risks and agree to hold the author harmless from any and all claims, damages, or losses.

Features

• Real-time market data access
• Stock Symbol & Index Validation: Comprehensive validation system with intelligent suggestions
• Model Context Protocol (MCP): AI integration for automated market analysis with over 20 tools.
• Endpoint-Level Caching: In-memory caching (10-minute TTL) for rapid responses to repeated queries.
• HTTP Caching: All REST API responses include a Cache-Control: public, max-age=30 header to reduce server load and improve client-side performance.
• Multiple data endpoints including:
  • Price and Volume information
  • Floorsheet Data
  • Market Summary
  • Live Market Data
  • Top Gainers/Losers
  • Company Details
  • Sector-wise Information
  • Index and Sub-indices
• Input Validation: All endpoints validate stock symbols and index names against actual NEPSE data
• Containerized Deployment: Docker and Docker Compose support for easy deployment
• Rate Limiting: Built-in protection against API abuse with configurable limits

⚠️ Important Legal & Ethical Notice

🎓 Educational & Research Use Only

This project is strictly intended for educational and research purposes only. Commercial use is NOT permitted without proper authorization from official NEPSE data providers.

📋 Usage Guidelines

• ✅ Allowed: Educational projects, research, learning, personal development
• ❌ NOT Allowed: Commercial applications, production trading systems, redistribution for profit
• ⚖️ Commercial Use: For commercial applications, please consult with official NEPSE data providers

🛡️ Data Source Disclaimer

This API depends on unofficial data sources and third-party libraries for accessing Nepal Stock Exchange data. The author:

• Does NOT own or control the underlying stock market data
• Does NOT guarantee data accuracy, completeness, or timeliness
• Is NOT affiliated with Nepal Stock Exchange (NEPSE) or any official data providers
• Cannot be held liable for any financial losses, legal issues, or damages arising from use of this API

📞 Contact & Issues

For any legal concerns, issues, or questions:

• Email: davidparkedme@gmail.com
• Repository Issues: Please open an issue on GitHub for technical problems
• Legal Concerns: Contact the author immediately for any legal or compliance issues

🌐 Hosted Service (Free Access)

A free hosted version is available with rate limiting as a generous effort to support researchers and students:

Service	URL	Status
REST API	https://nepseapi.surajrimal.dev
WebSocket	wss://nepseapiws.surajrimal.dev/
MCP Server	https://nepseapimcp.surajrimal.dev/mcp/

⚠️ Critical Service Disclaimers:

• No Reliability Guarantee: This is provided as a convenience for educational purposes only
• No Uptime Guarantee: The author holds NO responsibility if servers go offline
• Not a Reliable Source: Do NOT treat this as a reliable or production-ready service
• No Support Obligation: Do NOT contact the author asking why servers are down
• Fair Usage Policy: Please do not exploit the hosted service

🚨 Important: This free service may be discontinued at any time without notice. Use at your own risk.

📄 License

This project is released under the MIT License to encourage open-source collaboration while maintaining proper attribution.

Architecture

The project consists of three main components:

1. REST API Server (server.py)

   • Built with FastAPI
   • Provides HTTP endpoints for market data
   • Runs on port 8000
   • Supports CORS
   • Uses uvicorn as the ASGI server

2. WebSocket Server (socketServer.py)

   • Provides real-time data streaming
   • Supports bidirectional communication

3. MCP Server (mcp_server.py) - NEW

   • Model Context Protocol server for AI integration
   • Provides structured access to all stock data endpoints
   • Compatible with Claude Desktop and other MCP clients
   • Enables AI models to query Nepal stock market data

Installation

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

Usage

Quick Start - All Servers

Cross-platform (Recommended):

python start_servers.py

Windows (Double-click):

# Double-click start_servers.bat
# OR run in PowerShell:
.\start_servers.bat

Alternative methods:

# Manual startup script for Windows
python start_servers.py

# Or start individual components
python server.py          # FastAPI server
python socketServer.py    # WebSocket server
python mcp_server.py      # MCP server

Starting Individual Servers

# Start REST API server
python server.py

# Start WebSocket server
python socketServer.py

# Start MCP server (for AI integration)
python mcp_server.py

WebSocket Server Usage

The WebSocket server provides a persistent, real-time connection for receiving NEPSE data. It's ideal for applications that need live updates without constant polling.

Connecting to the Server: Connect your WebSocket client to ws://localhost:5555 (or wss://nepseapiws.surajrimal.dev/ for the hosted version).

Communication Protocol: Communication is done via JSON messages.

• Client Request: Send a JSON object with a route and optional params.
• Server Response: The server will respond with the requested data or an error message in JSON format.

Example 1: Get Market Summary

1. Send this message to the server:

   {
     "route": "Summary",
     "params": {}
   }

2. Receive a response like this:

   {
     "Total Turnover Rs:": 4489236458.2,
     "Total Traded Shares": 12540423,
     "Total Transactions": 85879,
     "Total Scrips Traded": 242
   }

Example 2: Get Company Details for NABIL Bank

1. Send this message:

   {
     "route": "CompanyDetails",
     "params": {
       "symbol": "NABIL"
     }
   }

2. Receive a response with the company's details.

Handling Errors: If you send an invalid route or parameters, the server will respond with an error message:

{
  "error": "Route not found"
}

Available Routes: The WebSocket server supports numerous routes, including:

• Summary
• NepseIndex
• LiveMarket
• TopGainers
• TopLosers
• CompanyDetails (requires symbol in params)
• FloorsheetOf (requires symbol in params)
• And many more, mirroring the REST API endpoints.

MCP Server Integration

The MCP server enables AI models (like Claude) to directly access Nepal stock market data using the Model Context Protocol (MCP) via FastMCP.

Here are some examples of the MCP server in action:

Stock Analysis

Market Depth

NEPSE Index

Sub-indices

How to Run the MCP Server

Local (for Claude Desktop, stdio):

In your mcp_server.py, ensure you start the server with stdio transport for local integration:

if __name__ == "__main__":
    mcp.run(transport="stdio")

Remote (HTTP, for hosted or networked use):

To run the MCP server as a remote HTTP service (e.g., for network/hosted access):

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=PORT)

Claude Desktop Integration

1. Install uv globally (required for Claude Desktop to find it):

   • On macOS and Linux:

     curl -LsSf https://astral.sh/uv/install.sh | sh

   • On Windows:

     powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Configure Claude Desktop

   Add the following to your claude_desktop_config.json (adjust the path to your mcp_server.py):

   {
     "mcpServers": {
       "nepseapi-mcp-server": {
         "command": "uv",
         "args": [
           "run",
           "--with", "fastmcp",
           "--with", "requests",
           "--with", "pydantic",
           "python",
           "C:/Users/Admin/Desktop/Work/NepseAPI/mcp_server.py"
         ]
       }
     }
   }

   • If you are running the MCP server remotely (HTTP), you can point Claude Desktop to the hosted MCP server instead of running it locally.

3. Restart Claude Desktop

4. The AI can now use tools like:

   • get_market_summary - Get current market overview
   • And 20+ more tools for comprehensive market analysis

Test MCP Server:

python test_mcp.py

🌐 Using Hosted Service (Free Access)

Instead of setting up locally, you can use the free hosted service with rate limits:

REST API:

# Use hosted REST API
curl "https://nepseapi.surajrimal.dev/health"
curl "https://nepseapi.surajrimal.dev/Summary"
curl "https://nepseapi.surajrimal.dev/validate/stock/NABIL"

WebSocket Connection:

// Connect to hosted WebSocket
const ws = new WebSocket('wss://nepseapiws.surajrimal.dev/');
ws.onmessage = (event) => console.log(JSON.parse(event.data));

MCP Server for Claude Desktop:

{
  "mcpServers": {
    "nepseapi-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "--with", "requests",
        "--with", "pydantic",
        "path\\to\\mcp_server.py"
      ]
    }
  }
}

⚠️ Rate Limits Apply: The hosted service has reasonable rate limits to ensure fair usage. Please do not abuse the free service.

🛑 Hosted Service Reliability Notice:

• This service is provided as a generous gesture for educational convenience
• No guarantee of availability, uptime, or continued operation
• No support provided for service outages or issues
• May be discontinued without notice at any time
• Use local deployment for any critical or production needs

Docker Deployment

Build and Run Locally

# Build the image
docker build -t nepseapi .

# Run the container
docker run -p 8000:8000 -p 5555:5555 -p 8080:8080 nepseapi

Using Docker Hub Image

# Pull and run from Docker Hub
docker run -p 8000:8000 -p 5555:5555 -p 8080:8080 -p 9000:9000 surajrimal/nepseapi:latest

Docker Compose (Recommended)

Use the provided docker-compose.yml for easy orchestration:

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

The Docker Compose setup includes:

• REST API: Port 8000
• WebSocket Server: Port 5555
• MCP Server: Port 8080
• Health Checks: Automatic service monitoring
• Restart Policies: Automatic recovery

Container Features

• Multi-service Architecture: All three servers running in one container
• Health Monitoring: Built-in health checks for all services
• Port Mapping: Separate ports for each service
• Environment Configuration: Configurable via environment variables
• Production Ready: Optimized for production deployment

Environment Requirements

API Endpoints

Base URL: http://localhost:8000

Market Data Endpoints

Endpoint	Description	Validation
/Summary	Get market summary	✅
/PriceVolume	Get price and volume data	✅
/LiveMarket	Get live market data	✅
/TopGainers	Get top gaining stocks	✅
/TopLosers	Get top losing stocks	✅
/CompanyList	Get list of all companies	✅
/NepseIndex	Get NEPSE index data	✅
/Floorsheet	Get floorsheet data	✅
/SupplyDemand	Get market supply/demand data	✅

Validation Endpoints

Endpoint	Description	Parameters
/validate/stock/{symbol}	Validate stock symbol	symbol (path)
/validate/index/{index_name}	Validate index name	index_name (path)
/validate/suggestions/stock/{symbol}	Get stock suggestions	symbol (path)
/validate/suggestions/index/{index_name}	Get index suggestions	index_name (path)
/validate/stats	Get validation statistics	None

Utility Endpoints

Endpoint	Description
/	Welcome message and API info
/health	API health check
/docs	FastAPI auto-generated documentation

Note: All endpoints with stock symbols or index names include automatic validation with helpful error messages and suggestions. Rate limiting is applied to prevent abuse.

And many more endpoints available at the root URL (/).

Rate Limiting

The API includes built-in rate limiting to prevent abuse and ensure fair usage across all services.

Rate Limit Configuration

Service/Category	Requests per Minute	Description
Health Checks	200	/health endpoint
Validation	120	/validate/* endpoints
Market Data	60	Core market endpoints
WebSocket	100	WebSocket connections & messages
MCP	6	MCP tool queries
Default	60	All other endpoints

Rate Limit Headers

HTTP responses include rate limiting information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1703123456
X-RateLimit-Category: market_data

Rate Limit Responses

When rate limits are exceeded:

HTTP API (429 status):

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Try again in 30 seconds.",
  "limit": 60,
  "reset_time": 1703123456
}

WebSocket:

{
  "error": "Rate limit exceeded for messages",
  "limit": 100,
  "remaining": 0,
  "reset_time": 1703123456
}

MCP:

Rate limit exceeded for MCP tool 'get_market_summary'.
Limit: 80 requests per minute. Try again in 25 seconds.

Rate Limit Monitoring

# Check rate limit statistics
curl http://localhost:8000/rate-limit/stats

# Example response
{
  "total_tracked_ips": 5,
  "active_requests_in_window": 23,
  "window_size_seconds": 60,
  "limits": {
    "default": 60,
    "validation": 120,
    "market_data": 60,
    "websocket": 100,
    "mcp": 80,
    "health": 200
  }
}

Stock Symbol & Index Validation

The API includes comprehensive validation for all stock symbols and index names to ensure data accuracy and provide helpful feedback.

Validation Features

• Real-time Validation: All endpoints validate input against actual NEPSE data
• Smart Suggestions: Get suggested corrections for invalid symbols
• Comprehensive Coverage: Validates both stock symbols and index names
• Error Prevention: Prevents API calls with invalid data

Validation Endpoints

Endpoint	Description	Parameters
/validate/stock/{symbol}	Validate stock symbol	symbol (path parameter)
/validate/index/{index_name}	Validate index name	index_name (path parameter)
/validate/suggestions/stock/{symbol}	Get stock symbol suggestions	symbol (path parameter)
/validate/suggestions/index/{index_name}	Get index name suggestions	index_name (path parameter)
/validate/stats	Get validation statistics	None

Example Usage

# Validate a stock symbol
curl "http://localhost:8000/validate/stock/NABIL"

# Get suggestions for invalid symbol
curl "http://localhost:8000/validate/suggestions/stock/NABIL123"

# Validate an index name
curl "http://localhost:8000/validate/index/Banking"

Response Format

Valid Symbol:

{
  "symbol": "NABIL",
  "is_valid": true,
  "suggestions": []
}

Invalid Symbol with Suggestions:

{
  "symbol": "NABIL123",
  "is_valid": false,
  "suggestions": ["NABIL", "NABBC", "NICA"]
}

For detailed information about the validation system, see VALIDATION_SUMMARY.md.

MCP Tools Available

The MCP server provides the following tools for AI integration, with endpoint-level caching (10-minute TTL) for faster repeat queries:

Tool Name	Description	Parameters
get_market_summary	Get current market summary	None
get_price_volume	Get price and volume data	None
get_live_market_data	Get live market data	None
get_top_gainers	Get top gaining stocks	None
get_top_losers	Get top losing stocks	None
get_company_list	Get a list of all companies	None
get_nepse_index	Get NEPSE index data	None
get_floorsheet	Get floorsheet data	symbol: str (optional)
get_supply_demand	Get market supply/demand data	None
validate_stock_symbol	Validate a stock symbol	symbol: str
validate_index_name	Validate an index name	index_name: str
get_stock_suggestions	Get suggestions for a stock symbol	symbol: str
get_index_suggestions	Get suggestions for an index name	index_name: str
get_validation_stats	Get validation statistics	None
get_company_details	Get details for a specific company	symbol: str
get_sector_data	Get data for a specific sector	sector: str
get_sub_indices	Get data for all sub-indices	None
get_top_stocks_by_turnover	Get top stocks by turnover	None
get_top_stocks_by_volume	Get top stocks by volume	None
get_top_stocks_by_transactions	Get top stocks by transactions	None

For more details on how to use these tools, please refer to MCP_USAGE.md.

Docker Deployment

Environment Requirements

• Python 3.11+
• Dependencies:
  • FastAPI
  • uvicorn
  • websockets
  • httpx
  • mcp (Model Context Protocol)
  • pydantic (for validation)

License Compliance: All dependencies are used under their respective open-source licenses (MIT, Apache 2.0, etc.)

Testing

# Test local REST API endpoints
curl http://localhost:8000/health

# Test local validation endpoints
curl http://localhost:8000/validate/stock/NABIL

# Test hosted service
curl https://nepseapi.surajrimal.dev/health

# Test MCP server functionality (local)
python test_mcp.py

# Run with verbose output
python test_mcp.py --verbose

# Test stock map update functionality
python test_update.py

# Test rate limiting functionality
python test_rate_limiting.py

Stock Map Maintenance

The project includes an automated system to keep the stock symbol database current as NEPSE adds new stocks.

Automatic Updates

• GitHub Actions: Runs daily at midnight UTC to update stockmap.json
• Workflow: .github/workflows/update-stock-map.yml
• Script: updateStocksMap.py

Manual Updates

# Start the API server first
python server.py

# In another terminal, run the update script
python updateStocksMap.py

# With verbose logging
python updateStocksMap.py --verbose

Update Process

1. Fetches latest data from /SecurityList and /SectorScrips endpoints
2. Processes active securities and maps them to sectors
3. Updates stockmap.json with new stock information
4. Commits changes automatically via GitHub Actions

The update script ensures data consistency and provides detailed logging for troubleshooting.

License

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

Third-Party Dependencies

This project uses an unofficial API client for NEPSE and various open-source libraries. All dependencies must be used in accordance with their respective licenses and terms of service.

Data Usage Rights

• No data ownership claimed: This project does not claim ownership of Nepal Stock Exchange data
• Educational use: Licensed for educational and research purposes
• Commercial restrictions: Commercial use requires proper authorization from official data providers
• Compliance responsibility: Users are responsible for ensuring compliance with all applicable laws and regulations

🔧 Future Maintenance & Support Policy

No Maintenance Guarantee: The author provides this project "as-is" with NO obligation for future maintenance, updates, or bug fixes.

Bug Reports & Issues:

• ❌ Do NOT contact the author asking why the repository stopped working
• ❌ Do NOT contact the author demanding fixes or support
• ✅ DO submit GitHub issues for documentation purposes only
• ✅ DO submit Pull Requests with fixes if you identify solutions
• ✅ DO fork the repository and maintain your own version if needed

Author's Commitment:

• Best Effort Only: Fixes will be provided only if the author has time and interest
• No Timeline Guarantees: No promises on when (or if) issues will be addressed
• Community-Driven: The project may evolve through community contributions
• No Liability: The author holds NO liability to fix issues, maintain compatibility, or provide ongoing support

Recommended Approach:

• Fork and Fix: If you need guaranteed functionality, fork the repository
• Community Support: Engage with other users for help and solutions
• Self-Reliance: Be prepared to maintain your own version for critical use cases

Deployment Options

The project supports multiple deployment configurations:

Container Deployment (Recommended)

• Docker: Single container with all services
• Docker Compose: Orchestrated multi-service deployment
• Production Ready: Health checks and restart policies

CI/CD

• Automated builds via GitHub Actions
• Multi-platform Docker image support
• Automated testing and deployment pipeline

⚠️ Legal Disclaimer & Liability

No Warranty

This software is provided "AS IS" without warranty of any kind. The author makes no representations or warranties regarding:

• Data accuracy or completeness
• Service availability or reliability
• Fitness for any particular purpose
• Compliance with local regulations

Limitation of Liability

The author shall NOT be liable for:

• Any financial losses resulting from use of this API
• Any legal issues arising from data usage
• Any damages, direct or indirect, arising from software use
• Any claims from third parties regarding data rights
• Service downtime or unavailability of hosted services
• Repository maintenance or future functionality
• Breaking changes or compatibility issues

User Responsibility

By using this software, you acknowledge and agree that:

• You are solely responsible for compliance with all applicable laws
• You will not use this software for unauthorized commercial purposes
• You understand this is an unofficial, educational project
• You will seek proper authorization for any commercial use
• You accept full responsibility for any issues arising from software use
• You will NOT demand support or guaranteed functionality from the author
• You understand this project may become unmaintained at any time

Official Data Sources

For official, licensed, and commercial-grade market data, please contact:

• Nepal Stock Exchange (NEPSE): Official data provider
• Licensed data vendors: Authorized commercial data distributors
• Financial institutions: Banks and brokerages with official data access

Contact for Legal Issues

For any legal concerns, compliance questions, or takedown requests:

• Email: davidparkedme@gmail.com
• Response Time: Legal inquiries will be addressed within 48 hours

This project is not affiliated with, endorsed by, or connected to the Nepal Stock Exchange (NEPSE) or any official financial institutions.

Acknowledgements

This project depends upon and is heavily inspired by NepseUnofficialApi. Thanks to the author basic-bgnr for open sourcing the project.