跳轉至

Hive blockchain api

Hive 區塊鏈 API 是由 Hive 平台提供的網絡 3.0 遊戲 API，使用其 AppID 和 PlayerID。遊戲玩家可以一次鑄造多達 200 個代幣，遊戲工作室可以獲得每個用戶的交易記錄。還有許多其他適合網絡 3 遊戲的功能。使用 Hive 區塊鏈 API，您可以高效地設置網絡 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
沙盒 URL 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 字串 Y
from 發行 NFT 的帳戶地址 字串 Y
to 接收 NFT 的錢包地址 字串 Y
isSend 如果為 true，當 KMS 中有錢包金鑰時，將使用此金鑰自動簽署交易並將其發送到區塊鏈。回應值為 txHash。如果為 false，則回應值為用戶必須手動簽署的交易數據 data.rawTx。 布林值 Y
mintMsg 發行時所需的資訊 陣列 Y
mintMsg.tokenId NFT ID。由 NFT 發行者指定，不允許重複。
  • Polygon: 僅可使用字串和整數（0~2256-1）
  • XPLA: 僅可使用字串
 字串 Y
mintMsg.royaltyPercentage 版稅比例。每當 NFT 被銷售或轉售時，將支付給 NFT 創作者或權利持有者的金額。總銷售金額中設置的版稅支付比例。這是為了支持藝術家和其他 NFT 創作者的持續資金。NFT 轉移時不會自動支付版稅給接收者，而是由市場確認 NFT 版稅並支付給接收者。這是適用於 OpenSea 的功能。
  • Polygon: 允許到小數點後兩位。
  • XPLA: 不允許小數。
 數字 Y
mintMsg.metadata 元數據
  • 輸入元數據時，請確認類型及 url（animationUrl, youtubeUrl, externalUrl）格式。傳送不正確的數據時，API 將無法正常運作。
  • 當元數據存儲在 IPFS 時，將以可與 OpenSea 連接的蛇形命名法保存（例如：animationUrl → animation_url）
 json Y
mintMsg.metadata.name NFT 名稱 字串 Y
mintMsg.metadata.description NFT 說明 字串 N
mintMsg.metadata.image NFT 圖像地址。可供上傳到 IPFS 的外部可訪問網站地址或公共 IPFS 地址。 字串 Y
mintMsg.metadata.animationUrl NFT 相關動畫地址 字串 N
mintMsg.metadata.youtubeUrl YouTube 地址 字串 N
mintMsg.metadata.imageData NFT 圖像資訊 字串 N
mintMsg.metadata.externalUrl 外部連結地址 字串 N
mintMsg.metadata.backgroundColor OpenSea 中代幣的背景顏色資訊 字串 N
mintMsg.metadata.attributes 元數據屬性資訊。未在元數據中明示的附加資訊。 json N
mintMsg.metadata.attributes.traitType 組成屬性的項目名稱。 字串 N
mintMsg.metadata.attributes.maxValue 屬性最大值 數字 N
mintMsg.metadata.attributes.value 屬性值。必須小於 mintMsg.metadata.attributes.maxValue。如果 mintMsg.metadata.attributes.displayType 為日期，則在值中輸入 Unix 時間戳（秒）。 字串或數字 N
mintMsg.metadata.attributes.displayType 屬性顯示類型。預設為字串類型。
  • 數字: 數字類型
  • boost_percentage: 以 % 資訊顯示於 OpenSea Boosts
  • boost_number: 顯示於 OpenSea Boosts
  • 日期: 以日期格式顯示（例如：2019年1月1日，星期二）
 字串 N
encoded 返回的交易是否編碼
  • true: 獲取編碼為 data.rawTx 的原始交易字串。
  • false: 獲取解碼為 data.rawTx 的 JSON 結果。
 布林值 Y
callbackUrl 用於接收交易是否成功/失敗記錄到區塊鏈的結果地址 字串 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 合約地址 字串 Y
tokenId 代幣 ID 字串 Y

標頭參數

欄位名稱 說明 類型 是否必填
Authorization 用於調用 API 的認證令牌 字串 是
x-network 區塊鏈網絡{ploygon, xpla} 字串 是
x-appid 應用程式唯一 ID。可以在 Hive 控制台應用中心 > AppID 列表中查看。 字串 是

回應

欄位名稱 說明 類型
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: 數字類型
  • 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

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

路徑參數

欄位名稱 說明 類型 必填與否
contract NFT 合約地址 字串 Y

標頭參數

欄位名稱 說明 類型 必填與否
Authorization 用於呼叫 API 的認證令牌 字串 是
x-network 區塊鏈網絡{ploygon, xpla} 字串 是
x-appid 應用程序唯一 ID。可以在 Hive 控制台應用中心 > AppID 列表中查看。 字串 是

請求主體

