XUnlocker

Unlock Xbox Live achievements programmatically — interactively or fully automated.

Warning: Unlocking many achievements in a short period has led to account suspensions and permanent bans. Use with caution. The “unlock all” functionality is especially risky and not recommended for your main account.

---

Table of Contents

• What is XUnlocker?
• Features
• Requirements
• Installation
• Usage
  • Interactive CLI
  • Harvest Mode (Batch Automation)
  • Local HTTP API
• Configuration
  • config.toml (Harvest)
  • rarity_times.txt
• API Reference
• Known Issues
• Contributing
• License

---

What is XUnlocker?

XUnlocker is a command‑line tool that talks directly to Xbox Live services to unlock achievements on your account.
It provides:

• A full interactive terminal interface for browsing your game library and unlocking achievements one‑by‑one or in bulk.
• A harvest mode that automates multi‑account, multi‑game unlocking with configurable delays based on achievement rarity.
• A local REST API and web dashboard to control the tool from a browser or scripts.

---

Features

• Two authentication methods

  • Email + password (full Microsoft OAuth flow with ECDSA‑signed requests)
  • Paste an existing XBL3.0 token (note: token permissions vary; insufficient privileges may cause failures)

• Interactive CLI
  Browse Xbox game history, filter by platform (Console, New‑gen, PC), search by name or Title ID, inspect achievement rarity, and unlock individually or in bulk.

• Harvest mode – automated batch processing
  Define multiple accounts and games in a TOML config. Accounts run in parallel; each account processes its games sequentially with configurable delays.

• Rarity‑based timing
  Automatically assigns unlock wait times based on achievement rarity (configurable via rarity_times.txt).

• Game presence spoofing (currently unstable, see known issues)
  Sends periodic heartbeats to simulate playing a title. Used internally during harvest waiting periods.

• Local HTTP API + Web UI
  Start a server on port 3033 and control everything via REST endpoints. A built‑in dashboard provides point‑and‑click access.

• Live progress dashboard
  During harvest runs, see per‑account status, achievement counts, elapsed time, and wait progress in real time.

---

Requirements

• Python 3.9 or newer
• Pip packages: requests, urllib3, colorama, ecdsa (On Python < 3.11 you also need tomli; Python 3.11+ uses the built‑in tomllib)

All dependencies are listed in requirements.txt.

---

Installation

git clone https://github.com/Tadakai/XUnlocker.git
cd XUnlocker
pip3 install -r requirements.txt

No additional build steps are required.

---

Usage

Run the main script:

python3 main.py

Interactive CLI

Choose option 1. You will be asked to authenticate.

• Email & password – performs a full Microsoft login and obtains an XSTS token. This method gives the tool all required permissions.
• Paste token – if you already have a valid XBL3.0 header, you can paste it. Different XSTS tokens may carry different permissions; if operations fail, re‑authenticate with email/password.

Once signed in, you can:

• Browse games, filter by platform, and view achievements.
• Unlock individual achievements, a selection, or all remaining ones.
  Again: “unlock all” is high risk — avoid using it on accounts you care about.
• Start the local API server (4 in the CLI menu).

Harvest Mode (Batch Automation)

Select option 2 from the main menu.
If no config.toml exists, an example will be created for you.

Edit config.toml to define one or more accounts and their games. Example:

[[accounts]]
email = "user1@example.com"
password = "your_password"
games = [
  { title_id = "1234567", percentage = 75, max_achievements = 20, total_minutes = 120 }
]

[[accounts]]
email = "user2@example.com"
password = "another_password"
games = [
  { title_id = "9876543", percentage = 100, max_achievements = 0, total_minutes = 0, achievement_ids = [] }
]

Then rerun python main.py and choose 2. The tool will process all accounts in parallel.

During execution a live dashboard shows progress. Press Ctrl+C to stop all processors gracefully.

Local HTTP API

From the CLI menu (option 1), choose 4 to start the server on port 3033.
Open http://localhost:3033 in a browser to see the web UI and test endpoints.

Quick API examples using curl:

# Get own profile
curl http://localhost:3033/api/profile/me

# Fetch game history
curl http://localhost:3033/api/games/me

# Unlock a single achievement
curl -X POST http://localhost:3033/api/achievements/unlock \
  -H "Content-Type: application/json" \
  -d '{"titleId":"1234567","achievementId":"42"}'

---

Configuration

config.toml (Harvest)

Each [[accounts]] entry can contain multiple games. All fields are optional unless marked as required.

Field	Type	Required	Description
email	string	yes	Microsoft account email
password	string	yes	Microsoft account password
games	array	yes	List of games to process
games[].title_id	string	yes	Xbox Title ID (numeric)
games[].percentage	int	no (100)	% of unlockable achievements to unlock
games[].max_achievements	int	no (0)	Max achievements to unlock (0 = all)
games[].total_minutes	int	no (0)	Total time to distribute across unlocks (0 = rarity‑based)
games[].achievement_ids	array	no ([])	Specific achievement IDs to target (empty = all unlockable)

rarity_times.txt

Customise the wait time before unlocking based on an achievement’s rarity. Each line has the format:
rarity_threshold:min_seconds:max_seconds

Example (default values):

100:360:780
90:720:1260
80:1260:1740
...
0:9000:12600

The tool will pick a random wait time between min_seconds and max_seconds for each achievement whose rarity >= threshold.

---

API Reference

When the local server is running, the following endpoints are available:

Method	Path	Description
GET	/api/profile/me	Own profile (gamertag, XUID, gamerscore)
GET	/api/profile/xuid/{xuid}	Profile by XUID (own only)
GET	/api/games/me	Full game history
GET	/api/games/search/{titleId}	Lookup game metadata by Title ID
GET	/api/achievements/{titleId}	Achievement list for a game
POST	/api/achievements/unlock	Unlock a single achievement (JSON: titleId, achievementId)
POST	/api/achievements/unlockall	Unlock all achievements for a title (JSON: titleId)
GET	/api/spoof/{titleId}	Start a 5‑minute presence heartbeat (currently unstable)
GET	/api/token	Active XBL3.0 token (plain text or ?format=json)

All POST endpoints expect application/json. The server is not intended for production — there is no auth on the API.

---

Known Issues

• Game spoofing is currently broken. The presence heartbeat feature does not work reliably; a fix is being worked on. During harvest mode, spoofed heartbeats may fail, but the unlocking logic itself remains functional.
• XSTS token permissions vary. Tokens obtained from different relying parties may lack permissions for some operations. If you experience unexpected failures, re‑authenticate with the email/password flow.

---

Contributing

Pull requests are welcome For major changes.

---

License

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.