hoyo-codes

API to get gift codes for Hoyoverse games, made for auto code redemption feature in Hoyo Buddy.

Besides an API, there is also a simple site for displaying all the available codes: https://hoyo-codes.seria.moe.

Endpoints

• Genshin: https://hoyo-codes.seria.moe/codes?game=genshin
• Honkai Star Rail: https://hoyo-codes.seria.moe/codes?game=hkrpg
• Honkai Impact 3rd: https://hoyo-codes.seria.moe/codes?game=honkai3rd [DEPRECATED]
• Zenless Zone Zero: https://hoyo-codes.seria.moe/codes?game=nap
• Tears of Themis: https://hoyo-codes.seria.moe/codes?game=tot [DEPRECATED]

How it Works

• The run.py file is responsible for running the API
• The update.py file is used to fetch codes from the sources listed in /api/codes/sources.py
• The check.py file is used to check the status of old codes to see if they have expired

update.py

1. We first use aiohttp to get the website's HTML. For pockettactics you would need a user agent, else the website blocks you, this is why the fake-useragent package is used
2. Then we parse the HTML using beautifulsoup + lxml (for faster parsing), then extract the codes from the website by inspecting the HTML elements
3. Next we verify the status of the each code with genshin.py, we would request to HoYoLAB to redeem a specific code, and save the code with different CodeStatus (OK or NOT_OK) based on the redemption result. If the code already exists in the database, we would skip the verification process

check.py

1. We get all the codes in the database with CodeStatus.OK and verify their status with the same technique used in update.py
2. Update the code with the new status

API

The API grabs the codes from the database with CodeStatus.OK and game with the game requested.

You can send POST and DELETE requests to /codes endpoint to add or remove codes manually, but you would need to provide the API_TOKEN in the Authorization header using the Bearer scheme. See the /docs endpoint for more details.

Scheduled Task

The API runs on my machine, and I schedule 2 tasks:

• update.py to run once every 1 hours
• check.py to run once everyday

You can send POST requests to /update-codes and /check-codes endpoints to manually trigger these tasks.

Note

Since v2.4.0, the scheduled tasks are now run inside the API using APScheduler, so you don't need to set up cron jobs or anything similar anymore.

Self-Hosting

Option 1: Docker Compose (Recommended)

This method bundles PostgreSQL database with the API for easy setup:

1. Download docker-compose.yml.
2. Create a cookies.json file in the same directory (see format).
3. Create a uids.json file in the same directory (see format).
4. Change API_TOKEN and POSTGRES_PASSWORD in docker-compose.yml.
5. Run docker compose up -d.

The API will be available at http://localhost:1078.

Note

You can change the HOST and PORT environment variables in docker-compose.yml to bind to different interfaces or ports.

Option 2: Docker Image Only

If you have an existing PostgreSQL database:

1. Create a cookies.json file (see format)
2. Create a uids.json file (see format)
3. Run the container:

docker run -d \
  --name hoyo-codes \
  -p 1078:1078 \
  -e DATABASE_URL="postgresql://user:password@host:5432/dbname" \
  -e API_TOKEN="your_api_token" \
  -e HOST="0.0.0.0" \
  -e PORT="1078" \
  -v ./cookies.json:/app/cookies.json \
  -v ./uids.json:/app/uids.json \
  -v hoyo-codes-logs:/app/logs \
  ghcr.io/seriaati/hoyo-codes:latest

Replace DATABASE_URL with your PostgreSQL connection string. Change API_TOKEN to something secure.

Note

You can change the HOST and PORT environment variables to bind to different interfaces or ports.

cookies.json Format

{
  "genshin": "stoken=...; ltoken_v2=...; ltuid_v2=...",
  "hkrpg": "...",
  "nap": "..."
}

You need game accounts that are eligible to redeem codes (e.g. adventure rank 10+ for Genshin Impact) for the corresponding games, then link them to your Hoyoverse account to get the cookies.

stoken is essentially required because without it the cookie_token will expire very quickly. stoken is a special cookie obtained by logging in with email/username and password, it lasts for a long period of time (usually a year), it can be used to generate new cookie_tokens.

Below is a snippet to get the cookies needed via genshin.py:

import genshin

client = genshin.Client()
cookies = await client.login_with_app_password("me@gmail.com", "EheTeNandayo")
print(cookies.to_str())

If you have one Hoyoverse account linked to multiple game accounts, you just have to copy paste the same cookies for those games.

uids.json Format

{
  "genshin": 123456789,
  "hkrpg": 987654321,
  "nap": 192837465
}

Extra Information

Warning

Honkai Impact 3rd and Tears of Themis endpoints are deprecated, they won't be removed, but no new codes will be added.

Honkai Impact 3rd and Tears of Themis code status cannot be verified. For Hi3, codes can't be redeemed on the website, and for ToT, I don't have a game account for it. The status of codes for these two games will always be CodeStatus.OK. For CN region, they can only redeem codes in-game, so this service is not possible for them.