Player Clan Finder

1. The start

   A scam inside our own clan

   In early 2024 I was in LEGIT, one of the top clans in Pet Simulator 99, the Roblox game by BIG Games built around collecting and trading pets. Our clan was known for its community and for playing fair. Then one of our members was scammed by another member and lost all their valuable pets and items.

2. The goal

   Know where the scammer goes next

   The victim was devastated, and leadership was determined to stop the scammer from simply joining the next big clan and doing it again. We spent hours warning other clans by hand. What we needed was a fast, reliable way to answer one question: which clan is this player in right now?

3. The adventure

   A small tool on a public API

   Pet Simulator 99 has a public API that returns a player's clan. So I built the smallest thing that could work: a Python command-line script that takes a Roblox user ID, calls the game's player endpoint and prints the clan and the player's role in it. Anyone in leadership could run it from a terminal and get an answer in seconds.

   1. Clone

      git clone https://github.com/leafranger/Player-Clan-Finder.git

   2. Install

      pip install requests, the only dependency.

   3. Run

      python clan_finder.py 123456789, with the player's Roblox user ID.

4. The difficulties

   Simple code, real stakes

   The technical side was deliberately simple. The hard part was making it dependable enough that clan leaders would trust it for decisions about real people: handling players with no clan, network errors and unexpected responses without ever printing a misleading answer.

5. The end

   More than fifteen clans warned

   We followed the scammer across several clans and warned more than 15 clan leaders, which helped prevent further scams in other top clans. The tool became part of our clan's security routine, and other clans started using it as a check before accepting new members. It's proof that a small tool, aimed at a real problem, can have an outsized impact.

What's next

• Technical enhancements

  Batch lookups for many players at once, a history of each player's clan changes, a web interface and a database for persistent data.

• Community features

  A shared blacklist, a network of clan leaders, automatic alerts for known scammers and a way for the community to report them.

• Player tracking

  Enter a Roblox user ID and instantly see which clan that player belongs to, and their role in it.

• Command-line interface

  One command from any terminal, easy to fit into a clan's existing management routine.

• Anti-scam protection

  Helps clan leaders follow players with malicious intent as they move from clan to clan.

• Community safety

  Makes it easy to share what you know about scammers, for a safer game for everyone.

The game behind it

Pet Simulator 99 is a popular Roblox game by BIG Games about collecting pets of different rarities, trading them with other players and joining clans for group activities and events. Trading is what makes a scam possible, and clans are what made tracking one worth automating.

Example output

$ python clan_finder.py 123456789
Player 123456789 is in clan: LEGIT
Role: Member

How it works

Player Clan Finder is a Python command-line script built on Pet Simulator 99's public API. It takes a Roblox user ID, requests that player's data from the game's API and reads the clan out of the JSON response.

import sys
import requests

def find_player_clan(roblox_id):
    """Find which clan a player belongs to, through the Pet Simulator 99 API."""
    try:
        response = requests.get(f"https://petsimulator99.com/api/player/{roblox_id}")
        response.raise_for_status()
        data = response.json()
        clan = data.get("clan")
        if clan:
            return {"player_id": roblox_id, "clan_name": clan["name"], "clan_id": clan["id"], "role": clan["role"]}
        return {"player_id": roblox_id, "clan_name": "No Clan", "clan_id": None, "role": None}
    except requests.RequestException as e:
        print(f"Error fetching player data: {e}")
        return None

def main():
    if len(sys.argv) != 2:
        print("Usage: python clan_finder.py <roblox_id>")
        sys.exit(1)
    result = find_player_clan(sys.argv[1])
    if result:
        print(f"Player {result['player_id']} is in clan: {result['clan_name']}")
        print(f"Role: {result['role']}")
    else:
        print("Failed to retrieve player information")

if __name__ == "__main__":
    main()

Run it

1. Clone

   git clone https://github.com/leafranger/Player-Clan-Finder.git

2. Install

   pip install requests, the only dependency.

3. Run

   python clan_finder.py 123456789, with the player's Roblox user ID.

The stack

• Core

  Python, Requests, JSON

  A single script: Requests for the HTTP calls, the standard library for everything else.

• Integration

  Pet Simulator 99 API, Roblox

  The game's public player endpoint, keyed by the Roblox user ID.

• Interface

  Command line

  Arguments in, a two-line answer out. Nothing to install beyond Python.

• Error handling

  Reliability

  Players without a clan and failed requests get a clear answer, never a misleading one.

Skills I gained

• API integration

  Third-party APIs

  HTTP requests, parsing JSON responses and proper error handling for a real-world service.

• CLI development

  Command line

  Argument parsing, input validation and a clear terminal experience.

• Building for a community

  Real-world problem solving

  Spotting what people actually need and shipping something that helps them right away.