跳转至

Hive 区块链 API

Hive 区块链 API 是由 Hive 平台提供的 web 3.0 游戏 API，使用其 AppID 和 PlayerID。游戏玩家可以一次铸造多个代币，最多可达 200 个代币，游戏工作室可以获取每个用户的交易日志。还有许多其他适合 web 3 游戏的功能。使用 Hive 区块链 API，您可以高效地设置 web 3 游戏项目的开发、运营和管理。Hive 区块链 API 支持 Polygon 和 XPLA 区块链。

准备工作：获取 API 认证令牌

要调用 Hive 区块链 API，您需要在 API 头中附加认证令牌。获取 API 认证令牌的方法如下。

  1. 在 Hive 控制台注册后，进入应用中心 > 游戏列表 > 注册新游戏进行游戏注册。
  2. 在应用中心 > AppID 列表 > 注册新 AppID 创建 AppID。
    • 创建 AppID：网页登录 AppID
    • 选择用途：区块链
    • 选择要使用的 AppID：选择“自动生成的 AppID”或“自动生成的 AppID + 附加信息”
  3. 在 Hive 控制台 > 区块链 > 查看 API 认证密钥中选择游戏名称，并获取 ID 和认证密钥（SecretKey）。
  4. 在 auth-token API 请求体中放入 ID 和 SecretKey，然后调用 API。
  5. API 响应值中的data.accessToken是认证令牌。

NFT API

NFT发行

生成向特定地址(to)发行代币的交易。将要发行的NFT信息(mintMsg.tokenId、mintMsg.metadata等)放入数组中进行调用。每次API调用，XPLA最多可以向1个账户发行200个代币，Polygon最多可以发行50个代币。from必须是具有发行权限的账户。

Note

通过API发行的数字资产及其元数据(mintMsg.metadata)将注册到公共IPFS（星际文件系统）。

请求 URL

直播网址 https://bc-api.qpyou.cn/service/v1/nft/{contract}/mint
沙盒网址 https://sandbox-bc-api.qpyou.cn/service/v1/nft/{contract}/mint
HTTP 方法 POST
内容类型 application/json

路径参数

字段名 说明 类型 是否必填
contract NFT 合约地址 字符串 Y

头部参数

字段名 描述 类型 是否必填
Authorization 用于调用API的认证令牌 string Y
x-network 区块链网络{ploygon, xpla} string Y
x-appid 应用的唯一ID。可以在Hive控制台应用中心 > AppID列表中查看。 string Y

请求体

字段名 描述 类型 是否必需
playerId 玩家 ID string Y
from NFT 发行账户地址 string Y
to NFT 接收钱包地址 string Y
isSend 如果为 true，当 KMS 中存在钱包密钥时，将使用该密钥自动签署交易并将其发送到区块链。响应值为 txHash。如果为 false，则响应值为用户需要手动签署的交易数据 data.rawTx。 boolean Y
mintMsg 发行时所需的信息 array Y
mintMsg.tokenId NFT ID。由 NFT 发行者指定，不允许重复。
  • Polygon: 仅允许使用字符串和整数（0~2256-1）
  • XPLA: 仅允许使用字符串
 string Y
mintMsg.royaltyPercentage 版权费比例。每当 NFT 被销售或转售时，支付给 NFT 创建者或拥有权利的持有者的金额。总销售金额中设置支付为版权费的比例。此功能旨在为希望持续支持艺术家及其他 NFT 制作者的 NFT 市场提供支持。NFT 转移时，版权费不会自动支付给接收者，而是由市场确认 NFT 版权费并支付给接收者。这是适用于 OpenSea 的功能。
  • Polygon: 允许保留到小数点后两位。
  • XPLA: 不允许小数。
 number Y
mintMsg.metadata 元数据
  • 输入元数据时，请检查类型和 url(animationUrl, youtubeUrl, externalUrl) 格式。传输不准确的数据时，API 将无法正常工作。
  • 当元数据存储在 IPFS 时，将以可与 OpenSea 兼容的蛇形命名法存储（例如：animationUrl → animation_url）
 json Y
mintMsg.metadata.name NFT 名称 string Y
mintMsg.metadata.description NFT 描述 string N
mintMsg.metadata.image NFT 图片地址。用于上传到 IPFS 的外部可访问网站地址或公共 IPFS 地址。 string Y
mintMsg.metadata.animationUrl NFT 相关动画地址 string N
mintMsg.metadata.youtubeUrl YouTube 地址 string N
mintMsg.metadata.imageData NFT 图片信息 string N
mintMsg.metadata.externalUrl 外部链接地址 string N
mintMsg.metadata.backgroundColor OpenSea 中代币的背景色信息 string N
mintMsg.metadata.attributes 元数据属性信息。未在元数据中明确说明的附加信息。 json N
mintMsg.metadata.attributes.traitType 组成属性的项名。 string N
mintMsg.metadata.attributes.maxValue 属性最大值 number N
mintMsg.metadata.attributes.value 属性值。必须小于 mintMsg.metadata.attributes.maxValue。如果 mintMsg.metadata.attributes.displayType 为日期，则在值中输入 Unix 时间戳（秒）。 string 或 number N
mintMsg.metadata.attributes.displayType 属性显示类型。默认值为字符串类型。
  • number: 数字类型
  • boost_percentage: 以 % 信息在 OpenSea Boosts 中显示
  • boost_number: 在 OpenSea Boosts 中显示
  • date: 以日期格式显示（例如：2019年1月1日，星期二）
 string N
encoded 返回的交易的编码状态
  • true: 接收编码后的 Raw Transaction String data.rawTx。
  • false: 接收解码后的 JSON 结果 data.rawTx。
 boolean Y
callbackUrl 用于接收交易在区块链上记录成功/失败结果的地址 string Y

回复

字段名 描述 类型
code API 调用结果代码，0:成功 number
message 结果消息 string
data API 响应数据 json
data.rawTx 交易数据。仅在isSend为false时接收此值。 string 或 json
data.hashedTx 哈希后的data.rawTx。仅在满足以下所有条件时接收此值。 1. x-network为polygon 2. from为多签名钱包地址 3. isSend为false string
data.txhash 作为交易发送结果接收的交易哈希。仅在isSend为true时接收此值。 string
data.status 发送的交易状态。isSend为true时，如果交易成功发送，则接收PENDING。如果isSend为false，则表示在发送交易之前需要签名，接收WAITING值。 string
data.reqeustId 可用于识别API请求的唯一值 string

