Upstox TOTP Python SDK

A modern, lightweight Python package that simplifies Upstox API authentication by handling TOTP-based login and token generation automatically. With this library, you can securely generate and refresh access tokens required to connect to the Upstox trading platform without manual intervention.

🚀 Features

• 🔐 Automated TOTP Authentication – Generate secure time-based one-time passwords (TOTP) for Upstox login
• ⚡ Token Management – Fetch, refresh, and store Upstox access tokens with ease
• 🛠️ Simple API – Minimal, developer-friendly methods for quick integration
• 📈 Trading Ready – Instantly plug into Upstox APIs for real-time market data, order placement, and portfolio management
• 🐍 Pythonic Design – Built with modern async/session handling for robust performance
• 🎯 CLI Tool – Command-line interface for quick token generation
• 🔧 Environment Configuration – Auto-configuration from environment variables
• 💡 Helpful Error Messages – Clear error messages with troubleshooting guidance
• 🔒 Secure by Design – Uses secure SecretStr for sensitive data handling
• 📚 Comprehensive Documentation – Detailed guides and API reference at upstox-totp.readthedocs.io

📚 Table of Contents

• 🚀 Features
• 📚 Table of Contents
• 🎯 Quick Start
  • Installation
  • Python SDK Usage
  • CLI Tool Usage
• ⚙️ Configuration
  • Environment Variables
  • Python Configuration
• 🔧 Advanced Usage
  • Context Manager
  • Session Management
  • TOTP Generation
  • Error Handling
• 📖 API Reference
  • Main Classes
  • Response Models
  • Access Token Data
• 📚 Documentation
• 🛠️ CLI Commands
  • Check Environment
  • Generate Token
  • Help
• 🔒 Security Best Practices
• 🚨 Troubleshooting
  • Common Issues
• 📊 Integration Examples
  • With Upstox API
  • Automated Token Refresh with Caching
  • Database Storage Example (SQLite)
• 🎓 Examples
• 🤝 Contributing
  • Development Setup
• 📋 Requirements
• 📝 License
• ⚠️ Important Notes
  • Token Management
  • Disclaimer
• 🙏 Acknowledgments

🎯 Quick Start

Requires Python 3.12 or higher

Installation

# Add as a dependency to your project
uv add upstox-totp

# Or install with pip
pip install upstox-totp

Python SDK Usage

from upstox_totp import UpstoxTOTP

# Initialize (auto-loads from environment variables or .env file)
upx = UpstoxTOTP()

# Generate access token
try:
    response = upx.app_token.get_access_token()
    
    if response.success and response.data:
        print(f"✅ Access Token: {response.data.access_token}")
        print(f"👤 User: {response.data.user_name} ({response.data.user_id})")
        print(f"📧 Email: {response.data.email}")
        print(f"🏢 Broker: {response.data.broker}")
        print(f"📊 Products: {', '.join(response.data.products)}")
        print(f"🏛️ Exchanges: {', '.join(response.data.exchanges)}")
        
        # Use the token for Upstox API calls
        access_token = response.data.access_token
        
except Exception as e:
    print(f"❌ Error: {e}")

CLI Tool Usage

# Check if environment is properly configured
upstox_cli check-env

# Generate access token
upstox_cli generate-token

Example CLI output:

❯ upstox_cli generate-token

🎉 Access token generated successfully!

Token Details:
Access Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
User ID: BAT123
User Name: Batman
User Type: individual
Broker: UPSTOX
Email: batman@arkham.com
Products: D, I, CO, MIS
Exchanges: NSE_EQ, BSE_EQ, NSE_FO, NSE_CD, BSE_FO, BSE_CD, MCX_FO
Is Active: True

💡 You can now use this access token to make authenticated API calls to Upstox.

⚙️ Configuration

Environment Variables

Create a .env file or set environment variables:

# Required - Your Upstox account credentials
UPSTOX_USERNAME=your-mobile-number      # 10-digit mobile number
UPSTOX_PASSWORD=your-password           # Your Upstox password
UPSTOX_PIN_CODE=your-pin                # Your Upstox PIN code

# Required - TOTP secret from your Upstox app setup
UPSTOX_TOTP_SECRET=your-totp-secret     # TOTP secret key

# Required - OAuth app credentials from Upstox Developer Console
UPSTOX_CLIENT_ID=your-client-id         # API key from app generation
UPSTOX_CLIENT_SECRET=your-client-secret # API secret from app generation
UPSTOX_REDIRECT_URI=your-redirect-uri   # Must match app settings

# Optional
UPSTOX_DEBUG=false                      # Enable debug logging
UPSTOX_SLEEP_TIME=1000                  # Request delay in milliseconds

Python Configuration

from upstox_totp import UpstoxTOTP
from pydantic import SecretStr

# Method 1: Auto-load from environment
upx = UpstoxTOTP()

# Method 2: Load from specific .env file
upx = UpstoxTOTP.from_env_file(".env.production")

