Forge API Documentation

Forge has two APIs that allow our partners to run quests on our platform that reward players for their in-game activity.

• One API for recording a player's game time

• Another one is for recording a player's achievements in the game

Here are the in-game quests that are possible:

• Play the game for N hours

• Play the game for N days in a week

• Play the game for N days in a row

• Unlock a specific achievement in the game

• Unlock N achievements in the game

Mapping “Partner game User with Forge Users”

Both the APIs accept either of the below as the unique identifier to map the “partner users” data with the corresponding “forge users”:

• Email ID

• Blockchain + Wallet Address

If a corresponding user is not present in “Forge,” the data will be archived immediately. It will be later used when a user joins Forge with an “Email ID”/”Blockchain + Wallet Address“ we have data already for or an existing Forge user who connects a new “Blockchain + Wallet Address” to forge for which we have data in the archive.

API Documentation

There are two APIs we support, one for playtime recording and another one for “achievements”:

• Player Playtime Data ingestion API (https://partners-api.forge.gg/player/playtime)

• Player Achievements Ingestion API (https://partners-api.forge.gg/player/achievement)

API key

To access the Forge APIs, you will need an API key. Please reach out to the forge team directly to get an API key, as the “Key” creation process is currently manual.

Forge generates a unique API key for each partner integrating with our system. This key is used to identify the partner, game, and game_id. Also, there is a limit to how many requests one can make to our endpoint using an API Key. The current limit is set at 500K per day. It’s more of a soft/safety limit. If a game partner needs a higher limit, we can increase it.

The API Key format: it is a base64 encoding of

<partner-name>:<game-name>:<game-id>:<secret random-value of size: 12 characters>

Example: Game1,

partner-name	game1
game-name	game1
game-id	game1-01
random secret	cHq12EXeuZvP

The key will be like below.

cGl4ZWw6cGl4ZWw6cGl4ZWwtMDE6Y0hxMTJFWGV1WnZQ

APIs

Player Playtime Data Injection API

It’s an HTTP API to inject player game playtime activities to Forge. Partner and game details will be identified using the API key used in invoking the API. The API supports batch inserts as well to reduce the number of calls that’s been made to our service.

API Details

URL	https://partners-api.forge.gg/player/playtime
Method	POST
Rate Limited	Yes
Quota	Yes. Default: 500K requests per day.

Query Parameters

Not required

Headers

X-API-Key	<Unique API key>
Content-Type	application/json

Payload Fields

Column	Type	Required	Constraints	Description
last_time_played	datetime	✅	Format: YYYY-MM-DD HH:MI:SS	Session end time for the user playing the game in UTC
total_hours	float	✅	≥ 0	Total time played by the user for the current session.
user_email	string	**		Email address used by the user to connect to the game.
wallet_address	string	**		Any web3 wallet used by the user to connect to the game.
blockchain	string	**		Blockchain associated with the shared wallet address.

Note ** Either user_email or wallet_address is required. If wallet_address is used, blockchain in required.

---

Sample Invocation [Single Record]

An example that makes use of user’s email id to identify the user.

curl --location '<https://partners-api.forge.gg/player/playtime>' \\
--header 'X-API-Key: <##########API_KEY###########>' \\
--header 'Content-Type: application/json' \\
--data-raw '{
    "last_time_played": "2022-12-16 12:00:00",
    "total_hours": 10.2,
    "user_email": "ale*****@gmail.com"
}'

An example that makes use of user’s wallet_address to identify the user.

curl --location '<https://partners-api.forge.gg/player/playtime>' \\
--header 'X-API-Key: <##########API_KEY###########>' \\
--header 'Content-Type: application/json' \\
--data-raw '{
    "last_time_played": "2022-12-12 12:00:00",
    "total_hours": 5.5,
    "wallet_address": "0x7adc9fe7c666b84cc8726e2088888*********",
		"blockchain": "ethxxx"
}'

---

Sample Payload [Batch]

Our APIs support batch upload as well. Instead of sending in data 1 by 1, they can send it in as JSON array of records.

[{
    "last_time_played": "2022-12-16 12:00:00",
    "total_hours": 10,
    "wallet_address": "0x7adc9fe7c666b84cc8726e2088888*********",
		"blockchain": "ethxxx"
},
{
    "last_time_played": "2022-12-18 12:00:00",
    "total_hours": 2,
    "wallet_address": "0x7adc9fe7c666b84cc8383e2088888*********",
		"blockchain": "ethxxx",
}]

---

API Response