欄位名稱 說明 類型 必填與否
playerId 玩家 ID 字串 是
from NFT 擁有者錢包地址 字串 是
isSend true時，當KMS中有錢包金鑰時，將自動使用此金鑰對交易進行簽名並發送到區塊鏈。回應值為 txHash。false時，將回應用戶需要手動簽名的交易數據 data.rawTx。 布林值 是
lockContract 鎖定合約地址 字串 是
tokenId NFT ID 字串 是
encoded 返回的交易是否進行編碼<i> true: 接收編碼為 data.rawTx 的原始交易字串。</i> false: 接收解碼為 data.rawTx 的 JSON 結果。 布林值 是
callbackUrl 用於接收交易是否成功/失敗的地址 字串 是

回應

欄位名稱 說明 類型
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

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

路徑參數

欄位名稱 說明 類型 必要性
contract 鎖定合約地址 字串 Y

標頭參數

欄位名稱 說明 類型 必填 여부
Authorization 用於調用 API 的認證令牌 字串 Y
x-network 區塊鏈網絡{ploygon, xpla} 字串 Y
x-appid 應用程序唯一 ID。可以在 Hive 控制台應用中心 > AppID 列表中查看。 字串 Y

請求主體

欄位名稱 說明 類型 必填與否
playerId 玩家 ID 字串 是
nftContract NFT 合約地址 字串 是
from 鎖定合約擁有者錢包地址 字串 是
isSend true時，當KMS中有錢包金鑰時，將自動用此金鑰簽署交易並發送到區塊鏈。回應值為 txHash。false時，將收到用戶需手動簽署的交易數據 data.rawTx。 布林值 是
tokenId NFT ID 字串 是
encoded 是否返回編碼的交易
  • true: 收到編碼為 data.rawTx 的原始交易字串。
  • false: 收到解碼為 data.rawTx 的 JSON 結果。
布林值 是
callbackUrl 用於接收交易在區塊鏈上記錄成功/失敗結果的地址 字串 是

回應

欄位名稱 說明 類型
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)。
 字串 Y

標頭參數

欄位名稱 說明 類型 必填與否
Authorization 用於調用 API 的認證令牌 字串 是
x-network 區塊鏈網絡{ploygon, xpla} 字串 是
x-appid 應用程序唯一 ID。可以在 Hive 控制台應用中心 > AppID 列表中查看。 字串 是

請求主體

欄位名稱 說明 類型 必填
playerId 玩家 ID 字串 Y
isSend 如果是true，當KMS中有錢包密鑰時，將自動使用此密鑰對交易進行簽名，然後將其發送到區塊鏈。回應值為txHash。如果是false，則會收到用戶需要手動簽名的交易數據data.rawTx。 布林值 Y
owner 使用者的錢包地址 字串 Y
convertPool 轉換池地址 字串 Y
gameTokenAmount 遊戲代幣數量 字串 Y
gameCurrencyCode 遊戲貨幣代碼 字串 Y
gameCurrencyAmount 遊戲貨幣數量 字串 Y
encoded 返回的交易編碼狀態<i> true: 接收編碼為data.rawTx的原始交易字串。</i> false: 接收解碼為data.rawTx的 JSON 結果。 布林值 Y
callbackUrl 用於接收交易在區塊鏈上記錄成功/失敗結果的地址 字串 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

實時 URL https://bc-api.qpyou.cn/service/v1/convert/pool/{convertPool}
沙盒 URL https://sandbox-bc-api.qpyou.cn/service/v1/convert/pool/{convertPool}
HTTP 方法 GET
內容類型 application/json

路徑參數

欄位名稱 說明 類型 必填 여부
convertPool 轉換池地址 字串 Y

標頭參數

欄位名稱 說明 類型 必填與否
Authorization 用於調用 API 的認證令牌 字串 是
x-network 區塊鏈網絡{ploygon, xpla} 字串 是
x-appid 應用程序唯一 ID。可以在 Hive 控制台應用中心 > AppID 列表中查看。 字串 是

回應

欄位名稱 說明 類型
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 註冊

當生成某個交易時（如 mint、convert、lock 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 的認證令牌 字串 是
x-network 區塊鏈網絡{ploygon, xpla} 字串 是
x-appid 應用程序的唯一 ID。可以在 Hive 控制台應用中心 > AppID 列表中查看。 字串 是

請求主體

欄位名稱 說明 類型 必填 여부
requestId 可識別API請求的唯一值 字串 Y
txHash 交易哈希 字串 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 的認證令牌 字串 Y
x-network 區塊鏈網絡{ploygon, xpla} 字串 Y
x-appid 應用程序唯一 ID。可以在 Hive 控制台應用中心 > AppID 列表中查看。 字串 Y

查詢參數

欄位名稱 說明 類型 必填與否
playerId 玩家 ID 字串 N
startDate 交易生成日期搜尋條件（開始日，yyyy-mm-dd） 字串 N
endDate 交易生成日期搜尋條件（結束日，yyyy-mm-dd） 字串 N
page 當前頁碼 數字 N
limit 每頁顯示的交易數量 數字 N

回應