# Method 3: Manual configuration
upx = UpstoxTOTP(
    username="9876543210",
    password=SecretStr("your-password"),
    pin_code=SecretStr("your-pin"),
    totp_secret=SecretStr("your-totp-secret"),
    client_id="your-client-id",
    client_secret=SecretStr("your-client-secret"),
    redirect_uri="https://your-app.com/callback",
    debug=True
)

🔧 Advanced Usage

Context Manager

from upstox_totp import UpstoxTOTP

# Use as context manager for automatic cleanup
with UpstoxTOTP() as upx:
    response = upx.app_token.get_access_token()
    if response.success:
        access_token = response.data.access_token
        # Use token for API calls

Session Management

# Access the underlying HTTP session
upx = UpstoxTOTP()
session = upx.session

# Reset session if needed (clears cookies, headers, etc.)
upx.reset_session()

# Generate new request ID
request_id = upx.generate_request_id()

TOTP Generation

# Generate TOTP manually
upx = UpstoxTOTP()
totp_code = upx.generate_totp_secret()
print(f"Current TOTP: {totp_code}")

Error Handling

from upstox_totp import UpstoxTOTP, UpstoxError, ConfigurationError

try:
    upx = UpstoxTOTP()
    response = upx.app_token.get_access_token()
    
except ConfigurationError as e:
    print(f"Configuration Error: {e}")
    print("💡 Check your environment variables in .env file")
    
except UpstoxError as e:
    print(f"Upstox API Error: {e}")
    # Error includes helpful troubleshooting tips
    
except Exception as e:
    print(f"Unexpected Error: {e}")

📖 API Reference

Main Classes

• UpstoxTOTP - Main client class for TOTP authentication
• AccessTokenResponse - Response model for access token data
• UpstoxError - Custom exception with helpful error messages
• ConfigurationError - Raised when configuration is invalid

Response Models

All API responses follow a consistent structure:

class ResponseBase:
    success: bool           # Whether the request was successful
    data: T | None         # Response data (varies by endpoint)
    error: dict | None     # Error details if request failed

Access Token Data

class AccessTokenData:
    access_token: str      # Your Upstox access token
    user_id: str          # Your user ID
    user_name: str        # Your display name
    email: str            # Your email address
    broker: str           # Broker name (UPSTOX)
    user_type: str        # Account type
    products: list[str]   # Available product types
    exchanges: list[str]  # Available exchanges
    is_active: bool       # Account status
    # ... more fields

📚 Documentation

For comprehensive documentation, tutorials, and examples, visit our official documentation:

🌐 upstox-totp.readthedocs.io

The documentation includes:

• 📖 User Guide

  • Installation Guide
  • Quick Start Guide
  • Configuration Guide
  • Advanced Usage Guide
  • CLI Reference

• 🔍 API Reference

  • Client API Reference
  • Data Models Reference
  • Error Handling Reference
  • Logging Reference

• 💡 Examples & Tutorials

  • Basic Usage Examples
  • Integration Examples
  • Token Caching Examples
  • Database Storage Examples

• 🛡️ Additional Information

  • Security Best Practices
  • Troubleshooting Guide
  • Contributing Guide

🛠️ CLI Commands

Check Environment

Validate your configuration before generating tokens:

upstox_cli check-env

Generate Token

Generate access token for API usage:

upstox_cli generate-token

Help

Get help for any command:

upstox_cli --help
upstox_cli generate-token --help

🔒 Security Best Practices

1. Never commit secrets - Use .env files and add them to .gitignore
2. Use SecretStr - Sensitive data is automatically protected from logs
3. Environment variables - Store credentials in environment variables, not code
4. Token rotation - Regenerate tokens regularly for security
5. Debug mode - Disable debug mode in production to prevent credential leaks

🚨 Troubleshooting

Common Issues

Configuration Error: Missing environment variables

# Check what's missing
upstox_cli check-env

# Set required variables in .env file
echo "UPSTOX_USERNAME=9876543210" >> .env
echo "UPSTOX_PASSWORD=your-password" >> .env
# ... add other variables

Invalid Credentials Error

• Verify your username (should be 10-digit mobile number)
• Check password and PIN are correct
• Ensure TOTP secret is properly configured

Client ID / Redirect URI Error

• Verify client_id and client_secret in Upstox Developer Console
• Ensure redirect_uri exactly matches your app settings
• Check if your app is approved and active

TOTP Validation Failed

• Verify your TOTP secret is correct
• Check system time is synchronized
• Ensure TOTP secret format is valid (no spaces, correct encoding)

📊 Integration Examples

With Upstox API

import requests
from upstox_totp import UpstoxTOTP

# Get access token
upx = UpstoxTOTP()
token_response = upx.app_token.get_access_token()
access_token = token_response.data.access_token

# Use token with Upstox API
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

# Get user profile
response = requests.get(
    'https://api.upstox.com/v2/user/profile',
    headers=headers
)
print(response.json())

# Get positions
response = requests.get(
    'https://api.upstox.com/v2/portfolio/long-term-positions',
    headers=headers
)
print(response.json())

Automated Token Refresh with Caching

import time
import json
from datetime import datetime, timedelta
from upstox_totp import UpstoxTOTP