请求示例

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/nft/0x31a6854383c81daab14089cba0b9de1d42ecd65f/mint' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20y...' 
  -H 'Content-Type: application/json' 
  -d '{
  "playerId": 1324,
  "from": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0",
  "to": "0xA10078576Ca6f63dc6f78ff9a8ed8bd05B51f463",
  "isSend": true,
  "royaltyPercentage": 7.5,
  "mintMsg": [
    {
      "tokenId": "1",
      "metadata": {
        "name": "Arbiter'''s Robe",
        "description": "desc",
        "image": "https://image01.c2x.world/equip_92053030.gif",
        "animationUrl": "https://image01.c2x.world/equip_92053030.gif",
        "externalUrl": "https://dex.c2xnft.com/market?key=4423",
        "attributes": [
          {
            "traitType": "Category",
            "value": "Game",
          }
        ]
      }
    }
  ],
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

响应示例

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

NFT 查询

查询对应于令牌 ID(tokenId)的 NFT。

请求 URL

直播 URL https://bc-api.qpyou.cn/service/v1/nft/{contract}/tokens/{tokenId}
沙盒 URL https://sandbox-bc-api.qpyou.cn/service/v1/nft/{contract}/tokens/{tokenId}
HTTP 方法 POST
内容类型 application/json

路径参数

字段名 说明 类型 是否必填
contract NFT 合约地址 字符串 是
tokenId 令牌 ID 字符串 是

头部参数

字段名 说明 类型 是否必需
Authorization 用于调用API的认证令牌 string Y
x-network 区块链网络{ploygon, xpla} string Y
x-appid 应用的唯一ID。可以在Hive控制台应用中心 > AppID列表中查看。 string Y

回复

字段名 说明 类型
code API 调用结果代码，0:成功 number
message 结果消息 string
data API 响应数据 json
data.nftContract NFT 合约地址 string
data.tokenId 令牌 ID string
data.tokenUri 令牌的 IPFS 地址 string
data.gatewayUrl 令牌的 Gateway 地址 string
data.metadata 元数据 json
data.metadata.name NFT 名称 string
data.metadata.description NFT 描述 string
data.metadata.image NFT 图片地址。可以从外部访问的网站地址或公共 IPFS 地址。 string
data.metadata.animationUrl NFT 相关动画地址 string
data.metadata.youtubeUrl YouTube 地址 string
data.metadata.imageData NFT 图片信息 string
data.metadata.externalUrl 外部连接地址 string
data.metadata.backgroundColor OpenSea 中令牌的背景色信息 string
data.metadata.attributes 元数据属性信息。未在元数据中明确说明的附加信息。 json
data.metadata.attributes.traitType 组成 attributes 的项目名称。 string
data.metadata.attributes.maxValue trait 最大值 string
data.metadata.attributes.value trait 值。必须小于 data.metadata.attributes.maxValue。如果 data.metadata.attributes.displayType 为 date，则在 value 中输入 unix 时间戳（秒）。 string 或 number
data.metadata.attributes.displayType trait 显示类型。默认值为 string 类型。
  • number: Number 类型
  • boost_percentage: 以 % 信息显示在 OpenSea Boosts 中
    • boost_number: 显示在 OpenSea Boosts 中
  • date: 以日期格式显示（示例：2019年1月1日，星期二）
 string

请求示例

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/nft/0x31a6854383c81daab14089cba0b9de1d42ecd65f/tokens/1' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6...'

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "nftContract": "0x31a6854383c81daab14089cba0b9de1d42ecd65f",
    "tokenId": "5",
    "tokenUri": "ipfs://QmTPp6KFmBiDQyVL5b9fUGgp9tJtKrVEayRiXadDuBaPSD",
    "gatewayUrl": "https://test-bc-file.qpyou.cn/ipfs/QmTPp6KFmBiDQyVL5b9fUGgp9tJtKrVEayRiXadDuBaPSD",
    "metadata": {
      "name": "Arbiter's Robe",
      "description": "desc",
      "image": "https://image01.c2x.world/equip_92053030.gif",
      "animationUrl": "https://image01.c2x.world/equip_92053030.gif",
      "externalUrl": "https://dex.c2xnft.com/market?key=4423",
      "backgroundColor": "orange",
      "attributes": [
        {
          "traitType": "Category",
          "value": "Game",
          "displayType": "string"
        }
      ]
    }
  }
}

锁定 API

NFT锁定

NFT锁定是指将发行的NFT锁定，使其无法交易。当游戏用户铸造游戏物品以获得NFT后，如果希望在游戏中再次使用该物品，则会将NFT锁定以防止交易。所有者(owner)会生成锁定设置交易，使其持有的NFT(tokenId)无法使用。

请求 URL

直播 URL https://bc-api.qpyou.cn/service/v1/nft/contract/{contract}/lock
沙盒 URL https://sandbox-bc-api.qpyou.cn/ service/v1/nft/contract/{contract}/lock
HTTP 方法 POST
内容类型 application/json

路径参数

字段名 说明 类型 是否必填
contract NFT 合约地址 字符串 Y

头部参数

字段名 说明 类型 是否必需
Authorization 用于调用API的认证令牌 string Y
x-network 区块链网络{ploygon, xpla} string Y
x-appid 应用的唯一ID。可以在Hive控制台应用中心 > AppID列表中查看。 string Y

请求体

字段名 说明 类型 是否必需
playerId 玩家 ID string Y
from NFT 所有者钱包地址 string Y
isSend true时，如果KMS中有钱包密钥，则使用此密钥自动对交易进行签名并将其发送到区块链。响应值为 txHash。如果为 false，则响应值为用户需要手动签名的交易数据 data.rawTx。 boolean Y
lockContract 锁定合约地址 string Y
tokenId NFT ID string Y
encoded 返回的交易是否编码<i> true: 接收编码为 data.rawTx 的原始交易字符串。</i> false: 接收解码为 data.rawTx 的 JSON 结果。 boolean Y
callbackUrl 记录交易到区块链成功/失败后接收结果的地址 string Y

回复

字段名 描述 类型
code api 调用结果代码, 0:成功 number
message 结果消息 string
data API 响应数据 json
data.rawTx 交易数据。仅当isSend为false时接收此值。 string 或 json
data.hashedTx 哈希的data.rawTx。仅在满足以下所有条件时接收此值。 ,
1. x-network为polygon
2. from为多重签名钱包地址
3. isSend为false		 string
data.txhash 作为交易发送结果接收的交易哈希。仅当isSend为true时接收此值。 string
data.status 发送的交易状态。当isSend为true时，如果交易成功发送，则接收PENDING。如果isSend为false，则表示在发送交易之前需要签名，接收WAITING值。 string
data.reqeustId API 请求的唯一标识信息 string

