InstantFaucet

1. Introduction

Welcome to the official documentation for InstantFaucet. This script is a state-of-the-art crypto earning platform designed with high performance and enterprise-grade security in mind.

Core Modules

  • Faucet: Customizable timers, rewards, and daily limits. Includes advanced requirement rules (e.g., watch a rewarded ad, complete a shortlink, or complete a task each X faucet claims).
  • Multi-Coin System: Seamlessly supports all cryptocurrencies provided by the FaucetPay API.
  • Shortlinks: Multi-step shortlink integration.
  • Tasks: Features PTC (Paid-to-Click), Telegram Tasks, and Website Reviews. Powered by AdsLab integration.
  • Challenges (Achievements): Gamification module rewarding users for hitting milestones (e.g., X faucet claims).
  • Referrals: Built-in affiliate system to drive user acquisition.
  • Coupons: Create and distribute promo codes for instant rewards.
  • Telegram Bot: Used for distributing Auto-Coupons to your channel/group and for mandatory user account verification via Telegram (if enabled from the admin panel).
  • Auto-Updater (OTA): One-click system updates directly from the admin panel.

Enterprise-Grade Security

InstantFaucet deploys multiple layers of aggressive fraud prevention:

  • Cryptographic Payload Signatures
  • Advanced Fingerprinting
  • Geo-IP & VPN Blocking
  • Dynamic Risk Scoring & Honeypots

2. Prerequisites

Before installing InstantFaucet, you must ensure your server meets the following software requirements. We highly recommend using a clean Ubuntu 20.04 or 22.04 LTS VPS, or buying cheap and dedicated hosting from AdsLab, which is specialized and created specifically for these scripts.

  • Node.js (v18+) & NPM: The runtime environment required for both the React frontend and Express backend.
  • MongoDB (v5+): A NoSQL database to store users, logs, and settings securely.
  • PM2 Process Manager: Keeps your application alive in the background and handles Auto-Updates.
  • Nginx / Reverse Proxy (Optional): To serve your application over a domain with an SSL Certificate.

3. Installation Guide

Follow these exact steps to install all required dependencies and the script itself on your Ubuntu VPS.

Step 3.1: Install Node.js & PM2

Run the following commands in your server terminal to install Node.js (v18), NPM, and the PM2 process manager globally:

# Download and install Node.js v18
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install PM2 globally
sudo npm install pm2 -g

Step 3.2: Install MongoDB

Install MongoDB using the official repository:

# Import MongoDB public GPG key and create list file
curl -fsSL https://pgp.mongodb.com/server-7.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

# Update apt and install
sudo apt-get update
sudo apt-get install -y mongodb-org

# Start and enable MongoDB on boot
sudo systemctl start mongod
sudo systemctl enable mongod

Step 3.3: Secure MongoDB & Create Database

For high security, we will create a dedicated database named instantfaucet and a specific user with a password for it.

# Enter the Mongo shell
mongosh

# Switch to the admin database and create root user (replace with your secure password)
use admin
db.createUser({ user: "admin", pwd: "YOUR_SECURE_ADMIN_PASSWORD", roles: [ { role: "userAdminAnyDatabase", db: "admin" } ] })

# Switch to the script database
use instantfaucet

# Create a specific user for this script (replace with your secure script password)
db.createUser({ user: "faucetuser", pwd: "YOUR_SCRIPT_PASSWORD", roles: [{ role: "readWrite", db: "instantfaucet" }] })

# Exit the shell
exit

After doing this, you must edit the MongoDB configuration to enable authorization. Edit /etc/mongod.conf, find the security section and uncomment/add it like this:

security:
  authorization: "enabled"

Then restart MongoDB: sudo systemctl restart mongod

Step 3.4: Install InstantFaucet Script

Upload your script archive to the server (e.g., using SFTP or FileZilla to /var/www/instantfaucet) and extract it.

# Unzip the archive
unzip InstantFaucet.zip
cd InstantFaucet

# Install root dependencies (Monorepo)
npm install

# Build the React frontend
npm run build

The script is now fully installed! Do not start PM2 yet. Proceed to Step 4 to configure your .env file first.

4. Configuration (.env & Bot)

Before starting the backend server, you must configure the environment variables and obtain your free license. Note that Site Name and your Domain are configured globally here.

Step 4.1: Setting up the .env file

Navigate to the backend directory. Rename .env.example to exactly .env and fill in your details.

  • MONGO_URI: Your exact database connection string. E.g., mongodb://username:password@ip:27017/databasename?authSource=databasename
  • TELEGRAM_BOT_TOKEN: The HTTP API Token you got from BotFather.
  • TELEGRAM_GROUP_USERNAME: The username of your Telegram group without the @ symbol.
  • TELEGRAM_CHANNEL_USERNAME: The username of your Telegram channel without the @ symbol.
  • TELEGRAM_BOT_USERNAME: The exact username of your bot without the @ symbol.
  • FAUCETPAY_API: Your FaucetPay API key.
  • LICENSE_KEY: The script license key generated from AdsLab.
  • JWT_SECRET: Add a random string to secure user cookies. E.g., CHANGE_THIS_TO_A_RANDOM_STRING_FOR_SECURITY.
  • WEBSITE_URL: The full URL of your website including HTTPS.
  • DOMAIN: Your exact domain without HTTPS.
  • SITE_NAME: The global name of your website. Displayed in the header.
  • SITE_LOGO: The path to your logo. You must upload your image to the client/public/ folder on your server.
  • SITE_FAVICON: The path to your favicon. Upload your icon to the client/public/ folder.
  • PORT: The port the backend will run on. Default is 8080.
  • ADMIN_FAUCETPAY_EMAIL: The exact FaucetPay email address of the owner. Logging in with this email automatically grants Admin Panel access.

Step 4.2: Getting Your Free License

InstantFaucet is a premium script provided for free by AdsLab, but it requires an active license key attached to your domain. Generate it on AdsLab.me and paste it in your .env.

Step 4.3: Telegram Bot Setup

Use @BotFather on Telegram to create a bot. Put the Token in your .env. CRITICAL: Add the bot as Admin to your Telegram Group and Channel.

Step 4.4: Start the Server

Now that your `.env` is fully configured, save the file and start your application from the root directory using PM2:

# Go back to the root directory
cd ..

# Start the backend server using PM2 via npm workspace
pm2 start npm --name "instant-faucet" -- start

# Save the PM2 process list to auto-start on server reboot
pm2 save
pm2 startup

5. Admin Panel Settings

The InstantFaucet admin panel is modularly divided into multiple sub-sections. Once you log in with an Administrator account, navigate to the Settings tab.

1. Faucet: Configure timer, reward (USD), limits, and requirements.

2. Coins: Toggle active cryptocurrencies for FaucetPay.

3. Security & Captcha: Manage Turnstile/hCaptcha keys, IP-API, and Telegram Verification.

4. Shortlinks: Add APIs from shortlink providers and set custom rewards.

5. AdsLab Integration: Insert Publisher Keys, Rewarded IDs, and manage Floating Ads.

6. Tasks & PTC: Enable/Disable tasks ecosystem.

7. Coupons: Manage Auto-Posting, Reward modes, and usage limits.

8. Challenges: Toggle the achievements gamification system.

9. Referrals: Set affiliate commission percentage.