@pure0cd/freefire-api
Version:
A powerful Node.js library to interact with Garena Free Fire API using Protobuf. Login, Search Players, and get Profile Stats.
486 lines (380 loc) • 14.9 kB
Markdown
<div align="center">
<!-- Wave Header with Typing Animation -->
<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=15,22,30&height=220§ion=header&text=Free%20Fire%20API&fontSize=70&fontAlignY=35&animation=twinkling&fontColor=fff&desc=Powerful%20Node.js%20Wrapper%20for%20Garena%20Free%20Fire&descAlignY=55&descSize=20" width="100%" />
<img src="https://dl.dir.freefiremobile.com/common/test/official/FF_SHORT_LOGO.PNG.png" width="130" alt="Free Fire Logo">
# Free Fire API
**The Ultimate Unofficial SDK**
> **Disclaimer**: This is an **unofficial** project and is **not** affiliated, associated, authorized, endorsed by, or in any way officially connected with **Garena Online Private Limited** or **Garena Free Fire**.
---
<p align="center">
<a href="https://www.npmjs.com/package/@pure0cd/freefire-api">
<img src="https://img.shields.io/npm/v/@pure0cd/freefire-api?style=for-the-badge&logo=npm&logoColor=white&color=red" alt="npm version">
</a>
<a href="LICENSE">
<img src="https://img.shields.io/github/license/pure0cd/freefire-api?style=for-the-badge&logo=opensourceinitiative&logoColor=white&color=blue" alt="license">
</a>
<a href="https://github.com/pure0cd/@pure0cd/freefire-api">
<img src="https://img.shields.io/github/stars/pure0cd/freefire-api?style=for-the-badge&logo=github&logoColor=white&color=yellow" alt="stars">
</a>
<a href="https://nodejs.org">
<img src="https://img.shields.io/badge/Node.js-%3E=14-green?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="node">
</a>
</p>
</div>
---
## <img src="https://capsule-render.vercel.app/api?type=soft&height=80&color=gradient&text=Overview§ion=header&reversal=true" width="100%"/>
**Free Fire API** is a robust and efficient Node.js library designed for developers who need to interact with Garena's game servers programmatically. Whether you are building a stats tracker, a tournament management platform, or a profile viewer, this library offers a seamless and type-safe interface.
---
## <img src="https://capsule-render.vercel.app/api?type=soft&height=80&color=gradient&text=Key%20Features§ion=header&reversal=true" width="100%"/>
<table>
<tr>
<td align="center" width="50%">
### 🔍 Smart Search
<img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Objects/Magnifying%20Glass%20Tilted%20Right.png" width="50" />
<br>
Perform fuzzy searches by nickname.
<br>High accuracy and fast response numbers.
</td>
<td align="center" width="50%">
### 👤 Full Profile
<img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/People/Bust%20in%20Silhouette.png" width="50" />
<br>
Retrieve comprehensive user details.
<br>Bio, Level, Likes, Region, Created At.
</td>
</tr>
<tr>
<td align="center" width="50%">
### 📊 Deep Stats
<img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Objects/Bar%20Chart.png" width="50" />
<br>
Analyze player performance.
<br>Battle Royale (BR) & Clash Squad (CS).
</td>
<td align="center" width="50%">
### 🎒 Inventory
<img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Objects/Backpack.png" width="50" />
<br>
Inspect equipped items.
<br>Outfits, Weapon Skins, and Pets.
</td>
</tr>
</table>
---
---
## <img src="https://capsule-render.vercel.app/api?type=soft&height=80&color=gradient&text=Installation§ion=header&reversal=true" width="100%"/>
Install the package via npm:
```bash
npm install /freefire-api
```
---
## <img src="https://capsule-render.vercel.app/api?type=soft&height=80&color=gradient&text=Usage§ion=header&reversal=true" width="100%"/>
### ⚡ Quick Start
The library handles authentication automatically as a guest if you don't provide credentials.
### 1. 🔍 Search Player
Search for a player by their in-game nickname.
```javascript
const FreeFireAPI = require('/freefire-api');
const api = new FreeFireAPI();
(async () => {
// Auto-login (Guest) is handled automatically!
const players = await api.searchAccount("Miyya");
console.log(players);
})();
```
**Response Example:**
```json
[
{
"accountid": "16207002",
"nickname": "Miyya",
"level": 74,
"exp": 4567890,
"region": "ID",
"liked": "12345"
}
]
```
---
### 2. 👤 Get Player Profile
Retrieve detailed information about a specific player using their UID.
```javascript
(async () => {
const profile = await api.getPlayerProfile("16207002");
console.log(profile);
})();
```
**Response Example:**
```json
{
"basicinfo": {
"accountid": "16207002",
"nickname": "Miyya",
"level": 74,
"exp": 4567890,
"region": "ID",
"liked": "12345",
"createat": 1512977151,
"lastloginat": 1738243535
},
"claninfo": {
"clanid": "100200300",
"clanname": "MY_GUILD"
},
"petinfo": {
"name": "Falco",
"level": 7,
"exp": 1200
}
}
```
---
### 3. 📊 Get Player Stats
Fetch statistics for Battle Royale (BR) or Clash Squad (CS).
**Parameters:**
- `mode`: `'br'` or `'cs'`
- `type`: `'career'`, `'ranked'`, or `'normal'`
```javascript
(async () => {
// Battle Royale Career Stats
const brStats = await api.getPlayerStats("16207002", "br", "career");
console.log(brStats);
})();
```
**Response Example:**
```json
{
"solostats": {
"games": 1500,
"wins": 200,
"kills": 4500,
"kd": "3.00"
},
"duostats": {
"games": 800,
"wins": 150,
"kills": 2000
},
"quadstats": {
"games": 3000,
"wins": 600,
"kills": 10000
}
}
```
---
### 4. 🎒 Get Inventory
See what items (Outfits, Weapons, Skills, Pets) the player is currently equipping.
```javascript
(async () => {
const items = await api.getPlayerItems("16207002");
console.log(items);
})();
```
**Response Example:**
```json
{
"outfit": [
{ "id": "101001", "name": "Skull Mask" },
{ "id": "102005", "name": "Red Jacket" }
],
"weapons": {
"shown_skins": [
{ "id": "907001", "name": "AK47 - Blue Flame" }
]
},
"skills": {
"equipped": [
{ "id": "123", "name": "Alok: Drop the Beat" }
]
},
"pet": {
"name": "Falco",
"id": { "id": "123001", "name": "Falco" }
}
}
```
---
### 🔐 Using Custom Credentials
If you want to use a specific account:
```javascript
await api.login("YOUR_UID", "YOUR_PASSWORD");
```
---
## <img src="https://capsule-render.vercel.app/api?type=soft&height=80&color=gradient&text=Running%20Tests§ion=header&reversal=true" width="100%"/>
The library includes a suite of test scripts to verify individual features. You can run them using `npm run` commands:
### Standard Tests
| Command | Description |
| :--- | :--- |
| `npm test` | Runs the search test by default |
| `npm run test:login` | Tests authentication (logs in as guest) |
| `npm run test:search` | Tests player search functionality |
| `npm run test:profile` | Tests fetching player profile details |
| `npm run test:stats` | Tests fetching career and ranked statistics |
| `npm run test:items` | Tests fetching equipped items (outfits, pets, skills) |
| `npm run test:all` | Runs all available tests sequentially |
<details>
<summary><strong>👇 Click here to see the Full Test Output Preview</strong></summary>
```text
-------------- login.js:
Loaded 27989 items into database.
Starting Login Test...
[i] No credentials provided, using public default account.
Login success!
Token: eyJhbG..............
OpenID: ee3fa7..............
-------------- search.js:
Loaded 27989 items into database.
Starting Search Test for 'folaa'...
[i] No credentials provided, using public default account.
Found 10 players.
Top Result: Folaa (UID: 16778836)
[1] Folaa - UID: 16778836 - LVL: 3
[2] FolAa_66 - UID: 1943283579 - LVL: 46
[3] Folaa_golgem - UID: 14576052221 - LVL: 6
[4] folaa_ji - UID: 9436868269 - LVL: 7
[5] Folaa- - UID: 2357144535 - LVL: 1
[6] FOLAA-khna9 - UID: 2359319137 - LVL: 1
[7] Folaa! - UID: 8638700824 - LVL: 7
[8] folaa!! - UID: 8341924255 - LVL: 17
[9] folaa..... - UID: 6973843243 - LVL: 2
[10] folaa***** - UID: 5824293752 - LVL: 5
-------------- profile.js:
Loaded 27989 items into database.
Starting Profile Test for UID: 12345678...
[i] No credentials provided, using public default account.
--- Basic Info ---
Nickname: FB:ㅤ
Level: 68
EXP: 2301178
Region: SG
Likes: 3637393
Created At: 12/7/2017, 5:19:29 AM
Last Login: 1/30/2026, 8:05:20 AM
--- Pet Info ---
Pet Name: SiNo
Pet Level: 7
-------------- stats.js:
Loaded 27989 items into database.
Starting Stats Test for UID: 16207002...
Fetching BR Career...
[i] No credentials provided, using public default account.
--- BR Career ---
Solo: {"accountid":"16207002","gamesplayed":1055,"wins":88,"kills":2769,"detailedstats":{"deaths":967,"top10times":0,"topntimes":279,"distancetravelled":3224879,"survivaltime":458396,"revives":0,"highestkills":20,"damage":812652,"roadkills":47,"headshots":1453,"headshotkills":630,"knockdown":0,"pickups":58619}}
Duo: {"accountid":"16207002","gamesplayed":461,"wins":80,"kills":1383,"detailedstats":{"deaths":381,"top10times":0,"topntimes":144,"distancetravelled":1544324,"survivaltime":217132,"revives":98,"highestkills":22,"damage":487692,"roadkills":48,"headshots":960,"headshotkills":367,"knockdown":1320,"pickups":32130}}
Squad: {"accountid":"16207002","gamesplayed":6340,"wins":1215,"kills":15821,"detailedstats":{"deaths":5125,"top10times":0,"topntimes":2043,"distancetravelled":26160398,"survivaltime":3167926,"revives":1298,"highestkills":34,"damage":7127329,"roadkills":122,"headshots":12471,"headshotkills":3858,"knockdown":17298,"pickups":577093}}
Fetching BR Ranked...
--- BR Ranked ---
Solo: {"accountid":"16207002","gamesplayed":4,"wins":1,"kills":25,"detailedstats":{"deaths":3,"top10times":0,"topntimes":3,"distancetravelled":13591,"survivaltime":1857,"revives":0,"highestkills":15,"damage":6317,"roadkills":0,"headshots":19,"headshotkills":8,"knockdown":0,"pickups":483}}
Duo: {"accountid":"16207002","gamesplayed":3,"wins":1,"kills":8,"detailedstats":{"deaths":2,"top10times":0,"topntimes":2,"distancetravelled":14501,"survivaltime":1607,"revives":3,"highestkills":4,"damage":2561,"roadkills":0,"headshots":2,"headshotkills":0,"knockdown":10,"pickups":383}}
Squad: {"accountid":"16207002","gamesplayed":456,"wins":40,"kills":1310,"detailedstats":{"deaths":416,"top10times":0,"topntimes":61,"distancetravelled":1576126,"survivaltime":142580,"revives":52,"highestkills":21,"damage":566518,"roadkills":0,"headshots":1139,"headshotkills":352,"knockdown":1489,"pickups":40318}}
Fetching CS Career...
--- CS Career ---
Data: {
"csstats": {
"accountid": "16207002",
"gamesplayed": 3043,
"wins": 1757,
"kills": 12356,
"detailedstats": {
"mvpcount": 987,
"doublekills": 2147,
"triplekills": 829,
"fourkills": 164,
"damage": 5336165,
"headshotkills": 3858,
"knockdowns": 14065,
"revivals": 829,
"assists": 5363,
"deaths": 9763,
"streakwins": 0,
"throwingkills": 0,
"onegamemostdamage": 0,
"onegamemostkills": 0,
"ratingpoints": 0,
"ratingenabledgames": 0,
"headshotcount": 0,
"hitcount": 0
}
}
}
Fetching CS Ranked...
--- CS Ranked ---
Data: {
"csstats": {
"accountid": "16207002",
"gamesplayed": 63,
"wins": 50,
"kills": 244,
"detailedstats": {
"mvpcount": 17,
"doublekills": 38,
"triplekills": 19,
"fourkills": 3,
"damage": 108165,
"headshotkills": 82,
"knockdowns": 308,
"revivals": 28,
"assists": 152,
"deaths": 158,
"streakwins": 14,
"throwingkills": 2,
"onegamemostdamage": 5703,
"onegamemostkills": 12,
"ratingpoints": 579.7000122070312,
"ratingenabledgames": 63,
"headshotcount": 270,
"hitcount": 3046
}
}
}
-------------- items.js:
Loaded 27989 items into database.
Starting Items Test for UID: 12345678...
Getting Player Items...
[i] No credentials provided, using public default account.
--- Summary ---
Outfit Items: 1
Weapon Items: 0
Skills Equipped: 5
Skills: 214049006, 205000455, 211000016, 203052001, 204000470
Pet Name: SiNo
Pet ID: Poring
--- First 5 Outfits ---
- Unknown Item (ID: 50)
All tests passed successfully!
```
</details>
---
## <img src="https://capsule-render.vercel.app/api?type=soft&height=80&color=gradient&text=Project%20Structure§ion=header&reversal=true" width="100%"/>
| File/Folder | Description |
| :--- | :--- |
| `lib/api.js` | Core API implementation logic. |
| `lib/crypto.js` | AES encryption handling for secure communication. |
| `lib/protobuf.js` | Protocol Buffer encoder for Garena's binary format. |
| `data/items.json` | Database mapping Item IDs to Names and Assets. |
| `proto/` | Protocol Buffer definitions (`.proto` files). |
---
## <img src="https://capsule-render.vercel.app/api?type=soft&height=80&color=gradient&text=Showcase§ion=header&reversal=true" width="100%"/>
Check out these awesome projects using this library:
- **[Ortega Tools](https://ortega.web.id/)** - Web Tools by Ortega.
> **Want to list your project here?**
> If you have a project using this library and want to be listed, please contact via email: **teza.io**
---
## <img src="https://capsule-render.vercel.app/api?type=soft&height=80&color=gradient&text=Acknowledgements§ion=header&reversal=true" width="100%"/>
We perform this work standing on the shoulders of giants. Special thanks to the open-source community for their Reverse Engineering efforts.
- **[0xMe/FreeFire-Api](https://github.com/0xMe/FreeFire-Api)**: Prior research established a Python-based workflow. This project converts that logic into an easy-to-use JavaScript implementation, with equivalent functionality.
---
## <img src="https://capsule-render.vercel.app/api?type=soft&height=80&color=gradient&text=License§ion=header&reversal=true" width="100%"/>
This project is licensed under the **GNU General Public License v3.0** and <strong>Maintained by <a href="https://github.com/pure0cd">pure0cd</a>.</strong>
---
## <img src="https://capsule-render.vercel.app/api?type=soft&height=80&color=gradient&text=Support§ion=header&reversal=true" width="100%"/>
If you find this project helpful and would like to support the development, you can treat me to a coffee! ☕
**Donate via SocialBuzz:**
[https://sociabuzz.com/0cd/tribe](https://sociabuzz.com/0cd/tribe)
> *A huge thank you to everyone who has supported! Your support keeps this project alive.* ❤️
---
<div align="center">
<br/>
<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=15,22,30&height=120§ion=footer&animation=twinkling&fontAlignY=75" width="100%" alt="Footer"/>
</div>