请求示例

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/nft/contract/0xebd9144485089ebe248f8490984a60579407c262/lock' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20...' 
  -H 'Content-Type: application/json' 
  -d '{
  "playerId": 1324,
  "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
  "isSend": true,
  "lockContract": "0x572f47db51a98ae0d51324c2703d9d63ee3c9f03",
  "tokenId": "1",
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

响应示例

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

NFT解锁

创建一个解除所有者(owner)对NFT(tokenId)使用锁定设置的交易。

请求 URL

直播 URL https://bc-api.qpyou.cn/service/v1/lock/contract/{contract}/unlock
沙盒 URL https://sandbox-bc-api.qpyou.cn/service/v1/lock/contract/{contract}/unlock
HTTP 方法 POST
内容类型 application/json

路径参数

字段名 说明 类型 必填 여부
contract 锁定合约地址 string Y

头部参数

字段名 说明 类型 必填 여부
Authorization 用于调用API的认证令牌 string Y
x-network 区块链网络{ploygon, xpla} string Y
x-appid 应用唯一ID。可以在Hive控制台应用中心 > AppID列表中查看。 string Y

请求体

字段名 说明 类型 必填性
playerId 玩家 ID string Y
nftContract NFT 合约地址 string Y
from 锁定合约所有者钱包地址 string Y
isSend true时，如果KMS中有钱包密钥，则使用该密钥自动签署交易后将其发送到区块链。响应值为 txHash。如果为false，则响应值为用户需要手动签署的交易数据 data.rawTx。 boolean Y
tokenId NFT ID string Y
encoded 返回的交易是否编码
  • true: 接收编码为 data.rawTx 的原始交易字符串。
  • false: 接收解码为 JSON 的 data.rawTx 结果。
boolean Y
callbackUrl 记录交易到区块链的成功/失败结果的地址 string Y

响应

字段名 说明 类型
code API 调用结果代码，0:成功 number
message 结果消息 string
data API 响应数据 json
data.rawTx 交易数据。仅在isSend为false时接收此值。 string 或 json
data.hashedTx 哈希后的data.rawTx。仅在满足以下条件时接收此值：
1. x-network为polygon
2. from为多签钱包地址
3. isSend为false		 string
data.txhash 作为交易发送结果接收的交易哈希。仅在isSend为true时接收此值。 string
data.status 发送的交易状态。当isSend为true时，如果交易成功发送，则接收PENDING。如果isSend为false，则意味着在发送交易之前需要签名，因此接收WAITING值。 string
data.reqeustId 可识别API请求的唯一值 string

请求示例

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/lock/contract/0x572f47db51a98ae0d51324c2703d9d63ee3c9f03/unlock' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuaGl2ZXNka...' 
  -H 'Content-Type: application/json' 
  -d '{
  "playerId": 1324,
  "isSend": true,
  "nftContract": "0xebd9144485089ebe248f8490984a60579407c262",
  "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
  "tokenId": "2",
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

响应示例

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

转换 API

交换游戏货币和游戏代币

交换游戏代币和游戏货币。

  • to-token: 将游戏货币(gameCurrencyCode)兑换为游戏代币(gameToken)。
  • to-currency: 将游戏代币(gameToken)兑换为游戏货币(gameCurrencyCode)。

请求 URL

直播 URL https://bc-api.qpyou.cn/service/v1/convert/{type}
沙盒 URL https://sandbox-bc-api.qpyou.cn/service/v1/convert/{type}
HTTP 方法 POST
内容类型 application/json

路径参数

字段名 描述 类型 是否必需
type 转换类型
  • to-token: 将游戏货币(gameCurrencyCode)兑换为游戏代币(gameToken)。
  • to-currency: 将游戏代币(gameToken)兑换为游戏货币(gameCurrencyCode)。
 string Y

头部参数

字段名 说明 类型 是否必需
Authorization 用于调用API的认证令牌 string Y
x-network 区块链网络{ploygon, xpla} string Y
x-appid 应用的唯一ID。可以在Hive控制台应用中心 > AppID列表中查看。 string Y

请求体

字段名 描述 类型 是否必需
playerId 玩家 ID string Y
isSend 如果为true，当KMS中存在钱包密钥时，将使用此密钥自动签署交易并将其发送到区块链。响应值为txHash。如果为false，则响应值为用户需要手动签署的交易数据data.rawTx。 boolean Y
owner 用户的钱包地址 string Y
convertPool 转换池地址 string Y
gameTokenAmount 游戏代币数量 string Y
gameCurrencyCode 游戏货币代码 string Y
gameCurrencyAmount 游戏货币数量 string Y
encoded 返回的交易是否编码<i> true: 接收编码为data.rawTx的原始交易字符串。</i> false: 接收解码为JSON的data.rawTx结果。 boolean Y
callbackUrl 用于接收交易在区块链上记录成功/失败结果的地址 string Y

响应

字段名 说明 类型
code api 调用结果代码, 0:成功 number
message 结果消息 string
data API 响应数据 json
data.rawTx 交易数据。仅在isSend为false时接收此值。 string 或 json
data.hashedTx 哈希后的data.rawTx。仅在满足以下所有条件时接收此值。
1. x-network为polygon
2. from为多签名钱包地址
3. isSend为false		 string
data.txhash 作为交易发送结果接收的交易哈希。仅在isSend为true时接收此值。 string
data.status 发送的交易状态。isSend为true时，如果交易成功发送，则接收PENDING。如果isSend为false，则表示在发送交易之前需要签名，接收WAITING值。 string
data.reqeustId 可用于识别API请求的唯一值 string

请求示例

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/convert/to-token' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvb...' 
  -H 'Content-Type: application/json' 
  -d '{
  "playerId": 1324,
  "isSend": true,
  "owner": "0xA10078576Ca6f63dc6f78ff9a8ed8bd05B51f463",
  "convertPool": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
  "gameTokenAmount": "1",
  "gameCurrencyCode": "A39539HFTGOLD0001",
  "gameCurrencyAmount": "1000",
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

响应示例

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}
// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

转换池确认

转换池是游戏公司发行的游戏代币和游戏货币可以相互兑换的地方。查询转换池的剩余代币数量和游戏货币数量。

请求 URL

直播网址 https://bc-api.qpyou.cn/service/v1/convert/pool/{convertPool}
沙盒网址 https://sandbox-bc-api.qpyou.cn/service/v1/convert/pool/{convertPool}
HTTP 方法 GET
内容类型 application/json

