# Multi-Name Sniper Guide

## Overview

The Minecraft Username Sniper now supports **sniping multiple usernames in a single run**, each with automatic token refresh capabilities.

## Features

### 1. Multi-Name Mode

Snipe multiple usernames sequentially, with three execution strategies:

- **Sequential**: Process names one at a time, waiting for each to complete
- **Parallel**: Process all names simultaneously (if timing allows)
- **Staggered**: Process names with a configurable delay between each

### 2. Auto-Token Refresh

Automatically authenticate Microsoft accounts via OAuth Device Flow:

- Supports `email:password` format (triggers OAuth flow)
- Supports raw bearer tokens (skips OAuth)
- Mixed format files (credentials + tokens together)
- Token caching for reuse

## Quick Start

### Basic Multi-Name Snipe

1. **Launch the GUI:**
   ```bash
   cd /home/bub/minecraft-sniper-gui
   python3 sniper_gui_nuclear.py
   ```

2. **Enter Multiple Usernames:**
   In the "Username" field, enter one name per line:
   ```
   Dream
   Technoblade
   Grian
   ```

3. **Configure Mode:**
   - Select timing mode (Exact or Windowed)
   - Set drop time
   - Load your tokens (or use auto-auth)

4. **Start Sniping:**
   Click "🎯 START SNIPE" and the system will process all names in order

### Using Auto-Auth from Credentials

1. **Create an accounts file** (`accounts.txt`):
   ```
   user1@example.com:MyPassword123
   user2@example.com:AnotherPassword456
   eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs... (raw token, optional)
   ```

2. **Enable Auto-Auth:**
   - Check "Auto-Auth from Credentials"
   - Click "Browse" and select your accounts file
   - Optionally check "Save tokens after auth" for caching

3. **System will automatically:**
   - Load accounts from file
   - Authenticate email:password pairs via Microsoft OAuth
   - Use cached tokens if available
   - Refresh tokens before each snipe (if enabled)

## Account File Format

The system supports three formats (mix and match):

### 1. Email:Password (OAuth)
```
user@example.com:SecurePassword123
```
→ Triggers Microsoft OAuth Device Flow automatically

### 2. Raw Bearer Token (No OAuth)
```
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImlWZG9lMGFQV3l0bWNsNnA4a3NwOF
```
→ Used directly (must be >200 chars, no colons)

### 3. Plain Token
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
→ Treated as bearer token

## Example Usage

### Scenario 1: Single Name, Multiple Tokens
```
Username: Dream
Tokens: (paste 10+ bearer tokens)
Mode: Exact timing at 2026-04-14T17:00:00
```

### Scenario 2: Multiple Names, Same Tokens
```
Username:
  Dream
  Technoblade
  Grian

Tokens: (paste 10+ bearer tokens)
Mode: Staggered (30s delay between names)
Drop Time: 2026-04-14T17:00:00
```

### Scenario 3: Multiple Names, Auto-Auth
```
Username:
  Player1
  Player2
  Player3

Auto-Auth: ✓ Enabled
Accounts File: /path/to/accounts.txt
Save Tokens: ✓ Enabled
```

### Scenario 4: Advanced - Per-Name Timing
(Coming in v2.0)
```
Each name can have its own drop time and stagger window
```

## Technical Details

### OAuth Flow
```
1. POST login.live.com/oauth20_authorize
   → Get device code + user code

2. Poll login.live.com/oauth20_token
   → Get Microsoft access token

3. POST xbl.auth.xboxlive.com
   → Get XBL authentication token

4. POST xsts.auth.xboxlive.com
   → Get XSTS token

5. POST api.minecraftservices.com/minecraft/profile/authentication/
   → Get Minecraft bearer token
```

### Rate Limits
- **Standard:** 3 requests / 30 seconds per account
- **Hard Cap:** 40 requests / 24 hours per account
- **Multi-name mode** automatically rotates tokens to avoid limits

### Token Expiry
- Bearer tokens typically expire after 24 hours
- Auto-auth refreshes tokens before each snipe
- Cached tokens are validated before use

## Troubleshooting

### "No valid tokens found"
- Check that tokens are properly formatted (no extra spaces)
- Use auto-auth to refresh expired tokens
- Verify tokens haven't hit rate limits

### "OAuth authentication failed"
- Check email:password format (no spaces around colon)
- Ensure Microsoft account is valid
- Check for 2FA requirements (may need app-specific password)

### Multi-name mode not working
- Ensure each name is on a separate line
- Check that names are valid Minecraft usernames (3-16 chars, alphanumeric + underscore)
- Verify drop time is in the future

## Performance Tips

1. **More Tokens = Higher Success Rate**
   - Aim for 10+ tokens per name
   - Use auto-auth to manage large account pools

2. **Staggered Mode for Rate Limits**
   - Use 15-30 second stagger delays
   - Prevents hitting 40 req/24h hard cap

3. **DNS Pre-resolution**
   - Enabled by default
   - Reduces first-request latency

4. **Connection Pooling**
   - HTTP/2 multiplexing enabled
   - 100 max connections per pool

## Security Notes

- **Credentials are stored locally** - never uploaded
- **Token cache is optional** - disable if concerned about persistence
- **OAuth flow is official Microsoft API** - not a bypass or exploit
- **No gift card exploitation** - requires valid Microsoft accounts

## Future Enhancements

See `FUTURE_FEATURES.md` for the roadmap:
- Account health dashboard
- Gift card support (POST endpoint)
- Per-name timing configuration
- Worker pool scaling (100+ concurrent requests)

---

*Version: 2.0 (Multi-Name + Auto-Auth)*
*Last Updated: April 13, 2026*