Публичная документация по API для разработчиков Gods Unchained, коллекционной карточной игры на блокчейне Ethereum.
Эта версия API ( v0 ) находится в ограниченной общедоступной бета-версии: если вы обнаружите ошибку или API возвращает результаты, противоречащие спецификации, сообщите об этом здесь. Характеристики ошибок будут добавлены в ближайшее время.
Вот некоторые сторонние инструменты, созданные с использованием этих API. Обязательно спросите на нашем сервере Discord, если вам нужна помощь или вам интересно, что создать.
Базовый URL для всех запросов:
https://api.godsunchained.com
К этому URL-адресу должен быть добавлен суффикс запрашиваемой версии (текущая версия: v0 ).
https://api.godsunchained.com/v0/
Мы поддерживаем запросы следующего вида:
https://api.godsunchained.com/v0/card?god=nature&god=death
Дублирующиеся ключи аргументов будут интерпретироваться раздельно: этот запрос вернет карты, где богом является либо природа, либо смерть.
Все запросы, которые могут возвращать несколько объектов, могут формироваться с помощью параметров page и perPage .
https://api.godsunchained.com/v0/proto?page=3&perPage=20
Все конечные точки с разбивкой на страницы возвращают данные в следующем формате:
{
total: number
page: number
perPage: number
records: Array<any>
}
Где total количество записей, обнаруженных этим запросом.
Сортировки применяются к конечным точкам с разбивкой на страницы с использованием параметров запроса sort и order :
https://api.godsunchained.com/v0/card?sort=mana&order=asc
Типы диапазонов и чисел можно упорядочить с помощью order=asc и order=desc , по умолчанию — asc .
В одном запросе можно применить несколько параметров сортировки, и они будут применяться по порядку:
https://api.godsunchained.com/v0/card?sort=mana&order=asc&sort=health&order=desc
Для запросов без точных пар параметров сортировки и порядка (когда применяется несколько параметров) необходимо пометить порядок как null :
https://api.godsunchained.com/v0/card?sort=mana&order=asc&sort=god&order=null&sort=health&order=desc
В настоящее время на всех конечных точках существует ограничение скорости 5 в секунду (5/с). Это может измениться в будущем.
Общие типы:
| Тип | Описание |
|---|---|
| Строка в кодировке URL. | |
| Десятичное число. | |
true или false |
Пользовательские типы API:
| Тип | Описание |
|---|---|
| Шестнадцатеричный адрес Ethereum, нечувствительный к регистру. | |
Конкретное число 1000 , диапазон 1000-2000 , минимум 1000- или максимум -2000 . |
Допустимые параметры типов перечисления в различных API приведены ниже:
| Тип | Параметры |
|---|---|
| свет, смерть, природа, война, магия, обман | |
| редкий, эпический, легендарный, блестящий | |
| обычный, редкий, эпический, легендарный, мифический | |
| существо, заклинание, оружие | |
| Пустота, эфир, атланты, викинги, олимпийцы, анубийцы, Амазонки | |
| однотонный, тень, золото, бриллиант | |
| полная, карта |
В Gods Unchained есть несколько «типов» карт:
Некоторые из этих конечных точек возвращают комбинацию вышеперечисленного, а некоторые нет: это документировано отдельными конечными точками. Как правило, по умолчанию возвращаются только карты, которые могут стать токенами ERC721 (т. е. карты токенов и моделей).
Карты -прототипы , или protos , содержат базовую статистику для класса карт.
| Метод | Описание | Статус |
|---|---|---|
/card/{id} | Получить карту | |
/card | Список карточек | |
/proto/{id} | Получить прототип | |
/proto | Список прото | |
/factory/{address} | Получить фабрику | |
/factory | Получить список заводов | |
/factory/{address}/purchase/{id} | Получить покупку | |
/purchase | Список заводов | |
/factory/{address}/purchase/{id}/pack/{index} | Получить пакет | |
/pack | Список пакетов | |
/referral | Получить список рефералов | |
/image/{id} | Получить изображение | |
/user/{address} | Получить пользователя | |
/ranking | Список пользователей, ранжированных по принадлежащим картам | |
/rarity | Получить статистику редкости | |
/user/{address}/inventory | Получить инвентарь пользователя | |
/deck | Кодирование колоды в строку колоды | |
/deck/{string} | Декодирование колоды из строки колоды |
Параметры
| Имя | Тип | Описание |
|---|---|---|
| идентификатор | ERC721 идентификатор карты |
Возвращает карту токена с id id и соответствующими метаданными. В настоящее время соответствует как общим спецификациям метаданных, так и спецификациям Apollo.
Возвращает список карточек токенов и моделей.
Параметры
| Имя | Тип | Описание |
|---|---|---|
user | получить карты, принадлежащие определенному адресу | |
rarity | получить карты определенной редкости | |
quality | получить карты с определенным качеством | |
god | получить карты с конкретным богом | |
type | получить карты определенного типа | |
tribe | получить карты с определенным племенем | |
purity | получить карты с особой чистотой | |
mana | получить карты с определенной маной | |
health | получить карты с определенным здоровьем | |
attack | получить карты с определенной атакой | |
proto | получить карточки с определенным идентификатором прототипа |
Формат ответа
{
"total": 1000,
"page": 1,
"perPage": 1,
"records": [
{
"id": {
"Int64": 0,
"Valid": false,
}
"proto": 319,
"purity": 59,
"user": "0xCb3562Dd15807e2BCF35092B1e873971AF0a51da"
}
]
}
Возвращает карту-прототип с идентификатором id .
Параметры
| Имя | Тип | Описание |
|---|---|---|
id | идентификатор прототипа карты |
Формат ответа
{
"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"
}
Возвращает список карточек-прототипов.
Параметры
| Имя | Тип | Описание |
|---|---|---|
god | получить прото с конкретным богом | |
rarity | получить прото с определенной редкостью | |
type | получить прототипы определенного типа | |
tribe | получить прото с определенным племенем | |
set | получить прото с определенным набором | |
collectable | получить прототипы, которые можно коллекционировать или нет | |
mana | получить прото с определенной маной | |
health | получить прото с определенным здоровьем | |
attack | получить прото с помощью конкретной атаки |
Формат ответа
{
"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"
}
]
}
Возвращает фабрику упаковки по address адрес.
Параметры
| Имя | Тип | Описание |
|---|---|---|
address | адрес фабрики |
Формат ответа
{
"address":"0x0777f76d195795268388789343068e4fcd286919",
"type":"rare"
}
Возвращает список фабрик пакетов.
Параметры
| Имя | Тип | Описание |
|---|---|---|
type | тип упаковки |
Формат ответа
{
"total": 4,
"page": 1,
"perPage: 1,
"records": [
{
"address":"0x0777f76d195795268388789343068e4fcd286919",
"type":"rare"
}
]
}
Возвращает id покупки на фабрике упаковки по address .
Параметры
| Имя | Тип | Описание |
|---|---|---|
address | адрес фабрики | |
id | идентификатор покупки на заводе |
Формат ответа
{
"id":0,
"user":"0x3882C6ba6475165aC5257Ddc1D8d7782E7805c28",
"count":1,
"remaining":0,
"factory":"0x000983ba1A675327F0940b56c2d49CD9c042DFBF",
"txhash":"0xda2b2956588bd642bed4b0aa8f63c979f4893662dd31c237aa58b173bf4eb223",
"type":"shiny"
}
Возвращает список покупок.
Параметры
| Имя | Тип | Описание |
|---|---|---|
type | получать покупки из определенного типа пакета | |
user | получить покупки, сделанные конкретным пользователем | |
factory | получить покупки, сделанные на конкретной фабрике | |
remaining | количество пакетов, которые осталось активировать после этой покупки | |
count | количество упаковок, купленных в этой покупке |
Формат ответа
{
"total": 1000,
"page": 1,
"perPage: 1,
"records": [
{
"id":0,
"user":"0x3882C6ba6475165aC5257Ddc1D8d7782E7805c28",
"count":1,
"remaining":0,
"factory":"0x000983ba1A675327F0940b56c2d49CD9c042DFBF",
"txhash":"0xda2b2956588bd642bed4b0aa8f63c979f4893662dd31c237aa58b173bf4eb223",
"type":"shiny"
}
]
}
Возвращает пакет с индексом index из id покупки от фабрики пакетов с address .
Параметры
| Имя | Тип | Описание |
|---|---|---|
address | адрес фабрики упаковки | |
id | идентификатор покупки | |
index | индекс упаковки в покупке |
Формат ответа
{
"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"
}
Возвращает список пакетов.
Параметры
| Имя | Тип | Описание |
|---|---|---|
type | получить пакеты определенного типа | |
user | получить пакеты, купленные конкретным пользователем | |
factory | получить пакеты, созданные определенной фабрикой | |
purchase | получить пакеты, созданные в конкретной покупке | |
opened | были ли открыты эти пакеты | |
fill | стоит ли наполнять эти пачки своими картами |
Формат ответа
{
"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"
}
]
}
Возвращает список рефералов.
Параметры
| Имя | Тип | Описание |
|---|---|---|
type | получить рефералов с определенной редкостью | |
referrer | получить рефералы, сделанные конкретным пользователем | |
purchaser | получить рефералов, сделанных для конкретного пользователя | |
factory | получить рекомендации, сделанные на конкретном заводе |
Формат ответа
{
"total": 1000,
"page": 1,
"perPage: 1,
"records": [
{
"id":0,
"referrer":"0xb08F95dbC639621DbAf48A472AE8Fce0f6f56a6e",
"purchaser":"0xE4a8dfcA175cDcA4Ae370f5b7aaff24bD1C9C8eF",
"factory":"0x1e891C587b345ab02A31b57c1F926fB08913d10D",
"value":1746000000000000000,
"count":0,
"type":"shiny"
}
]
}
Возвращает изображение на основе прототипа карты с идентификатором id . Чтобы получить изображение в карточном виде, используйте параметры format и quality .
Параметры
| Имя | Тип | Описание |
|---|---|---|
format | формат, в котором должно быть представлено изображение | |
h | высота, на которую будет изменен размер изображения | |
w | ширина, до которой будет изменен размер изображения | |
quality | качество карты |
Получите пользователя.
Параметры
| Имя | Тип | Описание |
|---|---|---|
address | адрес Ethereum пользователя |
Формат ответа
{
"username": "ender",
"address": "0xC257274276a4E539741Ca11b590B9447B26A8051",
"nonce": 0
}
Чтобы помочь создавать более эффективные приложения для нашей экосистемы, мы также предоставляем несколько полезных конечных точек API. Эти конечные точки могут быть признаны устаревшими в будущих выпусках, поскольку они могут быть составлены из существующих конечных точек, но обеспечивают удобный интерфейс во время разработки новых приложений, ориентированных на GU.
Возвращает упорядоченный список пользователей с наибольшим количеством карточек, соответствующих определенным условиям.
Параметры
| Имя | Тип | Описание |
|---|---|---|
rarity | получить ранг карт определенной редкости | |
quality | получить ранг карт определенного качества | |
god | получить ранг карт конкретного бога | |
type | получить ранг карт определенного типа | |
tribe | получить ранг карт определенного племени | |
purity | получить ранг карт с минимальным ограничением чистоты | |
mana | получить ранг карт с определенной маной | |
health | получить ранг карт с определенным здоровьем | |
attack | получить ранг карт с определенной атакой | |
proto | получить ранг карт с определенным идентификатором прототипа |
Формат ответа
{
"total": 10000,
"page": 1,
"perPage": 1,
"records": [
{
"user": "0xa012623C2d4EB0cfe921Bd283bb1823370Ae2737",
"count": 1585
}
]
}
Возвращает информацию о редкости прото.
Параметры
| Имя | Тип | Описание |
|---|---|---|
user | получить информацию о редкости карт, принадлежащих определенному адресу | |
rarity | получить информацию о редкости карт определенной редкости | |
quality | получить информацию о редкости карт определенного качества | |
god | получить информацию о редкости карт с конкретным богом | |
type | получить информацию о редкости карт определенного типа | |
tribe | получить информацию о редкости карт определенного племени | |
purity | получить информацию о редкости карт в диапазоне чистоты | |
mana | получить информацию о редкости карт в диапазоне маны | |
health | получить информацию о редкости карт в пределах диапазона здоровья | |
attack | получить информацию о редкости карт с диапазоном атаки | |
proto | ` | получить информацию о редкости карт с определенным идентификатором прототипа |
Параметры сортировки
proto , plain , shadow , gold , diamond
Формат ответа
{
"total": 380,
"page": 1,
"perPage": 1,
"records": [
{
"proto": 1,
"plain": 1325,
"shadow": 72,
"gold": 20,
"diamond": 3
}
]
}
Возвращает инвентарь пользователя с address , включая токены, теневые и централизованные карты.
Параметры
| Имя | Тип | Описание |
|---|---|---|
rarity | получить карты определенной редкости | |
quality | получить карты с определенным качеством | |
god | получить карты с конкретным богом | |
type | получить карты определенного типа | |
tribe | получить карты с определенным племенем | |
purity | получить карты в диапазоне чистоты | |
mana | получить карты в пределах маны | |
health | получить карты в пределах диапазона здоровья | |
attack | получить карты с диапазоном атаки | |
proto | получить карточки с определенным идентификатором прототипа |
Формат ответа
{
"total": 380,
"page": 1,
"perPage": 1,
"records": [
{
"proto": 1,
"purities": [
"100", "200", "300", "2999"
]
}
]
}
DeckStrings — удобный стандарт, позволяющий приложениям импортировать и экспортировать колоды. Следующие API предоставляют удобный интерфейс для основных операций со строками колоды.
Кодирует колоду в строку колоды.
Тело запроса
{
"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
]
}
Формат ответа
AQYBBhElYZgCogLLAgIMN0BQXV65AckBygH8AYkCmQLKAg==
Декодирует колоду из строки колоды.
Параметры
Формат ответа
{
"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
]
}
Перечисляет режимы игры с некоторыми свойствами.
Формат ответа
[
{
"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"
}
}
]
Показать результаты матча
Параметры
| Имя | Тип | Описание |
|---|---|---|
start_time | время начала матча (формат эпохи UNIX) | |
end_time | время окончания матча (формат эпохи UNIX) | |
player_won | user_id игрока | |
player_lost | user_id игрока | |
game_mode | идентификатор game_mode |
Важно : поле total_turns будет переименовано в total_rounds в более позднем обновлении. Мы продолжим его поддерживать, пока наше сообщество будет использовать новое имя поля.
Формат ответа
{
"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
}
]
}
Показывает ранг игрока в каждом режиме игры.
Параметры
| Имя | Тип | Описание |
|---|---|---|
user_id | Apollo ID пользователя | |
game_mode | Игровой режим ранга |
Формат ответа
{
"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
}
]
}
Показать свойства игроков.
Параметры
| Имя | Тип | Описание |
|---|---|---|
user_id | Apollo ID пользователя |
Формат ответа
{
"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"
}
]
}
Рассчитывает вероятность матча на основе рейтинга игроков (с использованием алгоритма рейтинга Эло)
Параметры
| Имя | Тип | Описание |
|---|---|---|
user_id | Apollo ID пользователя | |
opponent_id | Apollo ID противника | |
game_mode | игровой режим матча |
Формат ответа
0.6717130465747431
API-интерфейсы качества предоставляют данные о качествах и их визуальном составе, используемых общедоступными системами.
Показывает все определения активных классов качества и соответствующую информацию. В основном используется вспомогательными системами, такими как отношения имени и идентификатора или переопределение метаданных.
Формат ответа
[
{
"class_key": "quality",
"class_value": "2",
"class_properties": {
"name": "gold"
},
"class_type": "card",
"game_id": 1
},
...
]
Показывает указанное определение класса качества и соответствующую информацию. В основном используется вспомогательными системами, такими как отношения имени и идентификатора или переопределение метаданных.
Параметры
| Имя | Тип | Описание |
|---|---|---|
quality | Идентификатор качества |
Формат ответа
{
"class_key": "quality",
"class_value": "2",
"class_properties": {
"name": "gold"
},
"class_type": "card",
"game_id": 1
}
Показывает все данные графической композиции, необходимые для создания визуальных эффектов для указанных комбинаций прототипов и качеств для изображений NFT, используемых в Gods Unchained. В настоящее время поддерживает только искусство карт.
Параметры
| Имя | Тип | Описание | Пример |
|---|---|---|---|
pairs | Прототип и качество определяются с помощью разделителя @ | 1234@5 |
Формат ответа
[
{
"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"
]
}
}
]
