🔥 Free Fire Toolkit

A simple web app with four Free Fire tools in one place:

• Free Fire ID Check — look up a player's profile (name, level, rank, guild)
• Ban Checker — check if an account is banned or suspended
• Player Stats Checker — view career Solo / Duo / Squad stats
• Craftland Map Checker — look up a community Craftland map by its code

It's a thin Node.js/Express web app that calls the Free Fire Community API on your behalf, so your API key stays on the server and never gets exposed in the browser.

This guide assumes no prior experience. If you can copy/paste commands into a terminal, you can get this running.

---

What you need before starting

1. Node.js version 18 or newer. Download it from nodejs.org (the "LTS" version is fine). To check if you already have it, open a terminal and run:

   node --version
   

   If that prints something like v18.x.x or higher, you're good.

2. Git (only needed if you're cloning via git clone instead of downloading a ZIP). Get it from git-scm.com.

3. A Free Fire Community API key. This app doesn't work without one — see the next section.

---

Step 1: Get your API key

This app is just a frontend + proxy. All the actual Free Fire data comes from the third-party Free Fire Community API, which requires a paid API key to use.

1. Go to developers.freefirecommunity.com
2. Sign up for an account
3. Pick a plan and get your API key from the dashboard (check their pricing page for current rate limits and costs)
4. Copy the key somewhere safe — you'll paste it into this project in Step 3

Note: This API and the Free Fire Community platform are an independent, third-party project. They are not affiliated with, endorsed by, or connected to Garena or Free Fire. Full details are in their docs.

---

Step 2: Get the project on your machine

Option A — Clone with Git:

git clone <this-repo-url>
cd Free-Fire-ID-Checker

Option B — Download ZIP: Download the repository as a ZIP from GitHub, extract it, then open a terminal in the extracted folder.

---

Step 3: Configure your API key

1. In the project folder, find the file named .env.example.
2. Make a copy of it named .env (same folder).
   • Windows PowerShell: Copy-Item .env.example .env
   • macOS/Linux: cp .env.example .env
3. Open .env in a text editor. It looks like this:

   FREEFIRE_API_KEY=your_api_key_here
   FREEFIRE_API_BASE_URL=https://developers.freefirecommunity.com/api/v1
   PORT=3000
   

4. Replace your_api_key_here with the real API key you got in Step 1. Leave the other lines as they are unless you know you need to change them.
5. Save the file.

Important: Never commit your .env file to Git or share it publicly — it contains your real API key. This project's .gitignore already excludes it, so a plain git add . won't accidentally include it.

---

Step 4: Install dependencies

In the project folder, run:

npm install

This downloads the small set of packages the server needs (Express, CORS, dotenv). It only needs to be done once (or again if package.json changes).

---

Step 5: Start the app

npm start

You should see something like:

Free Fire Toolkit running at http://localhost:3000

Open that address in your browser. You'll see four tabs: ID Check, Ban Checker, Player Stats, and Craftland Map. Pick a tool, fill in the form, and submit.

If you ever see a yellow banner at the top of the page saying the API key is a placeholder, it means your .env file still has your_api_key_here instead of a real key — go back to Step 3.

To stop the server, go back to the terminal and press Ctrl+C.

---

Using the tools

Tool	What you need	Notes
Free Fire ID Check	Player UID (9-10 digits) + region	Region must match the player's actual server (sg, ind, or br)
Ban Checker	Player UID	Optional language for the ban reason text
Player Stats Checker	Player UID + region	Shows lifetime Solo/Duo/Squad stats
Craftland Map Checker	Map code (8-12 letters/numbers) + region	Region is where the map was created

Regions:

• sg — Singapore / Southeast Asia (SG, ID, ME, VN, TH, CIS, EU, TW, MY, PK, BD)
• ind — India
• br — Brazil / Americas (BR, US, NA, LATAM)

---

Project structure

Free-Fire-ID-Checker/
├── server.js              # Express app entry point
├── src/
│   ├── freefireClient.js  # Talks to the Free Fire Community API, validates input
│   └── routes.js          # /api/v1/info, /stats, /bancheck, /craftland routes
├── public/
│   ├── index.html         # The 4-tab UI
│   ├── app.js              # Frontend logic (fetch calls, rendering results)
│   └── styles.css          # Styling
├── openapi.yml             # OpenAPI spec describing the upstream API
├── .env.example             # Template for your local config (copy to .env)
└── package.json

---

Troubleshooting

"Request blocked. Please use a supported client application" / FW_001 This comes from the upstream API's own firewall, usually because the API key is missing, invalid, or the request looks automated. Double-check your key in .env and that your plan is active.

"Invalid API key provided" / 401 errors Your key in .env is missing, mistyped, or expired. Get a fresh key from your developer dashboard.

"Player not found" / 404 errors Double check the UID and make sure you picked the right region — a player registered in ind won't be found under sg.

"Rate limit exceeded" / 429 errors You've hit your plan's request limit. Wait for it to reset, or upgrade your plan.

Port already in use Change PORT=3000 in your .env file to a different number (e.g. 3001) and restart with npm start.

---

Hosting Guide

This is a single Node.js/Express process that also serves the static frontend from public/ — there's no build step and no database, so it's easy to host almost anywhere that runs Node. Pick whichever option below fits you.

Before deploying anywhere, keep two things in mind:

• Never put your .env file in the deployed image or repo. Set FREEFIRE_API_KEY (and optionally FREEFIRE_API_BASE_URL) as environment variables / secrets in your hosting platform's dashboard instead.
• This app has no built-in authentication or rate limiting. Anyone who can reach the deployed URL can use your API key's quota. If it's going to be public, put it behind one of: your host's rate limiting, a reverse proxy with access controls, or a simple auth layer (e.g. an API key check or Basic Auth in front of it) — see "Locking it down" below.

The app also exposes GET /health (returns { "status": "healthy" }), which most platforms can use as a health check endpoint.

Option A: Render (easiest, has a free tier)

1. Push this project to a GitHub/GitLab repo (make sure .env is not committed — it's already in .gitignore).
2. Go to render.com and create a new Web Service, pointing it at your repo.
3. Configure:
   • Build command: npm install
   • Start command: npm start
   • Environment: Node
4. Under the service's Environment tab, add environment variables:
   • FREEFIRE_API_KEY = your real key
   • FREEFIRE_API_BASE_URL = https://developers.freefirecommunity.com/api/v1 (optional, only if you need to override the default)
   • Don't set PORT — Render injects its own and the app already reads process.env.PORT.
5. Deploy. Render gives you a https://<your-service>.onrender.com URL automatically, with HTTPS included.

Option B: Railway

1. Push the project to GitHub.
2. In railway.app, create a new project from your repo. Railway auto-detects Node and runs npm install + npm start.
3. Open the service's Variables tab and add FREEFIRE_API_KEY (and FREEFIRE_API_BASE_URL if needed). Leave PORT unset — Railway sets it for you.
4. Generate a public domain from the service's Settings → Networking tab.

Option C: Fly.io

Fly needs a Dockerfile (or it can generate one for you). If you want to go this route, I can add a Dockerfile for this project — just ask. Rough outline once one exists:

fly launch          # generates fly.toml, detects the Node app
fly secrets set FREEFIRE_API_KEY=your_real_key
fly deploy

Fly's fly launch will ask for a port; point it at PORT (default 3000, or whatever you set as a secret).

Option D: Your own VPS (Ubuntu example)

For full control, or if you already have a server:

1. Install Node.js 18+ on the server (via nodesource or your distro's package manager).
2. Copy the project to the server (git clone or scp), then run:

   cd Free-Fire-ID-Checker
   npm install
   

3. Create .env directly on the server (not committed, not copied from your machine's history) with your real FREEFIRE_API_KEY.
4. Run it with a process manager so it survives reboots/crashes, e.g. pm2:

   npm install -g pm2
   pm2 start server.js --name freefire-toolkit
   pm2 save
   pm2 startup
   

5. Put it behind a reverse proxy (nginx or Caddy) to handle HTTPS and map port 80/443 to your app's PORT. A minimal nginx server block:

   server {
       listen 80;
       server_name your-domain.com;
   
       location / {
           proxy_pass http://localhost:3000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }
   

   Then use Certbot (certbot --nginx) to get a free TLS certificate.
6. Open port 80/443 in your firewall (ufw allow 'Nginx Full' on Ubuntu) and keep 3000 closed to the outside world so traffic only comes in through nginx.

Locking it down (recommended for any public deployment)

Since there's no built-in auth, consider adding one of these before sharing the URL widely:

• Reverse proxy Basic Auth — nginx/Caddy can require a username/password before requests even reach the app.
• A simple shared-secret check — require a header like x-app-secret on requests and validate it in Express middleware, giving the value to trusted users only.
• Platform-level access controls — Render, Railway, and most PaaS options support restricting access or adding rate limits via add-ons.

If you'd like, I can implement one of these (e.g. a lightweight rate limiter or shared-secret middleware) directly in the Express app.

---

Credits & disclaimer

• Data powered by the Free Fire Community API.
• This project and the underlying API are not affiliated with, endorsed by, or connected to Garena International or Free Fire. It's an independent, community-driven tool built by fans for fans.