class UpstoxClient:
    def __init__(self, cache_file="upstox_token.json"):
        self.upx = UpstoxTOTP()
        self.cache_file = cache_file
        self.access_token = None
        self.token_expiry = None
        self.load_cached_token()
    
    def load_cached_token(self):
        """Load token from cache if still valid"""
        try:
            with open(self.cache_file, 'r') as f:
                data = json.load(f)
                token_expiry = datetime.fromisoformat(data['expiry'])
                
                # Check if token is still valid (with 1-hour buffer)
                if token_expiry > datetime.now() + timedelta(hours=1):
                    self.access_token = data['token']
                    self.token_expiry = token_expiry
                    print("✅ Using cached token")
                    return
        except (FileNotFoundError, KeyError, ValueError):
            pass
        
        # Cache miss or expired token - refresh
        self.refresh_token()
    
    def refresh_token(self):
        """Refresh access token and cache it"""
        response = self.upx.app_token.get_access_token()
        if response.success:
            self.access_token = response.data.access_token
            self.token_expiry = datetime.now() + timedelta(hours=24)
            
            # Cache the token
            with open(self.cache_file, 'w') as f:
                json.dump({
                    'token': self.access_token,
                    'expiry': self.token_expiry.isoformat()
                }, f)
            
            print("✅ Token refreshed and cached successfully")
        else:
            raise Exception("Failed to refresh token")
    
    def api_call(self, endpoint, **kwargs):
        """Make authenticated API call with auto-refresh"""
        # Check if token needs refresh
        if (self.token_expiry and 
            self.token_expiry < datetime.now() + timedelta(hours=1)):
            print("🔄 Token expiring soon, refreshing...")
            self.refresh_token()
        
        headers = kwargs.setdefault('headers', {})
        headers['Authorization'] = f'Bearer {self.access_token}'
        
        # Make your API call here
        return requests.get(endpoint, **kwargs)

# Usage
client = UpstoxClient()
response = client.api_call('https://api.upstox.com/v2/user/profile')

Database Storage Example (SQLite)

import sqlite3
from datetime import datetime, timedelta
from upstox_totp import UpstoxTOTP

class UpstoxTokenManager:
    def __init__(self, db_path="upstox.db"):
        self.upx = UpstoxTOTP()
        self.db_path = db_path
        self.init_db()
    
    def init_db(self):
        """Initialize database table"""
        conn = sqlite3.connect(self.db_path)
        conn.execute('''
            CREATE TABLE IF NOT EXISTS tokens (
                id INTEGER PRIMARY KEY,
                access_token TEXT NOT NULL,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                expires_at TIMESTAMP NOT NULL
            )
        ''')
        conn.commit()
        conn.close()
    
    def get_valid_token(self):
        """Get valid token from DB or generate new one"""
        conn = sqlite3.connect(self.db_path)
        cursor = conn.execute('''
            SELECT access_token, expires_at FROM tokens 
            WHERE expires_at > datetime('now', '+1 hour')
            ORDER BY created_at DESC LIMIT 1
        ''')
        
        result = cursor.fetchone()
        conn.close()
        
        if result:
            print("✅ Using cached token from database")
            return result[0]
        
        # Generate new token
        return self.refresh_and_store_token()
    
    def refresh_and_store_token(self):
        """Generate new token and store in database"""
        response = self.upx.app_token.get_access_token()
        if not response.success:
            raise Exception("Failed to generate token")
        
        token = response.data.access_token
        expires_at = datetime.now() + timedelta(hours=24)
        
        conn = sqlite3.connect(self.db_path)
        conn.execute('''
            INSERT INTO tokens (access_token, expires_at)
            VALUES (?, ?)
        ''', (token, expires_at))
        conn.commit()
        conn.close()
        
        print("✅ New token generated and stored in database")
        return token

# Usage
token_manager = UpstoxTokenManager()
access_token = token_manager.get_valid_token()

🎓 Examples

Check out the examples/ directory for more comprehensive examples:

• quickstart.py - Basic token generation
• More examples coming soon!

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone the repository
git clone https://github.com/batpool/upstox-totp.git
cd upstox-totp

# Install dependencies with uv
uv sync

# Install development dependencies
uv sync --group dev

# Run tests
uv run pytest

# Format code
uv run black src/
uv run isort src/

📋 Requirements

• Python 3.12 or higher
• Active Upstox trading account
• Upstox Developer App (for client credentials)
• TOTP app setup (Google Authenticator, Authy, etc.)

📝 License

MIT License - see LICENSE file for details.

⚠️ Important Notes

Token Management

📅 Access Token Expiry: Upstox access tokens have a 24-hour expiration time. For production applications, it's recommended to:

• Store tokens securely in a database or cache (Redis, etc.)
• Implement automatic token refresh logic
• Monitor token expiry and regenerate proactively

Disclaimer

This is an unofficial library for Upstox API authentication. Please ensure you comply with Upstox's terms of service and API usage guidelines. Use at your own risk.

🙏 Acknowledgments

• Upstox for providing the trading platform and API
• Pydantic for excellent data validation
• pyOTP for TOTP implementation
• curl-cffi for HTTP client

Happy Trading! 📈

For questions or support, please open an issue on GitHub.