路径参数

字段名 说明 类型 是否必填
convertPool 转换池地址 字符串 Y

头部参数

字段名 说明 类型 是否必需
Authorization 用于调用 API 的认证令牌 string Y
x-network 区块链网络{ploygon, xpla} string Y
x-appid 应用的唯一 ID。可以在 Hive 控制台应用中心 > AppID 列表中查看。 string Y

响应

字段名 说明 类型
code api 调用结果代码, 0:成功 number
message 结果消息 string
data API 响应数据 json

请求示例

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/convert/pool/0xdcd51770d06B54204abd8c30A25b4583D4cABa39' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvb...' 
  -d ''

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "convertPoolAmount": "1000000000",
    "gameCurrency": [
      {
        "goodsCode": "A39539HFTBRONZE0003",
        "goodsAmount": "10000000000"
      },
      {
        "goodsCode": "A39539HFTGOLD0001",
        "goodsAmount": "1000000000000"
      },
      {
        "goodsCode": "A39539HFTSILVER0002",
        "goodsAmount": "100000000000"
      }
    ]
  }
}

交易 API

Txhash 注册

当生成某个交易时（如铸造、转换、锁定 API 等），将收到的 requestId 和将该交易记录到区块链后收到的 txHash 注册。这是为了跟踪交易生成请求是否正常完成的程序。

请求 URL

直播网址 https://bc-api.qpyou.cn/service/v1/tx/hash
沙盒网址 https://sandbox-bc-api.qpyou.cn/service/v1/tx/hash
HTTP 方法 PATCH
内容类型 application/json

头部参数

字段名 描述 类型 是否必需
Authorization 用于调用 API 的认证令牌 string Y
x-network 区块链网络{ploygon, xpla} string Y
x-appid 应用唯一 ID。可以在 Hive 控制台应用中心 > AppID 列表中查看。 string Y

请求体

字段名 说明 类型 必填 여부
requestId API 请求的唯一标识符 string Y
txHash 交易哈希 string Y

回复

字段名 说明 类型
code api 调用结果代码, 0:成功 number
message 结果消息 string
data API 响应数据 json

请求示例

curl -X 'PATCH' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/tx/hash' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImN...' 
  -H 'Content-Type: application/json' 
  -d '{
  "requestId": "538d0ca4-9d8b-4b8c-ab02-c68bc1623ed3",
  "txHash": "0x99a93c8ba06865bd7054835d5f9abe57424289dca15ea61fe55a33a0651b058c"
}'

响应示例

{
  "code": 0,
  "message": "success"
}

查询交易列表

查询请求的交易列表。如果请求的交易在区块链上成功记录，则交易状态(transactions.txStatus)将更新为成功。

请求 URL

直播网址 https://bc-api.qpyou.cn/service/v1/tx
沙盒网址 https://sandbox-bc-api.qpyou.cn/service/v1/tx
HTTP 方法 GET
内容类型 application/json

头部参数

字段名 说明 类型 必填 여부
Authorization 调用 API 所需的认证令牌 string Y
x-network 区块链网络{ploygon, xpla} string Y
x-appid 应用的唯一 ID。可以在 Hive 控制台应用中心 > AppID 列表中查看。 string Y

查询参数

字段名 说明 类型 必需性
playerId 玩家 ID 字符串 否
startDate 交易生成日期搜索条件（开始日期，yyyy-mm-dd） 字符串 否
endDate 交易生成日期搜索条件（结束日期，yyyy-mm-dd） 字符串 否
page 当前页面编号 数字 否
limit 每个页面显示的交易数量 数字 否

响应

字段名 说明 类型
code API 调用结果代码, 0:成功 number
message 结果消息 string
data API 响应数据 json
transactions 交易信息 array
transactions.appid 应用中心注册的应用唯一识别码 string
transactions.playerId 玩家 ID number
transactions.address 创建交易的钱包地址 string
transactions.contract 请求交易的合约地址 string
transactions.requestId API 调用的唯一代码 string
transactions.requestParams API 调用参数 json
transactions.txType 交易类型 string
transactions.txStatus 交易状态 string
transactions.txHash 交易 Hash string
transactions.createdAt 交易创建日期 string
transactions.updatedAt 交易更新日期 string
meta 分页信息 json
meta.totalItems 总数量 number
meta.itemCount 显示数量 number
meta.itemsPerPage 每页显示的数量 number
meta.totalPages 总页数 number
meta.currentPage 当前页码 number

请求示例

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/tx?playerId=1324&startDate=2023-08-10&endDate=2023-08-10' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuaGl2...'

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "transactions": [
      {
        "appid": "com.com2us.hivesdk.c2xwallet.hivepc.kr.test",
        "address": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",
        "contract": "0xB3A634AAC8F04f1946C1c9Fc461055AC1Bdc4b34",
        "requestId": "1643105b-7669-4260-8679-ca967660df41",
        "requestParams": {
          "encoded": true,
          "tokenId": "1",
          "playerId": 1324,
          "callbackUrl": "https://withhive.com/",
          "nftContract": "0xa3fd0377a12b75ac2f70d5f69550332c96582b00",
          "lockContract": "0xB3A634AAC8F04f1946C1c9Fc461055AC1Bdc4b34",
          "lockContractOwner": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765"
        },
        "txType": "UNLOCK",
        "txStatus": "SUCCESS",
        "txHash": "0x78889d58613816c16389a7031634cc781fc725c3b3a88999524c92f67be89236",
        "createdAt": "2023-08-10T07:23:05.000Z",
        "updatedAt": "2023-08-10T07:25:00.000Z"
      }
    ],
    "meta": {
      "totalItems": 11,
      "itemCount": 1,
      "itemsPerPage": 1,
      "totalPages": 11,
      "currentPage": 1
    }
  }
}

令牌 API

查询代币余额

查询代币持有者账户地址(from)的当前代币余额。

请求 URL

直播网址 https://bc-api.qpyou.cn/service/v1/ft/{contract}/account/{from}/balance
沙盒网址 https://sandbox-bc-api.qpyou.cn/service/v1/ft/{contract}/account/{from}/balance
HTTP 方法 GET
内容类型 application/json

路径参数

字段名 说明 类型 是否必填
contract 代币合约地址 string Y
from 代币持有者账户 string Y

头部参数

字段名 说明 类型 必填 여부
Authorization 用于调用 API 的认证令牌 string Y
x-network 区块链网络{ploygon, xpla} string Y
x-appid 应用唯一 ID。可以在 Hive 控制台应用中心 > AppID 列表中查看。 string Y

