gods unchained api

诸神无链 API

Gods Unchained（以太坊区块链上的集换式卡牌游戏）的公共开发者 API 文档。

此版本的 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/s)。这在未来可能会改变。

类型

一般类型：

类型	描述
	url 编码的字符串。
	一个十进制数。
	是true false

自定义API类型：

类型	描述
	十六进制以太坊地址，不区分大小写。
	具体数量1000 ，范围1000-2000 ，最小1000-或最大-2000 。

各种api中枚举类型的有效选项如下：

类型	选项
	光、死亡、自然、战争、魔法、欺骗
	稀有、史诗、传奇、闪亮
	常见、稀有、史诗、传奇、神话
	生物、法术、武器
	下界、以太、亚特兰蒂斯、维京人、奥林匹亚、阿努比安、亚马逊
	普通、阴影、金色、钻石
	满、卡

概念

Gods Unchained 中有几种“类型”的卡牌：

• 令牌：已“激活”的完整 ERC721 令牌卡。
• 型号：最常见的卡类型：锁定，显示在前端，但尚未转换为 ERC721 代币以节省 Gas。
• 中心化：无法在区块链上交易的卡（核心集的一部分或不可交易的促销卡）。

其中一些端点返回上述内容的组合，而另一些则不返回：这是由各个端点记录的。一般来说，默认是只返回可以成为ERC721代币的卡（即Token卡和Model卡）。

原型卡或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}	从牌组字符串解码牌组

核心API

获取/卡/{id}

参数

姓名	类型	描述
ID		卡的 ERC721 id

返回带有id和适当元数据的令牌卡。目前符合通用和 Apollo 元数据规范。

获取/卡

返回令牌和模型卡的列表。

参数

姓名	类型	描述
user		获取特定地址拥有的卡
rarity		获得特定稀有度的卡牌
quality		获得特定品质的卡牌
god		获得特定神灵的卡片
type		获取特定类型的卡片
tribe		获得特定部落的卡牌
purity		获得特定纯度的卡片
mana		获得具有特定法力的卡牌
health		获得具有特定健康状况的卡片
attack		获得具有特定攻击的卡牌
proto		获取具有特定原型 ID 的卡片

响应格式

 {
    "total": 1000,
    "page": 1,
    "perPage": 1,
    "records": [
        {
            "id": {
                "Int64": 0,
                "Valid": false,
            }
            "proto": 319,
            "purity": 59,
            "user": "0xCb3562Dd15807e2BCF35092B1e873971AF0a51da"
        }
    ]
}

获取 /proto/{id}

返回 id 为id原型卡。

参数

姓名	类型	描述
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"
        }
    ]
}

GET /工厂/{地址}

返回位于地址address的包工厂。

参数

姓名	类型	描述
address		工厂地址

响应格式

 {
    "address":"0x0777f76d195795268388789343068e4fcd286919",
    "type":"rare"
}

获取/工厂

返回包装工厂列表。

参数

姓名	类型	描述
type		包装类型

响应格式

 {
    "total": 4,
    "page": 1,
    "perPage: 1,
    "records": [
        {
            "address":"0x0777f76d195795268388789343068e4fcd286919",
            "type":"rare"
        }
    ]
}

GET /工厂/{地址}/购买/{id}

从address的包装工厂返回购买id 。

参数

姓名	类型	描述
address		工厂地址
id		工厂内采购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"
        }
    ]
}

GET /factory/{地址}/purchase/{id}/pack/{index}

返回带有索引index的包，该包的索引来自address为address的包工厂的购买id 。

参数

姓名	类型	描述
address		包装工厂地址
id		购买的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}

返回基于 id 为id卡片原型的图像。要获取卡片形式的图像，请使用format和quality参数。

参数

姓名	类型	描述
format		图像的呈现格式
h		图像大小将调整到的高度
w		图像大小调整后的宽度
quality		卡的质量

GET /用户/{地址}

获取一个用户。

参数

姓名	类型	描述
address		用户的以太坊地址

