Inspired by epicgames-weekly-freegames, this project takes a different approach to redeeming free games. Automating game redemption using Selenium had some unavoidable downsides:
- Fails on any UI updates to the store
- 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:
- Using APIs that are more stable than web design
- Manually injecting a FunCaptcha session token into the login flow
- Login
- Captcha
- Emails you when a link to solve a Captcha when required
- 2FA handing via TOTP token
- Session ID
- Captcha
- 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
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)
- 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) - 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
- Set the
baseUrl
in the config - Set the SMTP settings in the email config
- Example Gmail settings
- If you have 2FA setup for your Google account, you'll need to create an app password
If you want to test the email and webserver, delete an account's <email>-cookies.json
from your config directory, as this usually forces a fresh login with a captcha. Then just restart the container.
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.
{
"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",
},
}
}
If you are using full JSON configuration, the only remaining Docker configurables are TZ
and the volume.
Variable | Example | Default | Description |
---|---|---|---|
[email protected] |
Epic Games login email. For multiple accounts, use JSON Configuration | ||
PASSWORD | abc123 |
Epic Games login password | |
BASE_URL | 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 | |
SMTP_PORT | 587 |
The outgoing SMTP port (SSL or TLS, see secure ) |
|
EMAIL_SENDER_ADDRESS | [email protected] |
The sender of the email you will recieve (can be your email address) | |
EMAIL_SENDER_NAME | Epic Games Captchas |
The name of the email sender | |
EMAIL_RECIPIENT_ADDRESS | [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 |
|
SMTP_USERNAME | [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. | |
ONLY_WEEKLY | 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 |
RUN_ON_STARTUP | true |
false |
(Optional) If true, the process will run on startup in addition to the scheduled time |
INTERVAL_TIME | 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 |
RUN_ONCE | true |
false |
(Optional) If true, don't schedule runs. Use with RUN_ON_STARTUP to run once and shutdown. |
LOG_LEVEL | info |
info |
(Optional) Log level in lower case. Can be [silent, error, warn, info, debug, trace] |
TZ | America/Chicago |
UTC |
(Optional) TZ name |
Host port | Container port | Description |
---|---|---|
3000 |
3000 |
Port mapping on which the web server hosting the Captcha solving page resides |
Host location | Container location | Mode | Description |
---|---|---|---|
/my/host/dir/ |
/usr/app/config |
rw |
Location of the config and cookie file |
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:
- Go here to enable 2FA.
- Click "enable authenticator app."
- In the section labeled "manual entry key," copy the key.
- Use your authenticator app to add scan the QR code.
- Activate 2FA by completing the form and clicking activate.
- Once 2FA is enabled, use the key you copied as the value for the TOTP parameter.
$ docker run -d -e TZ=America/Chicago -v /my/host/dir/:/usr/app/config:rw -p 3000:3000 charlocharlie/epicgames-freegames:latest
$ 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
If you're experiencing issues logging with with username and password, you can import cookies for a temporary session.
- Setup the container per the below instructions
- In your web browser, log in to the Epic Games Store with "Remember me" checked.
- Install the Cookie Editor or EditThisCookie browser extension.
- While viewing the Epic Games Store page, copy your cookies to clipboard by clicking the "Export" button on the extension:
- In your mounted
./config
folder, create<email_address>-cookies.json
(e.g.[email protected]
), and paste in your cookies. - 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
""
.
Place these variables in a .env
file in the project root.
Variable | Example | Description |
---|---|---|
TEST_USER | [email protected] |
The default user to use when not provided in command options |
TEST_PASSWORD | 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 |
These variables are not currently necessary due to the plus-sign email exploit.
Variable | Example | Description |
---|---|---|
PERMANENT_EMAIL_HOST | imap.zoho.com |
The incoming IMAP server name |
PERMANENT_EMAIL_PORT | 993 |
The incoming IMAP port |
PERMANENT_EMAIL_USER | [email protected] |
The IMAP username |
PERMANENT_EMAIL_PASS | xyz789 |
The IMAP password |
PERMANENT_EMAIL_ADDRESS | example |
The email address portion before the '@' |
PERMANENT_EMAIL_ADDRESS_HOST | zohomail.com |
The email address portion after the '@' |