响应

字段名 说明 类型
code api 调用结果代码, 0:成功 number
message 结果消息 string
data API 响应数据 json
data.value 代币余额 string
data.rawValue data.decimals未应用的代币余额 string
data.decimals 代币小数点最大位数 number
data.symbol 代币符号 string
data.symbolUri 代币符号图片 URI string

请求示例

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/ft/0x94853BdC9c6AdD50D7842D1A3117fab385457470/account/0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765/balance' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6I...'

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "value": "999998999",
    "symbol": "ST",
    "decimals": 18,
    "rawValue": "999998999000000000000000000"
  }
}

合同API

合同查询

从部署合约的账户地址（owner）查询部署的合约。

请求 URL

直播 URL https://bc-api.qpyou.cn/service/v1/contract/owner/{owner}
沙盒 URL https://sandbox-bc-api.qpyou.cn/service/v1/contract/owner/{owner}
HTTP 方法 GET
内容类型 application/json

路径参数

字段名 说明 类型 是否必需
owner 部署合约的账户地址 string Y

头部参数

字段名 说明 类型 是否必需
Authorization 调用 API 所需的认证令牌 string Y
x-network 区块链网络{ploygon, xpla} string Y
x-appid 应用的唯一 ID。可以在 Hive 控制台应用中心 > AppID 列表中查看。 string Y

查询参数

字段名 说明 类型 是否必填
contractType 合同类型 string N
page 当前页面编号 number N
limit 每个页面显示的合同数量 number N

回复

字段名 描述 类型
code api 调用结果代码, 0:成功 number
message 结果消息 string
data API 响应数据 json
data.contracts 合约信息 array
data.contracts.network 链信息 string
data.contracts.owner 部署合约的账户地址 string
data.contracts.address 合约地址 string
data.contracts.type 合约类型 string
data.contracts.name 合约名称 string
data.contracts.gameIndex 游戏索引 number
data.contracts.gameName 游戏名称 string
data.contracts.symbol 合约符号图片 URI string
data.contracts.symbolUri 合约符号图片 URI string
data.contracts.createdAt 合约注册日期 string
meta 分页信息 json
meta.totalItems 总数量 number
meta.itemCount 显示数量 number
meta.itemsPerPage 每页显示的数量 number
meta.totalPages 总页数 number
meta.currentPage 当前页码 number

请求示例

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/service/v1/contract/owner/0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765?contractType=FT&limit=1' 
  -H 'accept: application/json' 
  -H 'x-network: polygon' 
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydX...'

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "contracts": [
      {
        "gameIndex": 539,
        "gameName": "HIVE SDK(en)",
        "owner": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",
        "address": "0x05524fd875255ebd9c5f8871015ccc37b7fb20de",
        "name": "Fungible Token",
        "type": "FT",
        "symbol": "Fungible Token",
        "symbolUri": "https://sandbox-bc-file.qpyou.cn/ipfs/QmfJ9oT8Yb69bGr9bKozoYFYDQ4e1qPy31q4W3xsxfVw9L",
        "createdAt": "2023-08-10T01:09:59.000Z",
        "network": "polygon"
      }
    ],
    "meta": {
      "totalItems": 5,
      "itemCount": 1,
      "itemsPerPage": 1,
      "totalPages": 5,
      "currentPage": 1
    }
  }
}

Actions API

Actions API是基于XPLA区块链的API，提供与游戏集成的网页URL。用户可以通过Actions API执行游戏资产与游戏代币（XPLA）之间的Mint、Convert、Lock、Unlock、Burn功能。

Action 创建 API

用户在请求 Action 创建后，可以访问响应的网页（actionLink），并执行以下区块链功能。

  • 铸造: 将物品铸造成NFT的功能，为物品设置唯一的值作为NFT ID(tokenId)。一旦NFT被铸造，游戏内物品需要被禁用处理。
  • 转换: 交换游戏货币和XPLA或游戏代币的功能，需要在Hive控制台注册的游戏货币代码(gameCurrencyCode)。游戏货币和代币(XPLA)之间的交换完成后，需要更新游戏内游戏货币的数量。
  • 锁定: 锁定已发行的NFT并在游戏中再次使用的功能，需要在游戏内激活物品。(锁定后可以在游戏中使用的物品不得在游戏内被交换或移除，否则将无法解锁。)
  • 解锁：在游戏中使用的物品可以通过解锁NFT功能再次在用户钱包中使用，该功能需要物品的唯一值NFT ID(tokenId)，并且只能在锁定(Lock)NFT的账户和钱包中进行解锁(Unlock)。执行解锁后，游戏内物品需要被禁用处理。
  • 燃烧：销毁已发行的NFT，并在游戏中使用该物品的功能，燃烧后可以在游戏中进行物品交换和移除。

在执行Mint、Convert、Lock、Unlock、Burn功能后，通过callbackUrl传递结果。

Note

一次生成的 Action 有效期为 5 分钟，超过 5 分钟或该 Action 功能执行完成后将无法再使用。

请求 URL

实时 URL https://bc-api.qpyou.cn/xpla-platform/v1/actions
沙盒 URL https://sandbox-bc-api.qpyou.cn/xpla-platform/v1/actions
HTTP 方法 POST
内容类型 application/json

头部参数

字段名称 说明 类型 是否必需
Authorization 用于调用API的认证令牌 string Y

请求体

字段名 说明 类型 必需性
actionType 区分区块链功能 {MINT | CONVERT | LOCK | UNLOCK | BURN} string Y
info 区块链功能的选项信息 json Y
appid 区块链应用的唯一ID。可以在Hive控制台应用中心 > AppID列表中查看。 string Y
gameAppid 游戏应用的唯一ID。可以在Hive控制台应用中心 > AppID列表中查看。 string Y
playerId 玩家ID number Y
callbackUrl 在区块链上记录交易后，接收成功/失败结果的地址 string Y
language 语言代码 string Y
actionType对应的请求体信息中包含的各个元素信息
  • 薄荷
    字段名 说明 类型
    nftContract NFT 合约地址 string
    itemName 游戏内物品名称 string
    tokenId NFT 识别值（物品唯一值） string
    metadata 元数据（参见 NFT 发行 API 请求体） json
  • CONVERT
    字段名 说明 类型
    convertPool 转换池账户地址 string
    gameCurrencyCode 游戏货币代码 string
    userGameCurrencyAmount 用户要兑换的游戏货币数量 number
    minCurrencyAmount 可兑换的游戏货币的最小数量 number
    maxCurrencyAmount 可兑换的游戏货币的最大数量 number
    totalExchangedCurrencyAmount 用户截至目前已兑换的游戏货币数量 number
  • LOCK
    字段名 说明 类型
    nftContract NFT 合约地址 string
    lockContract 锁合约地址 string
  • UNLOCK
    字段名 说明 类型
    nftContract NFT 合约地址 string
    lockContract 锁合约地址 string
    tokenId NFT 识别值（物品唯一值） string
  • BURN
    字段名 说明 类型
    nftContract NFT 合约地址 string