响应格式

 {
    "username": "ender",
    "address": "0xC257274276a4E539741Ca11b590B9447B26A8051",
    "nonce": 0
}

辅助 API

为了帮助我们的生态系统构建更有效的应用程序，我们还提供了一些有用的 API 端点。这些端点可能会在未来的版本中被弃用，因为它们可以由现有端点组合而成，但在开发新生的以 GU 为中心的应用程序期间提供了方便的接口。

获取/排名

返回具有最多满足特定条件的卡的用户的有序列表。

参数

姓名	类型	描述
rarity		获得具有特定稀有度的卡牌等级
quality		获得具有特定品质的卡牌等级
god		获得特定神的卡牌等级
type		获取特定类型卡牌的等级
tribe		获取特定部落的卡牌等级
purity		获得具有最小纯度界限的卡牌等级
mana		获得具有特定法力的卡牌等级
health		获得具有特定生命值的卡牌排名
attack		获得具有特定攻击的卡牌排名
proto		获取具有特定原型 ID 的卡牌排名

响应格式

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

获取/稀有度

返回有关原型的稀有度信息。

参数

姓名	类型	描述
user		获取有关特定地址拥有的卡的稀有度信息
rarity		获取有关具有特定稀有度的卡牌的稀有度信息
quality		获取特定品质卡牌的稀有度信息
god		获取有关特定神的卡牌的稀有度信息
type		获取特定类型卡牌的稀有度信息
tribe		获取特定部落卡牌的稀有度信息
purity		获取纯度范围内卡牌的稀有度信息
mana		获取某个法力范围内卡牌的稀有度信息
health		获取健康范围内卡牌的稀有度信息
attack		获取有关具有攻击范围的卡牌的稀有信息
proto	`	获取具有特定原型 ID 的卡牌的稀有度信息

排序选项

proto 、 plain 、 shadow 、 gold 、 diamond

响应格式

 {
    "total": 380,
    "page": 1,
    "perPage": 1,
    "records": [
        {
            "proto": 1,
            "plain": 1325,
            "shadow": 72,
            "gold": 20,
            "diamond": 3
        }
    ]
}

GET /用户/{地址}/库存

返回地址为address的用户的库存，包括代币卡、影子卡和中心化卡。

参数

姓名	类型	描述
rarity		获得特定稀有度的卡牌
quality		获得特定品质的卡牌
god		获得特定神灵的卡片
type		获取特定类型的卡片
tribe		获得特定部落的卡牌
purity		获得纯度范围内的卡片
mana		获得法力范围内的牌
health		获得健康范围内的卡片
attack		获得具有攻击范围的卡牌
proto		获取具有特定原型 ID 的卡片

响应格式

 {
    "total": 380,
    "page": 1,
    "perPage": 1,
    "records": [
        {
            "proto": 1,
            "purities": [
                "100", "200", "300", "2999"
            ]
        }
    ]
}

DeckString API

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		游戏模式标识符

重要提示：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"
  }
 ]
}

获取/预测

根据玩家的评分计算匹配的概率（使用 Elo 评分算法）

参数

姓名	类型	描述
user_id		用户的 Apollo ID
opponent_id		对手的Apollo ID
game_mode		比赛的比赛模式

响应格式

 0.6717130465747431

优质 API

质量 API 提供有关公共系统使用的质量及其视觉合成的数据。

获取/质量

显示所有有效的质量等级定义和相关信息。主要由支持系统使用，例如名称和 ID 关系或元数据覆盖。

响应格式

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

获取/质量/{质量}

显示指定的质量等级定义和相关信息。主要由支持系统使用，例如名称和 ID 关系或元数据覆盖。

参数

姓名	类型	描述
quality		质量ID

响应格式

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

获取/组合

显示为 Gods Unchained 中使用的 NFT 艺术的指定原型和质量组合生成视觉效果所需的所有图形合成数据。目前仅支持卡片艺术。

参数

姓名	类型	描述	例子
pairs		使用@分隔符定义的 Proto 和 Quality	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"
   ]
  }
 }
]