コンテンツにスキップ

ハイブブロックチェーン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呼び出しごとに1つのアカウントに対してXPLAは最大200トークン、Polygonは最大50トークンを発行できます。fromは発行権限を持つアカウントである必要があります。

Note

APIで発行したデジタル資産と資産のメタデータ(mintMsg.metadata)はPublic IPFS(InterPlanetary File System)に登録されます。

リクエストURL

ライブ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 コントラクト アドレス string 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にアップロードするための外部からアクセス可能なウェブサイトのアドレスまたはPublic 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 attributesを構成する項目名です。 string N
mintMsg.metadata.attributes.maxValue traitの最大値 number N
mintMsg.metadata.attributes.value trait値です。mintMsg.metadata.attributes.maxValueより小さくなければなりません。mintMsg.metadata.attributes.displayTypeがdateの場合、valueにunix timestamp (seconds)を入力します。 string または number N
mintMsg.metadata.attributes.displayType traitの表示タイプです。デフォルトはstringタイプです。
  • number: Numberタイプ
  • boost_percentage: OpenSea Boostsに%情報で表示
  • boost_number: OpenSea Boostsに表示
  • date: 日付形式で表示(例: Tuesday, January 1st, 2019)
 string N
encoded 返されるトランザクションのエンコーディングの有無
  • true: data.rawTxとしてエンコードされたRaw Transaction Stringを受け取ります。
  • 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/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コントラクトアドレス string Y
tokenId トークンID 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.nftContract NFT コントラクトアドレス string
data.tokenId トークン ID string
data.tokenUri トークンの IPFS アドレス string
data.gatewayUrl トークンのゲートウェイアドレス 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: 日付形式で表示 (例: Tuesday, January 1st, 2019)
 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コントラクトアドレス string 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としてエンコードされたRaw Transaction Stringを受け取ります。 </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としてエンコードされたRaw Transaction Stringを受け取ります。
  • 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/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としてエンコードされたRaw Transaction Stringを受け取ります。 </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/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 コンバートプールアドレス 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

リクエストサンプル

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

ライブURL https://bc-api.qpyou.cn/service/v1/tx/hash
サンドボックスURL 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

ライブURL https://bc-api.qpyou.cn/service/v1/tx
サンドボックスURL 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 string N
startDate トランザクション生成日検索条件(開始日, yyyy-mm-dd) string N
endDate トランザクション生成日検索条件(終了日, yyyy-mm-dd) string N
page 現在のページ番号 number N
limit 1ページに表示されるトランザクション件数 number 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

ライブURL https://bc-api.qpyou.cn/service/v1/ft/{contract}/account/{from}/balance
サンドボックスURL 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 1ページに表示するコントラクトの数 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
    }
  }
}

アクションAPI

アクションAPIはXPLAブロックチェーンに基づいてゲームと連携し、ウェブページのURLを提供するAPIです。ユーザーはアクションAPIを通じてゲーム内通貨とゲームトークン(XPLA)間のMint、Convert、Lock、Unlock、Burn機能を実行できます。

Action生成API

ユーザーはAction生成リクエストを送信した後、応答として受け取ったウェブページ(actionLink)にアクセスして、以下のようなブロックチェーン機能を実行できます。

  • ミント: アイテムをNFTとして発行する機能で、アイテムに対するユニークな値としてNFT ID(tokenId)を設定します。NFTが発行されると、インゲームアイテムは非アクティブ化する必要があります。
  • コンバート: ゲーム通貨とXPLAまたはゲームトークン間で交換する機能で、Hiveコンソールで登録したゲーム通貨コード(gameCurrencyCode)が必要です。ゲーム通貨とトークン(XPLA)間の交換が完了すると、インゲームのゲーム通貨の数量を更新する必要があります。
  • ロック: 発行されたNFTをロックし、再びインゲームで使用する機能で、インゲーム内アイテムのアクティブ化が必要です。(ロック後、インゲームで使用可能なアイテムはゲーム内で交換または削除されない必要があり、アンロックが可能です。)
  • Unlock: ゲーム内で使用中のアイテムを再びユーザーのウォレットで使用できるようにNFTのロックを解除する機能で、アイテムに対するユニークな値NFT ID(tokenId)が要求され、NFTをロック(Lock)したアカウントとウォレットでのみロック解除(Unlock)が可能です。Unlockが実行されると、ゲーム内アイテムは非アクティブ化する必要があります。
  • Burn: 発行されたNFTを消滅させ、ゲーム内でそのアイテムを使用する機能で、Burn後にゲーム内でアイテムの交換および削除が可能です。

Mint、Convert、Lock、Unlock、Burn機能を実行後、callbackUrlを通じて結果を伝達します。

Note