回复

字段名 说明 类型
code API 调用结果代码，0:成功 number
message 结果消息 string
data API 响应数据 json
data.id Action 的唯一 ID string
data.actionType 区块链功能的区分 {MINT | CONVERT | LOCK | UNLOCK | BURN} string
data.info actionType 的响应信息 json
data.info.serviceFee 区块链功能使用的服务手续费 number
data.appid 区块链应用的唯一 ID。可以在 Hive 控制台应用中心 > AppID 列表中查看。 json
data.gameAppid 游戏应用的唯一 ID。可以在 Hive 控制台应用中心 > AppID 列表中查看。 string
data.playerId 玩家 ID number
data.language 语言代码 string
data.callbackUrl 在区块链上记录交易后，成功/失败结果将发送到的地址 string
data.company 公司唯一编号 number
data.gameindex 游戏索引 number
data.appindex Hive 应用中心分配的应用唯一编号 number
data.actionLink 执行区块链功能的网页链接 string
data.result Action 的处理结果 string
data.createdAt Action 注册日期 string
data.updatedAt Action 修改日期 string
actionType对应的响应数据中的各元素信息
  • MINT: 与请求体信息中的MINT相同
  • CONVERT
    字段名 说明 类型
    convertPool 转换池账户地址 string
    gameCurrencyCode 游戏货币代码 string
    userGameCurrencyAmount 用户要兑换的游戏货币数量 number
    minCurrencyAmount 可兑换的游戏货币的最小数量 number
    maxCurrencyAmount 可兑换的游戏货币的最大数量 number
    totalExchangedCurrencyAmount 用户截至目前已兑换的游戏货币数量 number
    currencyName 游戏货币名称 string
    currencyLogoUrl 游戏货币logo URL string
    assetType 代币类型 {token | coin} string
    ftContract 游戏代币地址 string
    tokenName 游戏代币名称 string
    tokenLogoUrl 游戏代币logo URL string
  • LOCK: 与请求体信息中的LOCK相同
  • UNLOCK: 与请求体信息中的UNLOCK相同
  • BURN: 与请求体信息中的BURN相同

请求示例

    curl -X 'POST' \
  'https://sandbox-bc-api.qpyou.cn/xpla-platform/v1/actions' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6NiwiaWQiOiIvVWpXN....' \
  -H 'Content-Type: application/json' \
  -d '{

// MINT--------------------------------------------------------------------------------------------
  "actionType": "MINT",
  "info": {
    "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",
    "itemName": "아비터의 로브",
    "tokenId": "A1234",
    "metadata": {
      "name": "Arbiter'\''s Robe",
      "description": "A robe worn by the arbiter of the world.",
      "image": "https://image01.c2x.world/equip_92053030.gif",
      "animationUrl": "https://image01.c2x.world/equip_92053030.gif",
      "youtubeUrl": "https://www.youtube.com/watch?v=gmdexWtuzAE&pp=ygUEeHBsYQ%3D%3D",
      "externalUrl": "https://dex.c2xnft.com/market?key=4423",
      "attributes": [
        {
          "traitType": "Category",
          "value": "Game"
        }
      ]
    }
  },

// CONVERT--------------------------------------------------------------------------------------------

   "actionType": "CONVERT",
   "info": {
      "convertPool": "xpla1zaztjwm0tequ8rf70vk6f5qsen55zsy2445j94",
      "gameCurrencyCode": "J94597FISHGOLD0001",

      "userGameCurrencyAmount": 1000,
      "minCurrencyAmount": 100,
      "maxCurrencyAmount": 100000,
      "totalExchangedCurrencyAmount": 100
   },

// LOCK--------------------------------------------------------------------------------------------

   "actionType": "lock",
   "info": {
     "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s", 
     "lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp"
   },

// UNLOCK--------------------------------------------------------------------------------------------

   "actionType": "unlock",
    "info": {
     "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s", 
     "tokenId": "283ed-8b23-e4a", 
     "lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp"
   },

// BURN--------------------------------------------------------------------------------------------

   "actionType": "burn",
   "info": {"nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s"},

// -------------------------------------------------------------------------------------------------
  "appid": "com.gcp.stepbystep.pcweb.blockchain",
  "gameAppid": "com.gcp.stepbystep.pcweb.blockchain",
  "playerId": 1,
  "callbackUrl": "https://sandbox-bc-api.qpyou.cn/sample/v1/backend/callback",
  "language": "ko"
}'
</pre>

