# 🎮 Free Fire Account Generator

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Version](https://img.shields.io/badge/version-2.0.0-green.svg)](https://pypi.org/project/freefiregen/)

A powerful and reliable Python library for generating and managing Free Fire guest accounts programmatically. Perfect for bot development, account automation, and game testing.

**Author:** @m2_byte  
**Status:** Production Ready  
**License:** MIT

---

## ✨ Features

- 🤖 **Automated Account Generation** - Create Free Fire guest accounts instantly
- 🌍 **Multi-Region Support** - Generate accounts for 13+ different regions
- 🔐 **Secure Credentials** - Returns valid login credentials (UID & Password)
- ⚡ **Auto-Retry Logic** - Automatic retry on transient failures
- 🎯 **Comprehensive Error Handling** - Detailed error messages and handling
- 🚀 **High Performance** - Optimized for batch operations
- 📝 **Well Documented** - Complete API documentation with examples

---

## 📋 Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Reference](#api-reference)
- [Supported Regions](#supported-regions)
- [Error Handling](#error-handling)
- [Advanced Features](#advanced-features)
- [Examples](#examples)
- [Configuration](#configuration)
- [FAQ](#faq)
- [Security Notes](#security-notes)
- [License](#license)

---

## 📦 Installation

### Prerequisites

- Python 3.8 or higher
- pip package manager

### Install from PyPI

```bash
pip install freefiregen
```

---

## 🚀 Quick Start

### Basic Usage

```python
from freefiregen import create_bot_account

# Create a bot account in Middle East region
result = create_bot_account("MyBot", "ME")

if result['success']:
    print(f"✅ Account Created Successfully!")
    print(f"UID: {result['uid']}")
    print(f"Password: {result['password']}")
    print(f"Account ID: {result['account_id']}")
    print(f"Region: {result['region']}")
else:
    print(f"❌ Error: {result['error']}")
```

### Login with Generated Credentials

```python
# Use the generated credentials to login
uid = result['uid']
password = result['password']

# These credentials can be used with Free Fire login API
# or any Free Fire client that supports guest login
```

---

## 📖 API Reference

### `create_bot_account(name, region)`

Creates a new Free Fire guest account with automatic credential generation.

**Parameters:**

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `name` | str | Bot name (max 12 characters, auto-truncated) | `"MyBot"` |
| `region` | str | Region code for account creation | `"ME"`, `"BR"`, `"IND"` |

**Returns:**

Dictionary containing account information:

```python
{
    "success": True,                    # Account creation status
    "uid": "123456789",                 # Guest UID (login credential)
    "password": "m2byte...BOT2",        # Guest password (login credential)
    "account_id": "987654321",          # Free Fire account ID
    "name": "MyBot",                    # Confirmed bot name
    "region": "ME",                     # Region code
    "status_code": 200,                 # HTTP response code
    "error": None                       # Error message (if any)
}
```

**Example:**

```python
result = create_bot_account("BotName", "ME")

# Check success status
if result['success']:
    # Access the credentials
    print(f"Account ID: {result['account_id']}")
    print(f"Login Credentials: {result['uid']}:{result['password']}")
else:
    # Handle error appropriately
    print(f"Failed to create account: {result['error']}")
```

---

## 🌍 Supported Regions

| Code | Region | Language | Description |
|------|--------|----------|-------------|
| ME   | Middle East | Arabic | Middle East servers |
| IND  | India | Hindi | India/South Asia servers |
| ID   | Indonesia | Indonesian | Indonesia servers |
| VN   | Vietnam | Vietnamese | Vietnam servers |
| TH   | Thailand | Thai | Thailand servers |
| BD   | Bangladesh | Bengali | Bangladesh servers |
| PK   | Pakistan | Urdu | Pakistan servers |
| TW   | Taiwan | Chinese | Taiwan servers |
| EU   | Europe | English | European servers |
| CIS  | CIS Region | Russian | CIS/Russian servers |
| NA   | North America | English | North America servers |
| SAC  | South America | Spanish | South American servers |
| BR   | Brazil | Portuguese | Brazil servers |

---

## ⚠️ Error Handling

### Error Types

The library provides detailed error messages for various scenarios:

| Error Type | Description | Solution |
|------------|-------------|----------|
| `RATE_LIMIT` | Too many requests to API | Wait 30-60 seconds before retrying |
| `DUPLICATE_NAME` | Name already exists in region | Choose a different bot name |
| `INVALID_REGION` | Invalid region code provided | Check supported regions list |
| `NETWORK_ERROR` | Connection timeout or network issue | Check internet connection and retry |
| `API_ERROR` | API server returned an error | Retry after a few seconds |
| `UNKNOWN_ERROR` | Unexpected error occurred | Contact support with error details |

### Error Handling Example

```python
from freefiregen import create_bot_account

result = create_bot_account("BotName", "ME")

if result['success']:
    # ✅ Success - Account created
    uid = result['uid']
    password = result['password']
    account_id = result['account_id']
    
    print(f"✅ Account created successfully!")
    print(f"Login credentials: {uid}:{password}")
    print(f"Account ID: {account_id}")
    
else:
    # ❌ Error handling
    error = result['error']
    
    if "RATE_LIMIT" in error:
        print("⏳ Rate limited! Please wait before trying again.")
    
    elif "DUPLICATE_NAME" in error:
        print("⚠️ Name already taken! Choose a different name.")
    
    elif "INVALID_REGION" in error:
        print("❌ Invalid region code! Check supported regions.")
    
    elif "NETWORK_ERROR" in error:
        print("🌐 Network error! Check your internet connection.")
    
    else:
        print(f"❌ Error: {error}")
```

---

## 🔧 Advanced Features

### 1. Automatic Retry Logic

The library automatically retries failed requests up to 3 times for transient network errors. This ensures better reliability when dealing with unstable connections.

```python
# No need to implement retry logic manually
# The library handles it automatically
result = create_bot_account("BotName", "ME")  # Auto-retries on network errors
```

---

## 📚 Examples

### Example 1: Single Account Creation

```python
from freefiregen import create_bot_account

# Create a single account
result = create_bot_account("TestBot", "ME")

if result['success']:
    print(f"✅ Account Created")
    print(f"UID: {result['uid']}")
    print(f"Password: {result['password']}")
```

### Example 2: Batch Account Creation

```python
from freefiregen import create_bot_account
import time

bot_names = ["Bot1", "Bot2", "Bot3", "Bot4", "Bot5"]
accounts = []

for name in bot_names:
    result = create_bot_account(name, "ME")
    
    if result['success']:
        accounts.append({
            'name': name,
            'uid': result['uid'],
            'password': result['password'],
            'account_id': result['account_id']
        })
        print(f"✅ Created: {name}")
    else:
        print(f"❌ Failed: {name} - {result['error']}")
    
    # Respectful rate limiting
    time.sleep(1)

print(f"\n📊 Total created: {len(accounts)}")
```

### Example 3: Multi-Region Account Creation

```python
from freefiregen import create_bot_account

regions = ["ME", "IND", "BR", "EU"]

for region in regions:
    result = create_bot_account("GlobalBot", region)
    
    if result['success']:
        print(f"🌍 {region}: {result['account_id']}")
    else:
        print(f"❌ {region}: {result['error']}")
```

### Example 4: Save Accounts to Database

```python
from freefiregen import create_bot_account
import json

def save_account(account_data):
    """Save account data to JSON file"""
    with open('accounts.json', 'a') as f:
        json.dump(account_data, f)
        f.write('\n')

result = create_bot_account("BotName", "ME")

if result['success']:
    save_account({
        'uid': result['uid'],
        'password': result['password'],
        'account_id': result['account_id'],
        'region': result['region']
    })
```

---

## ⚙️ Configuration

### Environment Variables (Optional)

You can configure the library behavior using environment variables:

```bash
# Set request timeout (seconds)
export FFGEN_TIMEOUT=30

# Set number of retries
export FFGEN_MAX_RETRIES=3

# Enable debug mode
export FFGEN_DEBUG=true
```

### Python Configuration

```python
import os
from freefiregen import create_bot_account

# Override timeout (in seconds)
os.environ['FFGEN_TIMEOUT'] = '30'

# Override max retries
os.environ['FFGEN_MAX_RETRIES'] = '5'

result = create_bot_account("BotName", "ME")
```

---

## ❓ FAQ

**Q: Is this library legal to use?**  
A: This library is for educational and automation testing purposes. Ensure you comply with Free Fire's Terms of Service.

**Q: Can I use this in production?**  
A: Yes, the library is production-ready with automatic error handling and retry logic.

**Q: How many accounts can I create?**  
A: The limit depends on Free Fire's rate limiting. Typically, 1-2 accounts per second is safe.

**Q: What should I do about rate limiting?**  
A: If you get a `RATE_LIMIT` error, wait 30-60 seconds before retrying.

**Q: Can I use accounts for multiple regions?**  
A: Yes, accounts can be created for any supported region independently.

**Q: What's the difference between UID and Account ID?**  
A: UID is the guest login credential, while Account ID is your Free Fire game account identifier.

**Q: How long are the generated accounts valid?**  
A: Guest accounts are typically valid as long as Free Fire's servers support them.

**Q: Can I change the account name after creation?**  
A: Use Free Fire's in-game features to change your account name (if available in your region).

**Q: Is my data secure?**  
A: Credentials are sent only to Free Fire's official servers.

---

## 🔐 Security Notes
- **No Data Storage**: The library does not store any account credentials
- **Official Servers Only**: All requests are sent to Free Fire's official API endpoints
- **SSL Support**: Secure HTTPS connections are used for all communications

### Best Practices

- Store credentials securely (use password managers or encrypted databases)
- Never commit credentials to version control
- Use environment variables for sensitive data
- Implement rate limiting in your applications
- Respect Free Fire's Terms of Service

---

## 📝 Changelog

### Version 2.0.0 (Current)
- ✅ Initial stable release
- ✅ Support for 13+ regions
- ✅ Automatic retry logic
- ✅ Comprehensive error handling

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

### MIT License Summary
- ✅ Commercial use
- ✅ Modification
- ✅ Distribution
- ✅ Private use
- ❌ No Liability
- ❌ No Warranty

---

## 📧 Support & Contact

- **Issues**: Report bugs on [GitHub Issues](https://github.com/m2-byte/freefiregen)
- **Email**: [mtwobyte@gmail.com](mailto:mtwobyte@gmail.com)
- **Discord**: [Join Community](https://discord.com/invite/UdNB434h4Z)

---

## 🎯 Roadmap

### Upcoming Projects
We're building a comprehensive **TVN THDV Bot Control Library** with:
- 🤖 Multi-region bot management and automation
- 📊 Real-time bot monitoring and statistics
- ⚙️ Advanced configuration management tools
- 🔄 Batch account operations and optimization
- 🛡️ Secure bot credential management
- 📈 Bot performance analytics and reporting
- 🎮 Game farming and automation features
- 🔌 Easy integration with existing systems

---

## 👨‍💻 Author

**@m2_byte**
- 📧 Email: [mtwobyte@gmail.com](mailto:mtwobyte@gmail.com)
- 🐱 GitHub: [@m2-byte](https://github.com/m2-byte)
- 🐦 Telegram: [@m2_byte](https://t.me/m2_byte)

---

## ⭐ Acknowledgments

- Free Fire community
- Contributors and testers

---

## 🙋 Get Help

### Common Issues & Solutions

**Issue: `RATE_LIMIT` error**
```python
# Solution: Add delay between requests
import time
result = create_bot_account("Bot1", "ME")
time.sleep(2)  # Wait 2 seconds
result = create_bot_account("Bot2", "ME")
```

**Issue: `NETWORK_ERROR`**
```python
# Solution: Check internet connection and retry
try:
    result = create_bot_account("Bot", "ME")
except Exception as e:
    print(f"Network error: {e}")
    # Implement retry logic
```

---

<div align="center">

### Made with ❤️ for Free Fire Community

If this library helped you, please consider giving it a ⭐ star!

[⬆ Back to top](#-free-fire-account-generator)

</div>
