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

Quick Start

Installation

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

# Or install with pip
pip install upstox-totp

Basic 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}")

        # Use the token for Upstox API calls
        access_token = response.data.access_token

except Exception as e:
    print(f"❌ Error: {e}")

CLI Usage

# Check if environment is properly configured
upstox_cli check-env

# Generate access token
upstox_cli generate-token

Documentation Contents

User Guide

API Reference

Examples & Tutorials

Additional Information

Indices and tables

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 for details.

Important Notes

Warning

📅 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

Note

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.