<h3>Response Sample</h3>
<pre class="lang:json decode:true">
    // MINT

    {
         "code": 0,
         "message": "success",
         "data": {
    // MINT--------------------------------------------------------------------------------------------
                "actionType": "MINT",
                "info": {
                 "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",
                 "itemName": "아비터의 로브",
                 "tokenId": "A1234",
                 "metadata": {
                        "name": "Arbiter's Robe",
                        "description": "A robe worn by the arbiter of the world.",
                        "image": "https://image01.c2x.world/equip_92053030.gif",
                        "animationUrl": "https://image01.c2x.world/equip_92053030.gif",
                        "youtubeUrl": "https://www.youtube.com/watch?v=gmdexWtuzAE&pp=ygUEeHBsYQ%3D%3D",
                        "externalUrl": "https://dex.c2xnft.com/market?key=4423",
                        "attributes": [
                             {
                                    "traitType": "Category",
                                    "value": "Game"
                             }
                        ]
                 },
                 "serviceFee": 0.2
                },
                "id": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
                "actionLink": "https://sandbox-xpla-platform.withhive.com/games/mint?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=b6d2ca1b-b43a-4129-bf54-9a189e3aa664&lang=ko",
    // CONVERT--------------------------------------------------------------------------------------------
                "actionType": "CONVERT",
                "info": {
                 "convertPool": "xpla1zaztjwm0tequ8rf70vk6f5qsen55zsy2445j94",
                 "gameCurrencyCode": "J94597FISHGOLD0001",

                "userGameCurrencyAmount": 1000,
                 "minCurrencyAmount": 100,
                 "maxCurrencyAmount": 100000,
                 "totalExchangedCurrencyAmount": 100,
                 "currencyName": "GOLD",
                 "currencyLogoUrl": "https://sandbox-bc-file.qpyou.cn/ipfs/QmdqBYarCoFpPzkG9tgQJoe9NqcLuP9rBnVWn8tRo51uTR",
                 "assetType": "token",
                 "ftContract": "xpla1dhwmvf876g4fwhg28x6ep7jmulrreu8ztrhfk6wmp83f9y3xjstsz78pzy",
                 "tokenName": "FISH",
                 "tokenLogoUrl": "https://sandbox-bc-file.qpyou.cn/ipfs/QmbLRYXgk57KeanzmKuxjv2TtvXwt4DrFoFFYTH1MPkCgU",
                 "serviceFee": 10
                },
                "id": "81c705ac-2e03-4fa7-bb10-feb533b5e754",
                "actionLink": "https://sandbox-xpla-platform.withhive.com/games/convert?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=81c705ac-2e03-4fa7-bb10-feb533b5e754&lang=ko",
    // LOCK--------------------------------------------------------------------------------------------
                "actionType": "LOCK",
                "info": {
                    "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",
                    "lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp",
                    "serviceFee": 0.1
                },
                "id": "20cf84b8-af60-4ad4-9251-babf1a6778c3",
                "actionLink": "https://sandbox-xpla-platform.withhive.com/games/convert?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=81c705ac-2e03-4fa7-bb10-feb533b5e754&lang=ko",
    // UNLOCK--------------------------------------------------------------------------------------------
                "actionType": "UNLOCK",
                "info": {
                    "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",
                    "tokenId": "283ed-8b23-e4a",
                    "lockContract": "xpla139lxe8d6ml2hqtkdz9nnw2u47pqyw9spcgqgd6apmyt2wnqc4nwqecf0xp",
                    "serviceFee": 0.1
                },
                "id": "8e701ff2-d37b-473a-bdd7-886e40e18d7c",
                "actionLink": "https://sandbox-xpla-platform.withhive.com/games/unlock?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=b6d2ca1b-b43a-4129-bf54-9a189e3aa664&lang=ko",
    // BURN--------------------------------------------------------------------------------------------
                "actionType": "BURN",
                "info": {
                    "nftContract": "xpla1wtv5dwu90pe4jqfckyhr6cq3hdr7rrjdta7ntsczawe8ffupsq3s25sg0s",
                    "serviceFee": 0.1
                },
                "id": "8fb0c236-71a3-4b40-9ba0-d558f351757a",
                "actionLink": "https://sandbox-xpla-platform.withhive.com/games/burn?access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&action-id=b6d2ca1b-b43a-4129-bf54-9a189e3aa664&lang=ko",
    // --------------------------------------------------------------------------------------------------
                "appid": "com.gcp.stepbystep.pcweb.blockchain",
                "gameAppid": "com.gcp.stepbystep.android.google",
                "pid": 1,
                "language": "ko",
                "callbackUrl": "https://sandbox-bc-api.qpyou.cn/sample/v1/backend/callback",
                "company": 3,
                "gameindex": 597,
                "appindex": 21001,
                "result": null,
                "createdAt": "2024-08-05T08:33:15.448Z",
                "updatedAt": "2024-08-05T08:33:15.448Z"
         }
    }

callbackUrl API

用户在使用 Action 功能（MINT, LOCK, UNLOCK, BURN, CONVERT）后请求 callbackUrl，可以接收到 Action 执行结果。

请求 URL

URL 自定义
HTTP Method POST
Content-Type application/json

头部参数

字段名 说明 类型 是否必填
Authorization callbackUrl中存在token查询参数: Bearer ${token} 查询参数缺失时可省略 字符串 N
X-Request-ID 请求时发放的ID 字符串 Y
User-Agent XplaPlatform/1.0 字符串 Y

请求体 (使用 MINT, LOCK, UNLOCK, BURN 时的 callbackUrl)

  • 传递关于Mint、Lock、Unlock、Burn操作的状态(result.actionStatus)和游戏中需要更新的物品可用性(result.isAvailableItem)。
  • 需要更新用户(data.user.playerId)持有的物品(data.nft.tokenId)。
字段名 说明 类型 必需性
result Action 执行结果 json Y
result.actionStatus 动作状态 {SUCCESS, FAILRUE, EXPIRATION, CANCELLATION} string Y
result.actionType Action 的类型 MINT, BURN, LOCK, UNLOCK json Y
result.txHash 交易哈希 string Y
result.isAvailableItem 游戏内物品使用可能性 boolean Y
data Action 执行内容 json Y
data.user 执行 Action 使用的用户信息 json Y
data.user.playerId 玩家 ID string Y
data.user.wallet 玩家钱包地址 string Y
data.nft 执行 Action 使用的 nft 信息 json Y
data.nft.nftContract NFT 合约地址 string Y
data.nft.tokenId NFT ID string Y
data.serviceFeeAmount 用户支付的服务费用 (XPLA) number Y

请求体 (使用 CONVERT 时的 callbackUrl)

  • 传递关于转换执行的动作状态(result.actionStatus)和游戏中需要更新的游戏货币数量(result.amount)。
  • 需要更新用户持有的对应于游戏货币代码(result.amount.currencyCode)的游戏货币数量(result.amount)。
字段名 说明 类型 必需性
result Action 执行结果 json Y
result.actionStatus 动作状态 {SUCCESS, FAILRUE, EXPIRATION, CANCELLATION} string Y
result.actionType Action 的类型 CONVERT json Y
result.txHash 交易哈希 string Y
result.amount 转换结果数量信息 json Y
result.amount.changeUserAmount 用户的游戏货币变更数量 (+, -) number Y
result.amount.changePoolAmount 转换池的游戏货币变更数量 (+, -) number Y
result.amount.currencyCode 游戏货币代码 string Y
data Action 执行内容 json Y
data.user 执行 Action 使用的用户信息 json Y
data.user.playerId 玩家 ID string Y
data.user.wallet 玩家钱包地址 string Y
data.convert 执行 Action 使用的转换信息 json Y
data.convert.type 转换类型 (CONVERT_TO_TOKEN, CONVERT_TO_CURRENCY) string Y
data.convert.convertPool 转换池地址 string Y
data.convert.ftContract 代币地址 (或 XPLA) string Y
data.convert.currencyCode 游戏货币代码 string Y
data.in 流入转换池的数量信息 json Y
data.in.amount 用户请求的代币（货币）数量 number Y
data.in.txFeeAmount 用户支付的交易手续费 number Y
data.in.txFeeType XPLA 或 CURRENCY string Y
data.out 流出转换池的数量信息 json Y
data.out.amout 用户将获得的代币（货币）数量 number Y
data.serviceFeeAmount 用户支付的服务手续费 (XPLA) number Y