Status Code: 200

The API will return 200 if there is no errors

{
	"records_processed": 10
}

Status Code: 400

Errors in the payload format or data type or value

{
	"records_processed": 10,
	"records_failed": 2,
	"errors": [
		{
			"record_id": "1",
			"message": "Invalid wallet address."
		},
		{
			"record_id": "2",
			"message": "Invalid email address."
		}
	]
}

Status Code: 429

Reached the daily rate limit. Try again later.

{
    "records_processed": 0,
		"errors": [
			{
				"message": "Quota exceeded"
			}
		]
}

Status Code: 401 or 403

If missing Authorization Headers missing or invalid

{
    "records_processed": 0,
		"errors": [
			{
				"message": "UnAuthorized" // Forbidden
			}
		]
}

Status Code: 5XX

Our system down. Try again later.

{
    "records_processed": 0,
		"errors": [
			{
				"message": "Service Unavailable"
			}
		]
}

---

Player Achievements Injection API

API to inject player’s in-game user achievements unlocked in the game. Partner and game details will be identified using the API key used in invoking the API. The API supports batch inserts as well to reduce the number of calls that’s been made to our service.

---

API Details

URL	https://partners-api.forge.gg/v1/player/achievement
Method	POST
Rate Limited	Yes
Quota	Yes. Default: 500K requests per day.

Query Parameters

Not required

Headers

X-API-Key	<Unique API key>
Content-Type	application/json

---

Payload Fields

Column	Type	Required		Description
achievement_title	string	✅		In game achievement name.
achievement_description	string	✅		A short description to describe the given achievement.
unlock_time	datetime		Format: YYYY-MM-DD HH:MI:SS	Timestamp at which the achievement is ‘achieved’ in game.
unlocked	boolean	✅		Indicator show the achievement is ‘achieved’ for the user.
user_email	string	**		Email address used by the user to connect to the game.
wallet_address	string	**		Any web3 wallet used by the user to connect to the game.
blockchain	string	**		Blockchain associated with the shared wallet address.

Note

** Either user_email or wallet_address is required. If wallet_address is used, blockchain in required.

---

Sample Invocation [Single Record]

An example that makes use of user’s email id to identify the user.

curl --location '<https://partners-api.forge.gg/player/achievement>' \\
--header 'X-API-Key: <##########API_KEY###########>' \\
--header 'Content-Type: application/json' \\
--data-raw '{
    "achievement_title": "Sample achievement title",
    "achievement_description": "Optional: Achievemnent description",
    "unlock_time": "1508053252",
    "unlocked": true,
    "user_email": "ale********.com"
}'

An example that makes use of user’s wallet_address to identify the user.

curl --location '<https://partners-api.forge.gg/player/achievement>' \\
--header 'X-API-Key: <##########API_KEY###########>' \\
--header 'Content-Type: application/json' \\
--data-raw '{
    "achievement_title": "Sample achievement title",
    "achievement_description": "Optional: Achievemnent description",
    "unlock_time": "1508053252",
    "unlocked": true,
    "wallet_address": "0x7adc9fe7c666b84cc8726e2088888*********",
		"blockchain": "ethxxx"
}'

---

Sample Input Payload [Batch]

Our APIs support batch upload as well. Instead of sending in data 1 by 1, they can send it in as JSON array of records.

[{
		"record_id": "12345****",
    "achievement_title": "Sample achievement title",
    "achievement_description": "Optional: Achievemnent description",
    "unlock_time": "1508053252",
    "unlocked": true,
    "user_email": "ale********.com"
}]

---

API Response

Status Code: 200

The API will return 200 if there is no errors

{
	"records_processed": 10
}

Status Code: 400

Errors in the payload format or data type or value

{
	"records_processed": 10,
	"records_failed": 2,
	"errors": [
		{
			"record_id": "1",
			"message": "Invalid wallet address."
		},
		{
			"record_id": "2",
			"message": "Invalid email address."
		}
	]
}

Status Code: 429

Reached the daily rate limit. Try again later.

{
    "records_processed": 0,
		"errors": [
			{
				"message": "Quota exceeded"
			}
		]
}

Status Code: 401 or 403

If missing Authorization Headers missing or invalid

{
    "records_processed": 0,
		"errors": [
			{
				"message": "UnAuthorized" // Forbidden
			}
		]
}

Status Code: 5XX

Our system down. Try again later.

{
    "records_processed": 0,
		"errors": [
			{
				"message": "Service Unavailable"
			}
		]
}