Gods Unchained API
Public developer API documentation for Gods Unchained, a trading card game on the Ethereum blockchain.
This version of the API (v0
) is in a limited public beta: if you discover a bug, or the api returns results contrary to the specification, report it here. Error specifications will be added soon.
Projects
Here are some third-party tools built using these APIs, make sure to ask in our Discord server if you're looking for help or you're wondering what to build.
General
Base URL
The base url for all requests is:
https://api.godsunchained.com
This URL must be suffixed with the version being requested (current version: v0
).
https://api.godsunchained.com/v0/
Duplicate Arguments
We support queries of the following form:
https://api.godsunchained.com/v0/card?god=nature&god=death
Duplicate argument keys will be interpreted disjunctively: this query will return cards where the god is either nature OR death.
Pagination
All requests which can return multiple objects can be shaped by the page
and perPage
parameters.
https://api.godsunchained.com/v0/proto?page=3&perPage=20
All paginated endpoints return data in the following format:
{
total: number
page: number
perPage: number
records: Array<any>
}
Where total
is the number of records discovered by this query.
Sorting
Sorts are applied to paginated endpoints using the sort
and order
query parameters:
https://api.godsunchained.com/v0/card?sort=mana&order=asc
Range and number types can be ordered by order=asc
and order=desc
, defaulting to asc
.
Multiple sort parameters can be applied in one query, and will be applied in order:
https://api.godsunchained.com/v0/card?sort=mana&order=asc&sort=health&order=desc
For queries without exact pairings of sort and order parameters (where multiple parameters are applied), it is necessary to mark the order as null
:
https://api.godsunchained.com/v0/card?sort=mana&order=asc&sort=god&order=null&sort=health&order=desc
Rate Limits
Currently, no rate limits are applied to API usage: this may change in future.
Types
General types:
Type | Description |
---|---|
A url encoded string. | |
A decimal number. | |
true or false |
Custom API types:
Type | Description |
---|---|
A hexadecimal Ethereum address, case insensitive. | |
A specific number 1000 , a range 1000-2000 , a minimum 1000- or a maximum -2000 . |
The valid options for the enumeration types in various apis are set out below:
Concepts
There are several 'types' of card in Gods Unchained:
- Token: A full ERC721 token card which has been 'activated'.
- Model: The most common type of card: locked in, shown on frontend, but not yet converted to an ERC721 token to save gas.
- Centralized: Cards which cannot be traded on the blockchain (part of the core set or an untradeable promotion card).
Some of these endpoints return a combination of the above, while some do not: this is documented by the individual endpoints. In general, the default is to return only cards which can become ERC721 tokens (i.e. Token and Model cards).
Prototype cards, or protos, contain the underlying stats for a class of card.
Summary
Core API
GET /card/{id}
Parameters
Name | Type | Description |
---|---|---|
id | ERC721 id of the card |
Returns the token card with id id
and appropriate metadata. Currently conforms to both the generic and Apollo metadata specifications.
GET /card
Returns a list of token and model cards.
Parameters
Response Format
{
"total": 1000,
"page": 1,
"perPage": 1,
"records": [
{
"id": {
"Int64": 0,
"Valid": false,
}
"proto": 319,
"purity": 59,
"user": "0xCb3562Dd15807e2BCF35092B1e873971AF0a51da"
}
]
}
GET /proto/{id}
Returns the prototype card with id id
.
Parameters
Name | Type | Description |
---|---|---|
id |
id of the prototype card |
Response Format
{
"id":300,
"name":"Guerilla Sabotage",
"effect":"Deal 4 damage to a random enemy creature. Draw a card.",
"god":"Nature",
"rarity":"Common",
"tribe":{"String":"","Valid":false},
"mana":4,
"attack":{"Int64":0,"Valid":false},
"health":{"Int64":0,"Valid":false},
"type":"Spell"
}
GET /proto
Returns a list of prototype cards.
Parameters
Response Format
{
"total": 380,
"page": 1,
"perPage: 1,
"records": [
{
"id":300,
"name":"Guerilla Sabotage",
"effect":"Deal 4 damage to a random enemy creature. Draw a card.",
"god":"Nature",
"rarity":"Common",
"tribe":{"String":"","Valid":false},
"mana":4,
"attack":{"Int64":0,"Valid":false},
"health":{"Int64":0,"Valid":false},
"type":"Spell"
}
]
}
GET /factory/{address}
Returns the pack factory at address address
.
Parameters
Name | Type | Description |
---|---|---|
address |
address of factory |
Response Format
{
"address":"0x0777f76d195795268388789343068e4fcd286919",
"type":"rare"
}
GET /factory
Returns a list of pack factories.
Parameters
Name | Type | Description |
---|---|---|
type |
type of pack |
Response Format
{
"total": 4,
"page": 1,
"perPage: 1,
"records": [
{
"address":"0x0777f76d195795268388789343068e4fcd286919",
"type":"rare"
}
]
}
GET /factory/{address}/purchase/{id}
Returns purchase id
from the pack factory at address
.
Parameters
Name | Type | Description |
---|---|---|
address |
address of factory | |
id |
id of purchase within factory |
Response Format
{
"id":0,
"user":"0x3882C6ba6475165aC5257Ddc1D8d7782E7805c28",
"count":1,
"remaining":0,
"factory":"0x000983ba1A675327F0940b56c2d49CD9c042DFBF",
"txhash":"0xda2b2956588bd642bed4b0aa8f63c979f4893662dd31c237aa58b173bf4eb223",
"type":"shiny"
}
GET /purchase
Returns a list of purchases.
Parameters
Response Format
{
"total": 1000,
"page": 1,
"perPage: 1,
"records": [
{
"id":0,
"user":"0x3882C6ba6475165aC5257Ddc1D8d7782E7805c28",
"count":1,
"remaining":0,
"factory":"0x000983ba1A675327F0940b56c2d49CD9c042DFBF",
"txhash":"0xda2b2956588bd642bed4b0aa8f63c979f4893662dd31c237aa58b173bf4eb223",
"type":"shiny"
}
]
}
GET /factory/{address}/purchase/{id}/pack/{index}
Returns the pack with index index
from purchase id
from the pack factory with address address
.
Parameters
Name | Type | Description |
---|---|---|
address |
address of the pack factory | |
id |
id of the purchase | |
index |
index of the pack within the purchase |
Response Format
{
"purchaseid":11665,
"purchaseindex":0,
"purchaseindices":[0,1,2,3,4],
"user":"0x62ed0960478Cd1aAA29e9e94928107D7b1E2Cef8",
"factory":"0x0777F76D195795268388789343068e4fCd286919",
"opened":true,
"cards":[
{"proto":264,"purity":600},
{"proto":38,"purity":990},
{"proto":299,"purity":549},
{"proto":347,"purity":275},
{"proto":291,"purity":850}
],
"type":"rare"
}
GET /pack
Returns a list of packs.
Parameters
Response Format
{
"total": 1000,
"page": 1,
"perPage: 1,
"records": [
{
"purchaseid":11665,
"purchaseindex":0,
"purchaseindices":[0,1,2,3,4],
"user":"0x62ed0960478Cd1aAA29e9e94928107D7b1E2Cef8",
"factory":"0x0777F76D195795268388789343068e4fCd286919",
"opened":true,
"cards":[
{"proto":264,"purity":600},
{"proto":38,"purity":990},
{"proto":299,"purity":549},
{"proto":347,"purity":275},
{"proto":291,"purity":850}
],
"type":"rare"
}
]
}
GET /referral
Returns a list of referrals.
Parameters
Response Format
{
"total": 1000,
"page": 1,
"perPage: 1,
"records": [
{
"id":0,
"referrer":"0xb08F95dbC639621DbAf48A472AE8Fce0f6f56a6e",
"purchaser":"0xE4a8dfcA175cDcA4Ae370f5b7aaff24bD1C9C8eF",
"factory":"0x1e891C587b345ab02A31b57c1F926fB08913d10D",
"value":1746000000000000000,
"count":0,
"type":"shiny"
}
]
}
GET /image/{id}
Returns an image based on the card prototype with id id
. To get an image in its card form, use the format
and quality
parameters.
Parameters
GET /user/{address}
Get a user.
Parameters
Name | Type | Description |
---|---|---|
address |
the Ethereum address of the user |
Response Format
{
"username": "ender",
"address": "0xC257274276a4E539741Ca11b590B9447B26A8051",
"nonce": 0
}
Helper APIs
To help build more effective applications for our ecosystem, we're also providing a couple of helpful API endpoints. These endpoints may be deprecated in future releases, as they are composable from existing endpoints, but provide a convenient interface during the development of nascent GU-focused applications.
GET /ranking
Returns an ordered list of users with the most cards which meet particular conditions.
Parameters
Response Format
{
"total": 10000,
"page": 1,
"perPage": 1,
"records": [
{
"user": "0xa012623C2d4EB0cfe921Bd283bb1823370Ae2737",
"count": 1585
}
]
}
GET /rarity
Returns rarity information about protos.
Parameters
Sort Options
proto
, plain
, shadow
, gold
, diamond
Response Format
{
"total": 380,
"page": 1,
"perPage": 1,
"records": [
{
"proto": 1,
"plain": 1325,
"shadow": 72,
"gold": 20,
"diamond": 3
}
]
}
GET /user/{address}/inventory
Returns the inventory of the user with address address
, including token, shadow and centralized cards.
Parameters
Response Format
{
"total": 380,
"page": 1,
"perPage": 1,
"records": [
{
"proto": 1,
"purities": [
"100", "200", "300", "2999"
]
}
]
}
DeckString APIs
DeckStrings are a convenient standard for allowing applications to import and export decks. The following APIs provide a convenient interface for basic deck string operations.
POST /deck
Encodes a deck into a deck string.
Request Body
{
"version": 1,
"god": "deception",
"protos": [
290, 17, 201, 201, 80, 80, 93, 93, 64, 64, 185, 185, 55, 55, 97, 331, 281, 281, 252, 252, 330,
330, 280, 202, 202, 265, 265, 37, 94, 94
]
}
Response Format
AQYBBhElYZgCogLLAgIMN0BQXV65AckBygH8AYkCmQLKAg==
GET /deck/{string}
Decodes a deck from a deck string.
Parameters
Response Format
{
"version": 1,
"god": "deception",
"protos": [
290, 17, 201, 201, 80, 80, 93, 93, 64, 64, 185, 185, 55, 55, 97, 331, 281, 281, 252, 252, 330,
330, 280, 202, 202, 265, 265, 37, 94, 94
]
}
GET /mode
Lists the game modes with some properties.
Response Format
[
{
"id": 2,
"name": "Constructed",
"description": "Classic Contructed",
"live": true,
"required_level": 0,
"properties": {
"type": 4,
"image_url": "https://images.godsunchained.com/misc/classic_constructed.webp"
}
}
]
GET /match
Show the match results
Parameters
Name | Type | Description |
---|---|---|
start_time |
start time of the match (UNIX epoch format) | |
end_time |
end time of the match (UNIX epoch format) |
Important: total_turns field will be renamed to total_rounds on a later update, we will continue to support it while we ensure our community is using the new field name.
Response Format
{
"total": 1447,
"page": 1,
"perPage": 20,
"records": [
{
"player_won": 9127,
"player_lost": 6008,
"game_mode": 2,
"game_id": "b64865e2-682b-4a23-af11-20aad0cfd47c",
"start_time": 1560734177,
"end_time": 1560734355,
"player_info": [{"god":"nature","cards":[301,121,68,237,976,1000,973,523,910,385,494,467,905,519,907,507,919,916,906,442,386,537,471,928,475,906,454,909,945,920],"global":false,"health":30,"status":"connected","user_id":9127},{"god":"Magic","cards":[401,401,404,404,908,908,455,455,535,535,467,467,926,926,981,981,402,402,504,504,396,396,406,406,983,983,407,407,1002,1002],"global":true,"health":0,"status":"connected","user_id":6008}],
"total_turns": 6,
"total_rounds": 6
}
]
}
GET /rank
Show the rank of a player per game mode.
Parameters
Name | Type | Description |
---|---|---|
user_id |
Apollo ID of the user | |
game_mode |
Game mode of the rank |
Response Format
{
"total": 543,
"page": 1,
"perPage": 20,
"records": [
{
"user_id": 9115,
"game_mode": 1,
"rating": 952,
"rank_level": 1,
"win_points": 82.849302,
"loss_points": 86.586029
},
{
"user_id": 2317,
"game_mode": 2,
"rating": 875.627936,
"rank_level": 1,
"win_points": 48.249483,
"loss_points": 89.55682
}
]
}
GET /properties
Show the properties of the players.
Parameters
Name | Type | Description |
---|---|---|
user_id |
Apollo ID of the user |
Response Format
{
"total": 8298,
"page": 1,
"perPage": 20,
"records": [
{
"user_id": 612,
"xp_level": 0,
"total_xp": 0,
"xp_to_next": 25,
"won_matches": 0,
"lost_matches": 0,
"username": "bestplayer"
},
{
"user_id": 706,
"xp_level": 36,
"total_xp": 25850,
"xp_to_next": 350,
"won_matches": 51,
"lost_matches": 40,
"username": "broken_player"
}
]
}
GET /predict
Calculates the probability of a match based on the rating of the players (using Elo rating algorithm)
Parameters
Name | Type | Description |
---|---|---|
user_id |
Apollo ID of the user | |
opponent_id |
Apollo ID of the opponent | |
game_mode |
the game mode of the match |
Response Format
0.6717130465747431