XPLA 平台 API

XPLA Platform API是基于XPLA区块链的API，提供与游戏关联的网页URL。用户可以通过XPLA Platform API执行游戏货币与游戏代币（XPLA）之间的铸造、转换、锁定、解锁和销毁功能。

用户可以在请求生成 XPLA Web Link 后，访问收到的网页（actionLink），并执行如下区块链功能。

  • Mint: 将物品铸造成NFT的功能，为物品设置唯一值NFT ID(tokenId)，一旦NFT被铸造，游戏内物品需要被禁用处理
  • Convert: 在游戏货币与XPLA或游戏代币之间进行交换的功能，需要在Hive控制台注册的游戏货币代码(gameCurrencyCode)，游戏货币与代币(XPLA)之间的交换完成后，需要更新游戏内游戏货币的数量
  • Lock: 锁定已发行的NFT并在游戏中再次使用的功能，需要在游戏内激活物品，（锁定后在游戏中可用的物品不得在游戏内被交换或移除，以便能够解锁）
  • Unlock: 使在游戏中使用的物品能够再次在用户钱包中使用的功能，需要物品的唯一值NFT ID(tokenId)，并且仅能在锁定(Lock)该NFT的账户和钱包中解锁(Unlock)，一旦解锁，游戏内物品需要被禁用处理
  • Burn: 消灭已发行的NFT并在游戏中使用该物品的功能，Burn后可以在游戏中交换和移除物品

在执行 Mint、Convert、Lock、Unlock、Burn 功能后，通过 callbackUrl 传递结果。

Note

一旦生成的 XPLA Web Link 在 5 分钟内有效，5 分钟后或该功能执行完成后将无法再使用。

响应

字段名 描述 类型
code API 调用结果代码，0:成功 number
message 结果消息 string
data API 响应数据 json
data.id XPLA Web Link 的唯一ID string
data.actionType 区块链功能的区分 string
data.info 按 actionType 的响应信息 json
data.info.serviceFee 使用区块链功能的服务手续费费用 number
data.appid 区块链应用的唯一 ID。 Hive 控制台应用中心 > AppID 列表 中可以查看。 json
data.gameAppid 游戏应用的唯一 ID。 Hive 控制台应用中心 > AppID 列表 中可以查看。 string
data.playerId 玩家 ID number
data.language 语言代码 string
data.callbackUrl 记录交易到区块链后接收成功/失败结果的地址 string
data.company 公司唯一编号 number
data.gameindex 游戏索引 number
data.appindex Hive 应用中心分配的应用唯一编号 number
data.actionLink 执行区块链功能的网页链接 string
data.result XPLA Web Link 的处理结果 string
data.createdAt XPLA Web Link 创建日期 string
data.updatedAt XPLA Web Link 修改日期 string

CallbackUrl API

用户在使用 Action 功能（MINT, LOCK, UNLOCK, BURN, CONVERT）后请求 callbackUrl，可以接收到 Action 执行结果。

头部参数

字段名 说明 类型 必填 여부
Authorization callbackUrl中存在token查询参数: Bearer ${token}
如果没有查询参数: 省略		 string N
X-Request-ID 在生成XPLA Web Link请求时获得的ID string Y
User-Agent XplaPlatform/1.0 string Y

请求体 (使用 MINT, LOCK, UNLOCK, BURN 时 CallbackUrl)

传递关于执行Mint、Lock、Unlock、Burn的动作状态(result.actionStatus)和游戏内需要更新的物品使用可用性(result.isAvailableItem)。

用户(data.user.playerId)持有的物品(data.nft.tokenId)需要更新。

字段名 说明 类型 必填
result 在 XPLA Web Link 交换后处理的结果 json 是
result.actionStatus 动作状态 string 是
result.actionType XPLA Web Link 类型 MINT, BURN, LOCK, UNLOCK json 是
result.txHash 交易哈希 string 是
result.isAvailableItem 游戏内物品使用可用性 boolean 是
data 在 XPLA Web Link 处理的内容 json 是
data.user 在 XPLA Web Link 处理的用户信息 json 是
data.user.playerId 玩家 ID string 是
data.user.wallet 玩家钱包地址 string 是
data.nft 在 XPLA Web Link 处理的 nft 信息 json 是
data.nft.nftContract NFT 合约地址 string 是
data.nft.tokenId NFT ID string 是
data.serviceFeeAmount 用户支付的服务费用 (XPLA) number 是

请求体 (使用 CONVERT 时的 CallbackUrl)

传递关于转换执行的动作状态(result.actionStatus)和游戏中需要更新的游戏货币数量(result.amount)。

需要更新用户持有的游戏货币数量(result.amount)，对应于游戏货币代码(result.amount.currencyCode)。

字段名 描述 类型 必填
result 在 XPLA Web Link 交换后处理的结果 json Y
result.actionStatus 动作状态 string Y
result.actionType XPLA Web Link 类型 CONVERT json Y
result.txHash 交易哈希 string Y
result.amount 转换结果数量信息 json Y
result.amount.changeUserAmount 用户的游戏货币变更数量 (+, -) number Y
result.amount.changePoolAmount 转换池的游戏货币变更数量 (+, -) number Y
result.amount.currencyCode 游戏货币代码 string Y
data 在 XPLA Web Link 处理的内容 json Y
data.user 在 XPLA Web Link 处理的用户信息 json Y
data.user.playerId 玩家 ID string Y
data.user.wallet 玩家钱包地址 string Y
data.convert 在 XPLA Web Link 处理的转换信息 json Y
data.convert.type 转换类型 (CONVERT_TO_TOKEN, CONVERT_TO_CURRENCY) string Y
data.convert.convertPool 转换池地址 string Y
data.convert.ftContract 代币地址 (或 XPLA) string Y
data.convert.currencyCode 游戏货币代码 string Y
data.in 流入转换池的数量信息 json Y
data.in.amount 用户请求的代币（货币）数量 number Y
data.in.txFeeAmount 用户支付的交易手续费 number Y
data.in.txFeeType XPLA 或 CURRENCY string Y
data.out 从转换池流出的数量信息 json Y
data.out.amout 用户将收到的代币（货币）数量 number Y
data.serviceFeeAmount 用户支付的服务手续费 (XPLA) number Y