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.
- π 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
- π Features
- π Table of Contents
- π― Quick Start
- βοΈ Configuration
- π§ Advanced Usage
- π API Reference
- π Documentation
- π οΈ CLI Commands
- π Security Best Practices
- π¨ Troubleshooting
- π Integration Examples
- π Examples
- π€ Contributing
- π Requirements
- π License
β οΈ Important Notes- π Acknowledgments
Requires Python 3.12 or higher
# Add as a dependency to your project
uv add upstox-totp
# Or install with pip
pip install upstox-totpfrom 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}")# Check if environment is properly configured
upstox_cli check-env
# Generate access token
upstox_cli generate-tokenExample 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: [email protected]
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.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 millisecondsfrom 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
)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# 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()# Generate TOTP manually
upx = UpstoxTOTP()
totp_code = upx.generate_totp_secret()
print(f"Current TOTP: {totp_code}")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}")UpstoxTOTP- Main client class for TOTP authenticationAccessTokenResponse- Response model for access token dataUpstoxError- Custom exception with helpful error messagesConfigurationError- Raised when configuration is invalid
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 failedclass 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 fieldsFor comprehensive documentation, tutorials, and examples, visit our official documentation:
π upstox-totp.readthedocs.io
The documentation includes:
-
π User Guide
-
π API Reference
-
π‘ Examples & Tutorials
-
π‘οΈ Additional Information
Validate your configuration before generating tokens:
upstox_cli check-envGenerate access token for API usage:
upstox_cli generate-tokenGet help for any command:
upstox_cli --help
upstox_cli generate-token --help- Never commit secrets - Use
.envfiles and add them to.gitignore - Use SecretStr - Sensitive data is automatically protected from logs
- Environment variables - Store credentials in environment variables, not code
- Token rotation - Regenerate tokens regularly for security
- Debug mode - Disable debug mode in production to prevent credential leaks
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 variablesInvalid 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)
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())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')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()Check out the examples/ directory for more comprehensive examples:
quickstart.py- Basic token generation- More examples coming soon!
Contributions are welcome! Please feel free to submit a Pull Request.
# 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/- Python 3.12 or higher
- Active Upstox trading account
- Upstox Developer App (for client credentials)
- TOTP app setup (Google Authenticator, Authy, etc.)
MIT License - see LICENSE file for details.
π 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
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.
- 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.