Quick Start Guide

This guide will get you up and running with the Upstox TOTP Python SDK in just a few minutes.

Prerequisites

Before you begin, make sure you have:

1. Python 3.12+ installed

2. Upstox trading account with API access

3. Upstox Developer App created (for API credentials)

4. TOTP app configured (Google Authenticator, Authy, etc.)

Step 1: Install the Package

# Using uv (recommended)
uv add upstox-totp

# Or using pip
pip install upstox-totp

Step 2: Set Up Your Credentials

Create a .env file in your project root:

# Create .env file
touch .env

Add your credentials to the .env file:

# Required - Your Upstox account credentials
UPSTOX_USERNAME=9876543210              # Your 10-digit mobile number
UPSTOX_PASSWORD=your-password           # Your Upstox login 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=https://your-app.com/callback  # Must match app settings

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

Note

Security: Never commit your .env file to version control. Add it to your .gitignore:

echo ".env" >> .gitignore

Step 3: Your First Token Generation

Create a simple Python script:

# quickstart.py

from upstox_totp import UpstoxTOTP

def main():
    # Initialize client (auto-loads from .env file)
    upx = UpstoxTOTP()

    print("🚀 Generating Upstox access token...")

    try:
        # Get access token
        response = upx.app_token.get_access_token()

        if response.success and response.data:
            print("✅ Success! Token generated.")
            print(f"📊 User: {response.data.user_name}")
            print(f"🆔 User ID: {response.data.user_id}")
            print(f"📧 Email: {response.data.email}")
            print(f"🏢 Broker: {response.data.broker}")
            print(f"🔑 Access Token: {response.data.access_token[:20]}...")

            # Store token for later use
            access_token = response.data.access_token

        else:
            print("❌ Failed to generate token")
            if response.error:
                print(f"Error: {response.error}")

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

if __name__ == "__main__":
    main()

Run your script:

python quickstart.py

Expected output:

🚀 Generating Upstox access token...
✅ Success! Token generated.
📊 User: John Doe
🆔 User ID: ABC123
📧 Email: john@example.com
🏢 Broker: UPSTOX
🔑 Access Token: eyJ0eXAiOiJKV1QiLCJ...

Step 4: Using the CLI Tool

The package also includes a command-line interface:

# Check your environment setup
upstox_cli check-env

# Generate a token
upstox_cli generate-token

CLI output example:

❯ upstox_cli generate-token

🎉 Access token generated successfully!

Token Details:
Access Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
User ID: ABC123
User Name: John Doe
User Type: individual
Broker: UPSTOX
Email: john@example.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.

Step 5: Using the Token with Upstox API

Now use your token to make API calls:

# upstox_api_example.py

import requests
from upstox_totp import UpstoxTOTP

def get_user_profile():
    # Get access token
    upx = UpstoxTOTP()
    token_response = upx.app_token.get_access_token()

    if not token_response.success:
        raise Exception("Failed to get access token")

    access_token = token_response.data.access_token

    # Set up headers for API calls
    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
    )

    if response.status_code == 200:
        profile = response.json()
        print("👤 User Profile:")
        print(f"   Name: {profile['data']['user_name']}")
        print(f"   Email: {profile['data']['email']}")
        print(f"   User Type: {profile['data']['user_type']}")
    else:
        print(f"❌ API Error: {response.status_code}")
        print(response.text)

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

    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json'
    }

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

    if response.status_code == 200:
        positions = response.json()
        print("📊 Portfolio Positions:")
        for position in positions['data']:
            print(f"   {position['instrument_token']}: {position['quantity']}")
    else:
        print(f"❌ API Error: {response.status_code}")

if __name__ == "__main__":
    get_user_profile()
    get_portfolio_positions()

Step 6: Context Manager Usage

For automatic cleanup, use the context manager:

# context_manager_example.py

from upstox_totp import UpstoxTOTP

# Using context manager
with UpstoxTOTP() as upx:
    response = upx.app_token.get_access_token()

    if response.success:
        access_token = response.data.access_token
        print(f"✅ Token: {access_token[:20]}...")

        # Use token for API calls
        # Session is automatically cleaned up when exiting the context

Common Configuration Patterns

Environment-specific Configuration

from upstox_totp import UpstoxTOTP

# Load from specific environment file
upx = UpstoxTOTP.from_env_file(".env.production")

Manual Configuration

from upstox_totp import UpstoxTOTP
from pydantic import SecretStr

# Manual configuration (not recommended for production)
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 Mode

from upstox_totp import UpstoxTOTP

# Enable debug logging
upx = UpstoxTOTP(debug=True)

Error Handling Best Practices

from upstox_totp import UpstoxTOTP, UpstoxError, ConfigurationError

def robust_token_generation():
    try:
        upx = UpstoxTOTP()
        response = upx.app_token.get_access_token()

        if response.success and response.data:
            return response.data.access_token
        else:
            print(f"Token generation failed: {response.error}")
            return None

    except ConfigurationError as e:
        print(f"Configuration Error: {e}")
        print("💡 Check your environment variables in .env file")
        return None

    except UpstoxError as e:
        print(f"Upstox API Error: {e}")
        # Error includes helpful troubleshooting tips
        return None

    except Exception as e:
        print(f"Unexpected Error: {e}")
        return None

# Usage
token = robust_token_generation()
if token:
    print("✅ Token generated successfully")
else:
    print("❌ Failed to generate token")

Next Steps

Now that you have the basics working:

1. Learn about advanced features: See Advanced Usage Guide

2. Explore configuration options: See Configuration Guide

3. Check out integration examples: See Integration Examples

4. Read the full API reference: See Client API Reference

5. Learn about token caching: See Token Caching Examples

Common Issues

“Configuration Error: Missing environment variables”

# Check what's missing
upstox_cli check-env

“Invalid credentials” error

• Verify your username is a 10-digit mobile number

• Check password and PIN are correct

• Ensure TOTP secret is from the correct Upstox app setup

“Client ID / Redirect URI” error

• Verify credentials in Upstox Developer Console

• Ensure redirect_uri exactly matches your app settings

• Check if your app is approved and active

Token expires quickly

Note

Upstox access tokens expire after 24 hours. For production applications:

• Implement token caching (see Token Caching Examples)

• Set up automatic refresh logic

• Monitor token expiry

Getting Help

If you run into issues:

• Check the Troubleshooting Guide guide

• Review the Configuration Guide documentation

• Look at more Basic Usage Examples

• Create an issue on GitHub

Congratulations! 🎉

You’ve successfully set up the Upstox TOTP Python SDK and generated your first access token. You’re now ready to integrate with the Upstox API for trading, market data, and portfolio management.