欄位名稱 說明 類型
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 代幣合約地址 字串 Y
from 代幣擁有者帳戶 字串 Y

標頭參數

欄位名稱 說明 類型 必填與否
Authorization 用於調用 API 的認證令牌 字串 Y
x-network 區塊鏈網絡{ploygon, xpla} 字串 Y
x-appid 應用程序唯一 ID。可以在 Hive 控制台應用中心 > AppID 列表中查看。 字串 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

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

路徑參數

欄位名稱 說明 類型 必填與否
owner 部署合約的帳戶地址 字串 Y

標頭參數

欄位名稱 說明 類型 必填與否
Authorization 用於調用 API 的認證令牌 字串 Y
x-network 區塊鏈網絡{ploygon, xpla} 字串 Y
x-appid 應用程序唯一 ID。可以在 Hive 控制台應用中心 > AppID 列表中查看。 字串 Y

查詢參數

欄位名稱 說明 類型 必填與否
contractType 合約類型 字串 否
page 當前頁面編號 數字 否
limit 每頁顯示的合約數量 數字 否

回應

欄位名稱 說明 類型
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)，執行如下區塊鏈功能。

  • Mint: 將物品發行為 NFT 的功能，並為物品設定唯一值 NFT ID(tokenId)。當 NFT 被發行後，遊戲內物品需要進行非活化處理。
  • Convert: 將遊戲貨幣與 XPLA 或遊戲代幣之間進行交換的功能，需要在 Hive 控制台註冊的遊戲貨幣代碼(gameCurrencyCode)。當遊戲貨幣與代幣(XPLA)之間的交換結束後，需要更新遊戲內的遊戲貨幣數量。
  • Lock: 鎖定已發行的 NFT 並在遊戲中再次使用的功能，需要在遊戲內啟用物品。(鎖定後在遊戲中可用的物品不得在遊戲內交換或移除，否則無法解鎖。)
    • <
  • 解鎖：這是一個功能，可以讓您在遊戲中使用的物品再次在用戶錢包中使用，要求物品的唯一值 NFT ID(tokenId)，並且只能在鎖定(NFT 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} 字符串 是
info 区块链功能的选项信息 json 是
appid 区块链应用的唯一ID。可以在Hive控制台应用中心 > AppID列表中查看。 字符串 是
gameAppid 游戏应用的唯一ID。可以在Hive控制台应用中心 > AppID列表中查看。 字符串 是
playerId 玩家ID 数字 是
callbackUrl 在区块链上记录交易后接收成功/失败结果的地址 字符串 是
language 语言代码 字符串 是
actionType別 request body info中包含的各元素信息
  • 鑄造
    字段名 说明 类型
    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別 response data info中包含的各元素信息
  • MINT: 與請求主體信息中的 MINT 相同
  • CONVERT
    字段名稱 說明 類型
    convertPool 轉換池帳戶地址 string
    gameCurrencyCode 遊戲貨幣代碼 string
    userGameCurrencyAmount 用戶要交換的遊戲貨幣數量 number
    minCurrencyAmount 可交換的遊戲貨幣的最小數量 number
    maxCurrencyAmount 可交換的遊戲貨幣的最大數量 number
    totalExchangedCurrencyAmount 用戶目前為止已交換的遊戲貨幣數量 number
    currencyName 遊戲貨幣名稱 string
    currencyLogoUrl 遊戲貨幣標誌 URL string
    assetType 代幣類型 {token | coin} string
    ftContract 遊戲代幣地址 string
    tokenName 遊戲代幣名稱 string
    tokenLogoUrl 遊戲代幣標誌 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 自訂
HTTP 方法 POST
內容類型 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 執行動作的結果 json Y
result.actionStatus 動作狀態 {SUCCESS, FAILRUE, EXPIRATION, CANCELLATION} string Y
result.actionType 動作的類型 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 執行動作的內容 json Y
data.user 執行動作所使用的用戶資訊 json Y
data.user.playerId 玩家 ID string Y
data.user.wallet 玩家錢包地址 string Y
data.convert 執行動作所使用的轉換資訊 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)之間的Mint、Convert、Lock、Unlock、Burn功能。

XPLA 網頁連結生成 API

使用者在請求生成 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銷毀並在遊戲中使用該物品的功能，銷毀後可以在遊戲中交換和移除物品

執行 Mint、Convert、Lock、Unlock、Burn 功能後，通過 callbackUrl 傳遞結果。

Note

一旦生成的 XPLA 網頁連結在 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}
若查詢參數不存在: 可省略		 字串 N
X-Request-ID XPLA Web Link 創建請求時發放的 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 在 XPLA Web Link 交換後處理的結果 json Y
result.actionStatus 動作狀態 string Y
result.actionType XPLA Web Link 類型 MINT, BURN, LOCK, UNLOCK json Y
result.txHash 交易哈希 string Y
result.isAvailableItem 遊戲內物品使用可能性 boolean 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.nft XPLA Web Link 處理的 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)，对应于游戏货币代码(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