https://github.com/immutable/gods-unchained-api
Public developer API documentation for Gods Unchained.
https://github.com/immutable/gods-unchained-api
api blockchain blockchain-gaming ethereum gods-unchained tcg
Last synced: 5 months ago
JSON representation
Public developer API documentation for Gods Unchained.
- Host: GitHub
- URL: https://github.com/immutable/gods-unchained-api
- Owner: immutable
- Created: 2018-09-04T01:55:40.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2025-03-10T23:33:43.000Z (over 1 year ago)
- Last Synced: 2025-03-11T00:27:18.786Z (over 1 year ago)
- Topics: api, blockchain, blockchain-gaming, ethereum, gods-unchained, tcg
- Size: 41 KB
- Stars: 58
- Watchers: 26
- Forks: 11
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Gods Unchained API
Public developer API documentation for [Gods Unchained](https://godsunchained.com), 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](https://discord.gg/UUn3h45). 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](https://discord.gg/2FDZrh2) if you're looking for help or you're wondering what to build.
- [GUDecks](https://gudecks.com)
## 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
}
```
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"
]
}
}
]
```