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.

GUDecks

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, there is a rate limit of 5 per second (5/s) on all endpoints. This may change in the 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:

Type	Options
	light, death, nature, war, magic, deception
	rare, epic, legendary, shiny
	common, rare, epic, legendary, mythic
	creature, spell, weapon
	nether, aether, atlantean, viking, olympian, anubian, amazon
	plain, shadow, gold, diamond
	full, card

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

Method	Description	Status
`/card/{id}`	Get card
`/card`	List cards
`/proto/{id}`	Get a proto
`/proto`	List protos
`/factory/{address}`	Get factory
`/factory`	Get a list of factories
`/factory/{address}/purchase/{id}`	Get purchase
`/purchase`	List factories
`/factory/{address}/purchase/{id}/pack/{index}`	Get pack
`/pack`	List packs
`/referral`	Get a list of referrals
`/image/{id}`	Get image
`/user/{address}`	Get user
`/ranking`	List users ranked by cards owned
`/rarity`	Get rarity statistics
`/user/{address}/inventory`	Get a user's inventory
`/deck`	Encode a deck into a deck string
`/deck/{string}`	Decode a deck from a deck string

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

Name	Type	Description
`user`		get cards owned by a specific address
`rarity`		get cards with a specific rarity
`quality`		get cards with a specific quality
`god`		get cards with a specific god
`type`		get cards with a specific type
`tribe`		get cards with a specific tribe
`purity`		get cards with a particular purity
`mana`		get cards with a specific mana
`health`		get cards with a specific health
`attack`		get cards with a specific attack
`proto`		get cards with a specific prototype id

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

Name	Type	Description
`god`		get protos with a specific god
`rarity`		get protos with a specific rarity
`type`		get protos with a specific type
`tribe`		get protos with a specific tribe
`set`		get protos with a specific set
`collectable`		get protos that are collectable or not
`mana`		get protos with a specific mana
`health`		get protos with a specific health
`attack`		get protos with a specific attack

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

Name	Type	Description
`type`		get purchases from a specific pack type
`user`		get purchases made by a specific user
`factory`		get purchases made in a specific factory
`remaining`		number of packs remaining to be activated from this purchase
`count`		number of packs purchased in this purchase

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

Name	Type	Description
`type`		get packs of a specific type
`user`		get packs purchased by a specific user
`factory`		get packs created by a specific factory
`purchase`		get packs created in a specific purchase
`opened`		whether these packs have been opened
`fill`		whether to fill these packs with their cards

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

Name	Type	Description
`type`		get referrals with a specific rarity
`referrer`		get referrals made by a specific user
`purchaser`		get referrals made for a specific user
`factory`		get referrals made in a particular factory

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

Name	Type	Description
`format`		the format in which the image should be presented
`h`		the height to which the image will be resized
`w`		the width to which the image will be resized
`quality`		the quality of the card

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

Name	Type	Description
`rarity`		get rank of cards with a specific rarity
`quality`		get rank of cards with a specific quality
`god`		get rank of cards with a specific god
`type`		get rank of cards with a specific type
`tribe`		get rank of cards with a specific tribe
`purity`		get rank of cards with a minimum purity bound
`mana`		get rank of cards with a specific mana
`health`		get rank of cards with a specific health
`attack`		get rank of cards with a specific attack
`proto`		get rank of cards with a specific prototype id

Response Format

{
    "total": 10000,
    "page": 1,
    "perPage": 1,
    "records": [
        {
            "user": "0xa012623C2d4EB0cfe921Bd283bb1823370Ae2737",
            "count": 1585
        }
    ]
}

GET /rarity

Returns rarity information about protos.

Parameters

Name	Type	Description
`user`		get rarity info about cards owned by a specific address
`rarity`		get rarity info about cards with a specific rarity
`quality`		get rarity info about cards with a specific quality
`god`		get rarity info about cards with a specific god
`type`		get rarity info about cards with a specific type
`tribe`		get rarity info about cards with a specific tribe
`purity`		get rarity info about cards within a purity range
`mana`		get rarity info about cards within a mana range
`health`		get rarity info about cards within a health range
`attack`		get rarity info about cards with an attack range
`proto`	`	get rarity info about cards with a specific prototype id

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

Name	Type	Description
`rarity`		get cards with a specific rarity
`quality`		get cards with a specific quality
`god`		get cards with a specific god
`type`		get cards with a specific type
`tribe`		get cards with a specific tribe
`purity`		get cards within a purity range
`mana`		get cards within a mana range
`health`		get cards within a health range
`attack`		get cards with an attack range
`proto`		get cards with a specific prototype id

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)
`player_won`		user_id of a player
`player_lost`		user_id of a player
`game_mode`		game_mode identifier

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

Quality APIs

The Quality APIs provide data about the qualities and their visual compsition used by public systems.

GET /quality

Shows all the active quality class definitions and related information. Primarily used by supporting systems such as name and id relationships or metadata overrides.

Response Format

[
    {
        "class_key": "quality",
        "class_value": "2",
        "class_properties": {
            "name": "gold"
        },
        "class_type": "card",
        "game_id": 1
    },
    ...
]

GET /quality/{quality}

Shows the specified quality class definition and related information. Primarily used by supporting systems such as name and id relationships or metadata overrides.

Parameters

Name	Type	Description
`quality`		Quality ID

Response Format

{
 "class_key": "quality",
 "class_value": "2",
 "class_properties": {
  "name": "gold"
 },
 "class_type": "card",
 "game_id": 1
}

GET /composition

Shows all the graphical composition data required to generate visuals for the specified proto and quality combinations for NFT art used in Gods Unchained. Currently only supports Card art.

Parameters

Name	Type	Description	Example
`pairs`		Proto and Quality defined with an `@` separator	`1234@5`

Response Format

[
 {
  "id": 1234,
  "name": "Born Again",
  "effect": "Pull a creature from your void to your hand. Give it +5/+5 and ward.",
  "god": "light",
  "rarity": "epic",
  "tribe": { "String": "", "Valid": false },
  "mana": 6,
  "attack": { "Int64": 0, "Valid": false },
  "health": { "Int64": 0, "Valid": false },
  "type": "spell",
  "set": "core",
  "collectable": true,
  "live": "true",
  "art_id": "C448",
  "lib_id": "L2-235",
  "composition": {
   "illustration": [
    "1234"
   ],
   "frame": [
    "spell",
    "spell_plain"
   ],
   "rosette": [
    "light",
    "light_plain"
   ],
   "gems": [
    "rarity_epic"
   ],
   "wreath": [],
   "lock": [
    "lock_plain"
   ],
   "tribe_bar": [],
   "set": [
    "core"
   ]
  }
 }
]

Files

README.md

Latest commit

History

README.md

File metadata and controls

Gods Unchained API

Projects

General

Base URL

Duplicate Arguments

Pagination

Sorting

Rate Limits

Types

Concepts

Summary

Core API

GET /card/{id}

GET /card

GET /proto/{id}

GET /proto

GET /factory/{address}

GET /factory

GET /factory/{address}/purchase/{id}

GET /purchase

GET /factory/{address}/purchase/{id}/pack/{index}

GET /pack

GET /referral

GET /image/{id}

GET /user/{address}

Helper APIs

GET /ranking

GET /rarity

GET /user/{address}/inventory

DeckString APIs

POST /deck

GET /deck/{string}

GET /mode

GET /match

GET /rank

GET /properties

GET /predict

Quality APIs

GET /quality

GET /quality/{quality}

GET /composition