Need help with epicgames-freegames-node?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

claabs
214 Stars 16 Forks MIT License 180 Commits 22 Opened issues

Description

Automatically login, email you Captchas, and redeem free games from the Epic Games Store. Powered by Docker.

Services available

!
?

Need anything else?

Contributors list

# 333,161
TypeScr...
Shell
HTML
Docker
158 commits
# 342,399
Shell
ddns
dnspod
TypeScr...
1 commit
# 637,935
Shell
TypeScr...
HTML
Docker
1 commit
# 76,310
Angular
D
Laravel
confere...
1 commit

Epic Games Store Weekly Free Games

Purpose

Inspired by epicgames-weekly-freegames, this project takes a different approach to redeeming free games. Automating game redemption using Selenium had some unavoidable downsides:

  1. Fails on any UI updates to the store
  2. Unable to resolve any Captcha requests

I decided to take a different approach by only using the APIs that the Epic Games Store site uses itself. This resolves the above issues by:

  1. Using APIs that are more stable than web design
  2. Manually injecting a FunCaptcha session token into the login flow

Scope

  • Login
    • Captcha
    • Emails you when a link to solve a Captcha when required
    • 2FA handing via TOTP token
    • Session ID
  • Game catalog discovery
    • Get list of available free games
    • Filter out games that are already owned
  • Purchase available free games
    • Order preview
    • Order confirmation
  • Cookie management
    • Save to file in case of shutdown
    • Import cookies from browser
  • Schedule check/purchase via cron string
  • Authentication refresh to reduce login count
  • Support for multiple accounts
  • TODO: Proper global store support (Works fine for now)
  • TODO: Redeem all free games, not just the weekly promotion

Setup

Captcha Emails

Recent events have removed the ability to easily automate Captcha solving with Google Speech-to-text. This is a workaround that makes you solve a captcha by emailing you a link where you can solve it. To use this requires:

  • The ability to expose ports on your machine/local network/internet
    • Where you expose the port limits where you can solve captchas from (the machine running the container/your home network/anywhere, respectively)
  • Access to an SMTP server for email (Gmail works)

Email Setup

  1. Expose port 3000 in your Docker run config (e.g.
    -p 81:3000
    maps the machine's port 81 to the container's port 3000)
  2. If you want to access the Captcha solving page from outside your network, setup any port forwarding/reverse proxy/DNS
    • Hosting over HTTPS may result in better captcha solving success
  3. Set the
    baseUrl
    in the config
  4. Set the SMTP settings in the email config

If you want to test the email and webserver, delete an account's

-cookies.json
from your config directory, as this usually forces a fresh login with a captcha. Then just restart the container.

JSON Configuration

The tool can be configured with a combination of JSON and environment variables. The config file supports JSON5 syntax (comments, trailing commas, etc). For each property, the JSON config value takes priority over the respective environment variable value. For details on each property, see the table below.

The config file is store in the mounted

./config
directory.

config.json
or
config.json5

{
    "accounts": [
        // Multiple accounts can be configured here
        {
            "email": "[email protected]",
            "password": "abc123",
            "totp": "EMNCF83ULU39CYFOPAQW8VHZBC7S7CTWKDXM19C2S2JYI69R39NE"
        },
        {
            "email": "[email protected]",
            "password": "abc123",
        },
    ],
    "onlyWeekly": false,
    "runOnStartup": true,
    "intervalTime": 60,
    "cronSchedule": "0 12 * * *",
    "runOnce": false,
    "logLevel": "info",
    "baseUrl": "https://example.com",
    "email": {
        "smtpHost": "smtp.gmail.com",
        "smtpPort": 587,
        "emailSenderAddress": "[email protected]",
        "emailSenderName": "Epic Games Captchas",
        "emailRecipientAddress": "[email protected]",
        "secure": false,
        "auth": {
            "user": "[email protected]",
            "pass": "abc123",
        },
    }
}

Docker Congifuration

If you are using full JSON configuration, the only remaining Docker configurables are

TZ
and the volume.

Environment Variables

| Variable | Example | Default | Description | |-------------------------|----------------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | EMAIL |

[email protected]
| | Epic Games login email. For multiple accounts, use JSON Configuration | | PASSWORD |
abc123
| | Epic Games login password | | BASEURL |
https://epic.example.com
|
http://localhost:3000
| The URL you will access to solve Captchas when required. Extra path names are supported | | SMTP
HOST |
smtp.gmail.com
| | The outgoing SMTP host name | | SMTPPORT |
587
| | The outgoing SMTP port (SSL or TLS, see
secure
) | | EMAIL
SENDERADDRESS |
[email protected]
| | The sender of the email you will recieve (can be your email address) | | EMAIL
SENDERNAME |
Epic Games Captchas
| | The name of the email sender | | EMAIL
RECIPIENTADDRESS |
[email protected]
| | The recipient of the email (can be your email address) | | SMTP
SECURE |
true
| |
true
for SSL (port 465),
false
for TLS or unsecure | | SMTPUSERNAME |
[email protected]
| | The SMTP username (if necessary) | | SMTP
PASSWORD |
abc123
| | The SMTP password (if necessary) | | TOTP |
EMNCF83ULU3...YI69R39NE
| | (Maybe required) If 2FA is enabled, add your TOTP secret. See details below. | | ONLYWEEKLY |
true
|
false
| (Optional) By default, the script will redeem all free games in the Epic Games catalog. To only redeem the weekly promotions, set to
true
| | SERVER
PORT |
3333
|
3000
| (Optional) Where the Express server listens. Useful for inter-container networks in Docker Compose, otherwise just stick to
-p
| | RUNONSTARTUP |
true
|
false
| (Optional) If true, the process will run on startup in addition to the scheduled time | | INTERVALTIME |
60
|
60
| (Optional) intervalTime controls the script execution interval of multiple accounts in seconds. (Only effective when multiple accounts are configured using config.json) | | CRON
SCHEDULE |
0 12 * * *
|
0 12 * * *
| (Optional) Cron string of when to run the process. If using
TZ=UTC
, a value of
5 16 * * *
will run 5 minutes after the new games are available | | RUNONCE |
true
|
false
| (Optional) If true, don't schedule runs. Use with RUN
ONSTARTUP to run once and shutdown. | | LOGLEVEL |
info
|
info
| (Optional) Log level in lower case. Can be [silent, error, warn, info, debug, trace] | | TZ |
America/Chicago
|
UTC
| (Optional) TZ name |