一度生成されたアクションは5分間有効であり、5分が経過するか、そのアクション機能の実行が完了すると、もはや使用できなくなります。

リクエスト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別 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別のレスポンスデータ情報に含まれる各要素情報
  • MINT: request body infoの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: request body infoのLOCKと同じ
  • UNLOCK: request body infoのUNLOCKと同じ
  • BURN: request body infoの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

ユーザーがアクション機能（MINT、LOCK、UNLOCK、BURN、CONVERT）を使用した後、callbackUrlをリクエストすると、アクションの実行結果を受け取ることができます。

リクエストURL

URL カスタム
HTTP Method POST
Content-Type application/json

ヘッダー パラメータ

フィールド名 説明 タイプ 必須かどうか
Authorization callbackUrlにtokenクエリパラメータが存在: Bearer ${token} クエリパラメータがない場合は省略 string N
X-Request-ID Actionリクエスト時に発行された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 アクション実行結果 json Y
result.actionStatus アクションの状態 {SUCCESS, FAILURE, EXPIRATION, CANCELLATION} string Y
result.actionType アクションのタイプ MINT, BURN, LOCK, UNLOCK json Y
result.txHash トランザクションハッシュ string Y
result.isAvailableItem ゲーム内アイテムの使用可能かどうか boolean Y
data アクション実行内容 json Y
data.user アクション実行に使用されたユーザー情報 json Y
data.user.playerId プレイヤーID string Y
data.user.wallet プレイヤーのウォレットアドレス string Y
data.nft アクション実行に使用されたNFT情報 json Y
data.nft.nftContract NFTコントラクトアドレス string Y
data.nft.tokenId NFT ID string Y
data.serviceFeeAmount ユーザーが支払ったサービス手数料 (XPLA) number Y

リクエストボディ (CONVERT使用時のcallbackUrl)

  • Convertの実行に関するアクションステータス(result.actionStatus)と、ゲーム内で更新が必要なゲーム通貨の数量(result.amount)を伝えます。
  • ゲーム通貨コード(result.amount.currencyCode)に該当するユーザーが保有しているゲーム通貨の数量(result.amount)の更新が必要です。
フィールド名 説明 タイプ 必須かどうか
result アクション実行結果 json Y
result.actionStatus アクションの状態 {SUCCESS, FAILURE, 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プラットフォームAPIは、XPLAブロックチェーンに基づいてゲームと連携し、ウェブページのURLを提供するAPIです。ユーザーはXPLAプラットフォームAPIを通じて、ゲーム資産とゲームトークン（XPLA）間のMint、Convert、Lock、Unlock、Burn機能を実行できます。

XPLA Web Link生成API

ユーザーはXPLA Web Link生成リクエスト後に応答されたウェブページ(actionLink)にアクセスし、以下のようなブロックチェーン機能を実行できます。

  • Mint: アイテムをNFTとして発行する機能で、アイテムに対するユニークな値としてNFT ID(tokenId)を設定します。NFTが発行されると、インゲームアイテムは非活性化処理が必要です。
  • Convert: ゲーム通貨とXPLAまたはゲームトークンを交換する機能で、Hiveコンソールで登録したゲーム通貨コード(gameCurrencyCode)が必要です。ゲーム通貨とトークン(XPLA)間の交換が終了すると、インゲームのゲーム通貨の数量更新が必要です。
  • Lock: 発行されたNFTをロックし、再びインゲームで使用する機能で、インゲーム内アイテムの活性化が必要です。(ロック後、インゲームで使用可能なアイテムはゲーム内で交換または削除されない必要があり、アンロックが可能です)
  • Unlock: インゲームで使用中のアイテムを再びユーザーのウォレットで使用できるようにNFTのロックを解除する機能で、アイテムに対するユニークな値NFT ID(tokenId)が要求され、NFTをロック(Lock)したアカウントとウォレットでのみロック解除(Unlock)が可能です。アンロックが実行されると、インゲームアイテムは非活性化処理が必要です。
  • Burn: 発行されたNFTを消滅させ、インゲームでそのアイテムを使用する機能で、バーン後にインゲームでアイテムの交換および削除が可能です。

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

ユーザーがアクション機能（MINT、LOCK、UNLOCK、BURN、CONVERT）を使用した後にcallbackUrlをリクエストすると、アクションの実行結果を受け取ることができます。

ヘッダーパラメータ

フィールド名 説明 タイプ 必須 여부
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 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)

Convertの実行に関するアクションステータス(result.actionStatus)と、ゲーム内で更新が必要なゲーム通貨の数量(result.amount)を伝えます。

ゲーム通貨コード(result.amount.currencyCode)に対応するユーザーが保有しているゲーム通貨の数量(result.amount)の更新が必要です。

フィールド名 説明 タイプ 必須 여부
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