Ports

| Host port | Container port | Description | |-----------|----------------|-------------------------------------------------------------------------------| |

3000
|
3000
| Port mapping on which the web server hosting the Captcha solving page resides |

Volumes

| Host location | Container location | Mode | Description | |-----------------|--------------------|------|----------------------------------------| |

/my/host/dir/
|
/usr/app/config
|
rw
| Location of the config and cookie file |

Two-factor login

Epic has begun enforcing two-factor when claiming free games. It is likely necessary when using this tool.

If you have two-factor authentication (2FA) enabled on your account, you need to add your TOTP secret as an environment variable. To get your TOTP secret, you may need to redo your 2FA setup:

  1. Go here to enable 2FA.
  2. Click "enable authenticator app."
  3. In the section labeled "manual entry key," copy the key.
  4. Use your authenticator app to add scan the QR code.
  5. Activate 2FA by completing the form and clicking activate.
  6. Once 2FA is enabled, use the key you copied as the value for the TOTP parameter.

Docker Run

With JSON Config

$ docker run -d -e TZ=America/Chicago -v /my/host/dir/:/usr/app/config:rw -p 3000:3000 charlocharlie/epicgames-freegames:latest

Without JSON Config

$ docker run -d -e TZ=America/Chicago -e [email protected] -e PASSWORD=abc123 -e TOTP=ABC123 -e RUN_ON_STARTUP=true -e BASE_URL=https://example.com -e SMTP_HOST=smtp.gmail.com -e SMTP_PORT=587 -e SMTP_HOST=smtp.gmail.com -e [email protected] -e EMAIL_SENDER_NAME="Epic Games Captchas" -e [email protected] -e SMTP_SECURE=true -e [email protected] -e SMTP_PASSWORD=abc123 -v /my/host/dir/:/usr/app/config:rw -p 3000:3000 charlocharlie/epicgames-freegames:latest

Cookie Import

If you're experiencing issues logging with with username and password, you can import cookies for a temporary session.

  1. Setup the container per the below instructions
  2. In your web browser, log in to the Epic Games Store with "Remember me" checked.
  3. Install the Cookie Editor or EditThisCookie browser extension.
  4. While viewing the Epic Games Store page, copy your cookies to clipboard by clicking the "Export" button on the extension: Cookie Editor export button
  5. In your mounted
    ./config
    folder, create
    -cookies.json
    (e.g.
    [email protected]
    ), and paste in your cookies.
  6. Start the epicgames-freegames-node container and the cookies will automatically be converted to a new format.

Notes:

  • Due to device ID issues, you will only stay logged in for 8 hours.
  • If you log out of the browser session you copied the cookies from, the container will break.
  • If you have the container scheduled regularly, it should automatically refresh the cookies and keep you logged in for some time.
  • If you get an email prompting you to solve a captcha to log in, you should repeat the above process.
  • Epic Games still uses Arkose for purchase captchas, so you still may recieve emails when games are redeemed.
  • Your password is optional when using this, so you can fill it with some junk if you prefer. It just can't be
    ""
    .

Development

Recommended Dev Environment Variables

Place these variables in a

.env
file in the project root.

| Variable | Example | Description | |---------------|----------------------|------------------------------------------------------------------------------------------------------------------| | TESTUSER |

[email protected]
| The default user to use when not provided in command options | | TESTPASSWORD |

xyz789
| The default password to use when not provided in command options | | TEST_TOTP |
xyz789
| The default password to use when not provided in command options | | ENV |
local
| When set to 'local', the create account function will ask you to complete a captcha manually when the bot cannot |

Optional variables

These variables are not currently necessary due to the plus-sign email exploit.

| Variable | Example | Description | |------------------------------|--------------------|------------------------------------------| | PERMANENTEMAILHOST |

imap.zoho.com
| The incoming IMAP server name | | PERMANENTEMAILPORT |
993
| The incoming IMAP port | | PERMANENTEMAILUSER |
[email protected]
| The IMAP username | | PERMANENTEMAILPASS |
xyz789
| The IMAP password | | PERMANENTEMAILADDRESS |
example
| The email address portion before the '@' | | PERMANENTEMAILADDRESS_HOST |
zohomail.com
| The email address portion after the '@' |

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.