Hive Blockchain API
Hive Blockchain API is the web 3.0 game API that is powered by Hive platform, using its AppID and PlayerID. The game player can mint many tokens at once, up to 200 tokens, and the game studio can get transaction log per user. There are many other features optimal for the web 3 games. With the Hive Blockchain API, you can efficiently set up the development, operation, and management of web 3 game projects. The Hive Blockchain API supports Polygon and XPLA blockchains.
Pre-requisites: Get API authentication token¶
To call a Hive Blockchain API, you have to append an auth token to the header of an API. This is how to get your API auth token.
- Sign up at the Hive Console, go to AppCenter > Game List > Register new game.
- Create an new AppID at AppCenter > AppID List > Register new AppID.
- Register new AppID: Web Login AppID
- Purpose of use: Blockchain
- AppID to use: Choose “automatically generated AppID” or “automatically generated AppID” with “Additional Information”
- Go to the the Hive Console > Blockchain > Search for API Authentication Key, select and search the game name, and get the ID and the Secret key.
- Insert the ID and the Secret key in the request body of auth-token API and call this API.
- You can get your API auth key as
data.accessTokenin the API responses.
NFT API¶
Mint NFT¶
Create a transaction that mint tokens to a specific address (to). Load the required NFT information (mintMsg.tokenId, mintMsg.metadata, etc.) into an array and call this API. You can mint a maximum of 200/50 tokens to 1 account for XPLA/Polygon per API call. from must be the account that has a right to mint.
Note
The digital asset and its metadata (mintMsg.metadata) created via API will be registered at the public IPFS (InterPlanetary File System).
Request URL¶
| Live URL | https://bc-api.qpyou.cn/service/v1/nft/{contract}/mint |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/service/v1/nft/{contract}/mint |
| HTTP Method | POST |
| Content-Type | application/json |
Path parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| contract | the NFT contract address | string | Y |
Header parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
| x-appid | This is the AppID of an app. Go to the Hive Console AppCenter > AppID lists to check an AppID. | string | Y |
Request body¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| playerId | the player id | string | Y |
| from | the account address that mints NFTs | string | Y |
| to | the wallet address that receives NFTs | string | Y |
| isSend | If true, when there is a wallet key in KMS, it automatically signs the transaction with this key and sends it to the blockchain. You will receive txHash as a response. If false, you will receive data.rawTx as a response, which is the transaction data that requires manual signing by the user. | boolean | Y |
| mintMsg | the required information | array | Y |
| mintMsg.tokenId | This is the NFT ID. The NFT ID should be unique, and is defined by the NFT minter. * Polygon: Only strings and integers (0~2256-1) are allowed. * XPLA: Only strings are allowed. | string | Y |
| mintMsg.royaltyPercentage | This is the royalty percentage. It is the money given to the creator of an NFT or the claimant every time the NFT is sold or resold. The royalty rate is applied to the total amount of sale. This feature is supported for the NFT marketplaces that are willing to continuously fund artists and NFT creators. The marketplace checks the NFT royalty and pay it to the recipient. The royalty is not directly paid to the recipient when the NFT is sold (transferred). This feature is adopted for the OpenSea. * Polygon: Allowed to the 2 decimal places. * XPLA: Only an integer is allowed. | number | Y |
| mintMsg.metadata | the metadata * You need to check type and url ( animationUrl, youtubeUrl, externalUrl) formats. If this data is incorrect, the API request may fail. * The metadata will be saved in the snake case to be used for OpenSea when it is saved in IPFS (example: animationUrl → animation_url) | json | Y |
| mintMsg.metadata.name | the NFT name | string | Y |
| mintMsg.metadata.description | the NFT description | string | N |
| mintMsg.metadata.image | This is the NFT image address. This is the public website address or the public IPFS address for uploading images to IPFS. | string | Y |
| mintMsg.metadata.animationUrl | the address for the NFT animation | string | N |
| mintMsg.metadata.youtubeUrl | the Youtube address | string | N |
| mintMsg.metadata.imageData | the NFT image information | string | N |
| mintMsg.metadata.externalUrl | the external url | string | N |
| mintMsg.metadata.backgroundColor | the background color info of the token (OpenSea) | string | N |
| mintMsg.metadata.attributes | These are the information of the metadata attributes. These contain the additional info that are not described in the metadata. | json | N |
| mintMsg.metadata.attributes.traitType | The names of the items that constitute attributes | string | N |
| mintMsg.metadata.attributes.maxValue | the maximum value of trait | number | N |
| mintMsg.metadata.attributes.value | This is the trait value. It should be less than mintMsg.metadata.attributes.maxValue. If mintMsg.metadata.attributes.displayType is date, set this value following unix timestamp (seconds) format. | string or number | N |
| mintMsg.metadata.attributes.displayType | This is the display type of the trait. The default value is string. * number: numeric type * boost_percentage: percentage (OpenSea Boosts) * boost_number: numeric (OpenSea Boosts) ,br> * date: date type (example: Tuesday, January 1st, 2019) | string | N |
| encoded | whether the returned transaction is encoded or not * true: Receive the encoded raw transaction string (data.rawTx). * false: Receive the decoded data.rawTx (JSON). | boolean | Y |
| callbackUrl | the address to which the result of sending transaction is returned | string | Y |
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.rawTx | Transaction data. You receive this value only when isSend is false. | string or json |
| data.hashedTx | Hashed data.rawTx. You receive this value only when all the following conditions are met: 1. x-network is polygon 2. from is a multi-signature wallet address 3. isSend is false | string |
| data.txhash | Transaction hash received as a result of sending the transaction. You receive this value only when isSend is true. | string |
| data.status | Status of the sent transaction. If isSend is true and the transaction has been sent successfully, you will receive PENDING. If isSend is false, it means the transaction requires signing before sending, and you will receive WAITING. | string |
| data.reqeustId | the unique value that can identify each API request | string |
Request sample¶
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/"
}'
Response sample¶
// When the isSend in the Request Body is true and the from is a wallet address created from a KMS key
{
"code": 0,
"message": "success",
"data": {
"txhash": "02f8f3830138810b8459682f008459682f1083023...",
"status": "pending",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When the isSend in the Request Body is false and the from is a multi-signature wallet address
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8f3830138810b8459682f008459682f1083023...",
"hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When the isSend in the Request Body is false and the from is either a wallet address created from a KMS key or a plain wallet address
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8f3830138810b8459682f008459682f1083023...",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When isSend in the Request Body is false: data.rawTx is a string
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
"requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
}
}
// When isSend in the Request Body is false: data.rawTx is a JSON object
{
"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"
}
}
Get NFT information¶
Get NFT information via the token ID (tokenId).
Request URL¶
| Live URL | https://bc-api.qpyou.cn/service/v1/nft/{contract}/tokens/{tokenId} |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/service/v1/nft/{contract}/tokens/{tokenId} |
| HTTP Method | POST |
| Content-Type | application/json |
Path parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| contract | the NFT contract address | string | Y |
| tokenId | the token ID | string | Y |
Header parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
| x-appid | This is the AppID of an app. Go to the Hive Console AppCenter > AppID lists to check an AppID. | string | Y |
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.nftContract | the NFT contract address | string |
| data.tokenId | the token ID | string |
| data.tokenUri | the IPFS address of the token | string |
| data.gatewayUrl | the gateway address of the token | string |
| data.metadata | the metadata information | json |
| data.metadata.name | the NFT name | string |
| data.metadata.description | the NFT description | string |
| data.metadata.image | This is the NFT image address. This is the public website address or the public IPFS address. | string |
| data.metadata.animationUrl | the address for the NFT animation | string |
| data.metadata.youtubeUrl | the Youtube address | string |
| data.metadata.imageData | the NFT image information | string |
| data.metadata.externalUrl | the external url | string |
| data.metadata.backgroundColor | the background color info of the token (OpenSea) | string |
| data.metadata.attributes{} | These are the information of the metadata attributes. These contain the additional info that are not described in the metadata. | json |
| data.metadata.attributes.traitType | The names of the items that constitute attributes | string |
| data.metadata.attributes.maxValue | the maximum value of trait | string |
| data.metadata.attributes.value | This is the trait value. It should be less than data.metadata.attributes.maxValue. If data.metadata.attributes.displayType is date, set this value following unix timestamp (seconds) format. | string or number |
| data.metadata.attributes.displayType | This is the display type of the trait. The default value is string. * number: numeric type * boost_percentage: percentage (OpenSea Boosts) * boost_number: numeric (OpenSea Boosts) * date: date type (example: Tuesday, January 1st, 2019) | string |
Request sample¶
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...'
Response sample¶
{
"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"
}
]
}
}
}
Lock API¶
Lock NFT¶
Locking an NFT means forbidding a minted NFT to be traded. When a gamer minted an NFT from a game item and wants this item to use in the game again, the minted NFT is locked and become unavailable for trading. Creates a lock transaction to lock down the NFT (tokenId). The owner (owner) of an NFT won’t be able to use this NFT.
Request URL¶
| Live URL | https://bc-api.qpyou.cn/service/v1/nft/contract/{contract}/lock |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/ service/v1/nft/contract/{contract}/lock |
| HTTP Method | POST |
| Content-Type | application/json |
Path parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| contract | the NFT contract address | string | Y |
Header parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
| x-appid | This is the AppID of an app. Go to the Hive Console AppCenter > AppID lists to check an AppID. | string | Y |
Request body¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| playerId | the player id | string | Y |
| from | the wallet address of the NFT owner | string | Y |
| isSend | If true, when there is a wallet key in KMS, it automatically signs the transaction with this key and sends it to the blockchain. You will receive txHash as a response. If false, you will receive data.rawTx as a response, which is the transaction data that requires manual signing by the user. | boolean | Y |
| lockContract | the address of the NFT lock contract | string | Y |
| tokenId | NFT ID | String | Y |
| encoded | whether the returned transaction is encoded or not * true: Receive the encoded raw transaction string (data.rawTx). * false: Receive the decoded data.rawTx (JSON). | boolean | Y |
| callbackUrl | the address to which the result of sending transaction is returned | string | Y |
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.rawTx | Transaction data. You receive this value only when isSend is false. | string or json |
| data.hashedTx | Hashed data.rawTx. You receive this value only when all the following conditions are met: 1. x-network is polygon 2. from is a multi-signature wallet address 3. isSend is false | string |
| data.txhash | Transaction hash received as a result of sending the transaction. You receive this value only when isSend is true. | string |
| data.status | Status of the sent transaction. If isSend is true and the transaction has been sent successfully, you will receive PENDING. If isSend is false, it means the transaction requires signing before sending, and you will receive WAITING. | string |
| data.reqeustId | the unique value that can identify each API request | string |
Request sample¶
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/"
}'
Response sample¶
// When the isSend in the Request Body is true and the from is a wallet address created from a KMS key
{
"code": 0,
"message": "success",
"data": {
"txhash": "02f8f3830138810b8459682f008459682f1083023...",
"status": "pending",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When the isSend in the Request Body is false and the from is a multisig wallet address
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8f3830138810b8459682f008459682f1083023...",
"hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When the isSend in the Request Body is false and the from is either a wallet address created from a KMS key or a plain wallet address
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8f3830138810b8459682f008459682f1083023...",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When isSend in the Request Body is false: data.rawTx is a string
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
"requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
}
}
// When isSend in the Request Body is false: data.rawTx is JSON obejct
{
"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"
}
}
Unlock NFT¶
Creates a unlocking transaction to release the NFT (tokenId) from being locked. The owner (owner) of an NFT will be able to use this NFT again.
Request URL¶
| Live URL | https://bc-api.qpyou.cn/service/v1/lock/contract/{contract}/unlock |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/service/v1/lock/contract/{contract}/unlock |
| HTTP Method | POST |
| Content-Type | application/json |
Path parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| contract | the address of the NFT lock contract | string | Y |
Header parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
| x-appid | This is the AppID of an app. Go to the Hive Console AppCenter > AppID lists to check an AppID. | string | Y |
Request body¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| playerId | the PlayerID | string | Y |
| nftContract | the NFT contract address | string | Y |
| from | the wallet address of the owner of the NFT lock contract | string | Y |
| isSend | If true, when there is a wallet key in KMS, it automatically signs the transaction with this key and sends it to the blockchain. You will receive txHash as a response. If false, you will receive data.rawTx as a response, which is the transaction data that requires manual signing by the user. | boolean | Y |
| tokenId | NFT ID | String | Y |
| encoded | whether the returned transaction is encoded or not true: Receive the encoded raw transaction string (data.rawTx). false: Receive the decoded data.rawTx (JSON). | boolean | Y |
| callbackUrl | the address to which the result of sending transaction is returned | string | Y |
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.rawTx | Transaction data. You receive this value only when isSend is false. | string or json |
| data.hashedTx | Hashed data.rawTx. You receive this value only when all the following conditions are met: 1. x-network is polygon 2. from is a multi-signature wallet address 3. isSend is false | string |
| data.txhash | Transaction hash received as a result of sending the transaction. You receive this value only when isSend is true. | string |
| data.status | Status of the sent transaction. If isSend is true and the transaction has been sent successfully, you will receive PENDING. If isSend is false, it means the transaction requires signing before sending, and you will receive WAITING. | string |
| data.reqeustId | the unique value that can identify each API request | string |
Request sample¶
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,
"nftContract": "0xebd9144485089ebe248f8490984a60579407c262",
"from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
"isSend": true,
"tokenId": "2",
"encoded": true,
"callbackUrl": "https://withhive.com/"
}'
Response sample¶
// When the isSend in the Request Body is true and the from is a wallet address created from a KMS key
{
"code": 0,
"message": "success",
"data": {
"txhash": "02f8f3830138810b8459682f008459682f1083023...",
"status": "pending",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When the isSend in the Request Body is false and the from is a multisig wallet address
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8f3830138810b8459682f008459682f1083023...",
"hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When the isSend in the Request Body is false and the from is either a wallet address created from a KMS key or a plain wallet address
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8f3830138810b8459682f008459682f1083023...",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When isSend in the Request Body is false: data.rawTx is a string
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
"requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
}
}
// When isSend in the Request Body is false: data.rawTx is JSON obejct
{
"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"
}
}
Convert API¶
Exchange game currency and game token¶
Exchange the game token for the game currency or the vice versa.
- to-token: Exchange the game currency (gameCurrencyCode) for the game token (gameToken).
- to-currency: Exchange the game token (gameToken) for the game currency (gameCurrencyCode).
Request URL¶
| Live URL | https://bc-api.qpyou.cn/service/v1/convert/{type} |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/service/v1/convert/{type} |
| HTTP Method | POST |
| Content-Type | application/json |
Path parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Type | the convert type * to-token: Exchange the game currency ( gameCurrencyCode) for the game token (gameToken). * to-currency: Exchange the game token ( gameToken) for the game currency (gameCurrencyCode). | string | Y |
Header parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
| x-appid | This is the AppID of an app. Go to the Hive Console AppCenter > AppID lists to check an AppID. | string | Y |
Request body¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| playerId | the PlayerID | string | Y |
| isSend | If true, when there is a wallet key in KMS, it automatically signs the transaction with this key and sends it to the blockchain. You will receive txHash as a response. If false, you will receive data.rawTx as a response, which is the transaction data that requires manual signing by the user. | boolean | Y |
| owner | the wallet address of the user | string | Y |
| convertPool | the address of the convert pool | string | Y |
| gameTokenAmount | the amount of the game token | string | Y |
| gameCurrencyCode | the code of the game currency | string | Y |
| gameCurrencyAmount | the amount of the game currency | string | Y |
| encoded | whether the returned transaction is encoded or not * true: Receive the encoded raw transaction string (data.rawTx). * false: Receive the decoded data.rawTx (JSON). | boolean | Y |
| callbackUrl | the address to which the result of sending transaction is returned | string | Y |
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.rawTx | Transaction data. You receive this value only when isSend is false. | string or json |
| data.hashedTx | Hashed data.rawTx. You receive this value only when all the following conditions are met: 1. x-network is polygon 2. from is a multi-signature wallet address 3. isSend is false | string |
| data.txhash | Transaction hash received as a result of sending the transaction. You receive this value only when isSend is true. | string |
| data.status | Status of the sent transaction. If isSend is true and the transaction has been sent successfully, you will receive PENDING. If isSend is false, it means the transaction requires signing before sending, and you will receive WAITING. | string |
| data.reqeustId | the unique value that can identify each API request | string |
Request sample¶
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/"
}'
Response sample¶
// When the isSend in the Request Body is true and the from is a wallet address created from a KMS key
{
"code": 0,
"message": "success",
"data": {
"txhash": "02f8f3830138810b8459682f008459682f1083023...",
"status": "pending",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When the isSend in the Request Body is false and the from is a multisig wallet address
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8f3830138810b8459682f008459682f1083023...",
"hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When the isSend in the Request Body is false and the from is either a wallet address created from a KMS key or a plain wallet address
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8f3830138810b8459682f008459682f1083023...",
"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
}
}
// When isSend in the Request Body is false: data.rawTx is a string
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
"requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
}
}
// When isSend in the Request Body is false: data.rawTx is JSON obejct
{
"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"
}
}
Get convert pool information¶
A convert pool is a place where the game token minted by the game studio and the game currency can be exchanged with each other. This API gets you the remaining amount of tokens and game currency in a convert pool.
Request URL¶
| Live URL | https://bc-api.qpyou.cn/service/v1/convert/pool/{convertPool} |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/service/v1/convert/pool/{convertPool} |
| HTTP Method | GET |
| Content-Type | application/json |
Path parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| convertPool | the address of the convert pool | string | Y |
Header parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
| x-appid | This is the AppID of an app. Go to the Hive Console AppCenter > AppID lists to check an AppID. | string | Y |
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
Request sample¶
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 ''
Response sample¶
{
"code": 0,
"message": "success",
"data": {
"convertPoolAmount": "1000000000",
"gameCurrency": [
{
"goodsCode": "A39539HFTBRONZE0003",
"goodsAmount": "10000000000"
},
{
"goodsCode": "A39539HFTGOLD0001",
"goodsAmount": "1000000000000"
},
{
"goodsCode": "A39539HFTSILVER0002",
"goodsAmount": "100000000000"
}
]
}
}
Transaction API¶
Register txhash¶
Register requestId that is returned in the API response after you created a transaction (mint, convert, lock API, etc.), and register txHash which is received after sending this transaction to a blockchain. The purpose of calling this API is tracking the request for creating a transaction and its status.
Request URL¶
| Live URL | https://bc-api.qpyou.cn/service/v1/tx/hash |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/service/v1/tx/hash |
| HTTP Method | PATCH |
| Content-Type | application/json |
Header parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
| x-appid | This is the AppID of an app. Go to the Hive Console AppCenter > AppID lists to check an AppID. | string | Y |
Request body¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| requestId | the unique value that can identify each API request | string | Y |
| txHash | the transaction hash | string | Y |
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
Request sample¶
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"
}'
Response sample¶
Get transaction list¶
This API gets you the list of transactions requested to be sent to a blockchain. If the requested transactions are successfully sent and recorded in a blockchain, its status (transactions.txStatus) is updated to “success.”
Request URL¶
| Live URL | https://bc-api.qpyou.cn/service/v1/tx |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/service/v1/tx |
| HTTP Method | GET |
| Content-Type | application/json |
Header parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
| x-appid | This is the AppID of an app. Go to the Hive Console AppCenter > AppID lists to check an AppID. | string | Y |
Query parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| playerId | the PlayerID | string | N |
| startDate | the start date of the search range for the transaction creation date (yyyy-mm-dd) | string | N |
| endDate | the end date of the search range for the transaction creation date (yyyy-mm-dd) | string | N |
| page | the current page no. | number | N |
| limit | the number of transactions that will be displayed on a page. | number | N |
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| transactions | the transaction information | array |
| transactions.appid | the unique code (AppID) for identification of an app registered at the AppCenter | string |
| transactions.playerId | the PlayerID | number |
| transactions.address | the wallet address of an account that created the transaction | string |
| transactions.contract | the contract address of the requested transaction | string |
| transactions.requestId | the unique value that can identify each API request | string |
| transactions.requestParams | the request parameters of the API | json |
| transactions.txType | the transaction type | string |
| transactions.txStatus | the transaction status | string |
| transactions.txHash | the transaction hash | string |
| transactions.createdAt | the date the transaction was created | string |
| transactions.updatedAt | the date the transaction was updated | string |
| meta | the pagination information | json |
| meta.totalItems | the total number | number |
| meta.itemCount | the number of exposures | number |
| meta.itemsPerPage | the number of exposures per page | number |
| meta.totalPages | the total number of pages | number |
| meta.currentPage | the current page no. | number |
Request sample¶
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...'
Response sample¶
{
"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
}
}
}
Token API¶
Get Token balance¶
This API gets you the current token balance of the token owner account address (from).
Request URL¶
| Live URL | https://bc-api.qpyou.cn/service/v1/ft/{contract}/account/{from}/balance |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/service/v1/ft/{contract}/account/{from}/balance |
| HTTP Method | GET |
| Content-Type | application/json |
Path parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| contract | the address of the token contract | string | Y |
| from | the token owner address | string | Y |
Header parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
| x-appid | This is the AppID of an app. Go to the Hive Console AppCenter > AppID lists to check an AppID. | string | Y |
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.value | the token balance | string |
| data.rawValue | the token balance not applying data.decimals | string |
| data.decimals | the maximum decimal places of the token | number |
| data.symbol | the symbol of the token | string |
| data.symbolUri | the token symbol image URI | string |
Request sample¶
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...'
Response sample¶
{
"code": 0,
"message": "success",
"data": {
"value": "999998999",
"symbol": "ST",
"decimals": 18,
"rawValue": "999998999000000000000000000"
}
}
Contract API¶
Get contract information¶
This API gets you the information of the contract that was deployed by an account address (owner).
Request URL¶
| Live URL | https://bc-api.qpyou.cn/service/v1/contract/owner/{owner} |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/service/v1/contract/owner/{owner} |
| HTTP Method | GET |
| Content-Type | application/json |
Path parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| owner | the account address that deployed the contract | string | Y |
Header parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
| x-appid | This is the AppID of an app. Go to the Hive Console AppCenter > AppID lists to check an AppID. | string | Y |
Query parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| contractType | the contract type | string | N |
| page | the current page no. | number | N |
| limit | the number of contracts that will be displayed on a page. | number | N |
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.contracts | the contract information | array |
| data.contracts.network | the chain information | string |
| data.contracts.owner | the account address that deployed the contract | string |
| data.contracts.address | the contract address | string |
| data.contracts.type | the contract type | string |
| data.contracts.name | the contract name | string |
| data.contracts.gameIndex | the game index | number |
| data.contracts.gameName | the game name | string |
| data.contracts.symbol | the contract symbol image URI | string |
| data.contracts.symbolUri | the contract symbol image URI | string |
| data.contracts.createdAt | the date the contract was recorded | string |
| meta | the pagination information | json |
| meta.totalItems | the total number | number |
| meta.itemCount | the number of exposures | number |
| meta.itemsPerPage | the number of exposures per page | number |
| meta.totalPages | the total number of pages | number |
| meta.currentPage | the current page no. | number |
Request sample¶
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...'
Response sample¶
{
"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¶
The Actions API is an API that provides webpage URLs in conjunction with games based on the XPLA blockchain. Users can perform Mint, Convert, Lock, Unlock, and Burn functions between in-game currency and game tokens (XPLA) through the Actions API.
Action Creation API¶
Users can access the webpage (actionLink) received after requesting Action creation to perform blockchain functions as shown below.
- Mint: A function that issues items as NFTs, setting a unique value for the item as the NFT ID (tokenId). Once the NFT is issued, the in-game item needs to be deactivated.
- Convert: A function that exchanges in-game currency with XPLA or game tokens, requiring the game currency code (gameCurrencyCode) registered in the Hive console. After the exchange between in-game currency and tokens (XPLA) is completed, an update of the in-game currency quantity is necessary.
- Lock: A function that locks issued NFTs for later use in-game, requiring activation of the item within the game. (Items that can be used in-game after locking should not be exchanged or removed in-game to allow for unlocking.)
- Unlock: A feature that allows items currently in use in the game to be unlocked for use again from the user's wallet, requiring a unique value NFT ID (tokenId) for the item, and can only be unlocked from the account and wallet that locked the NFT. Once Unlock is performed, the in-game item needs to be deactivated.
- Burn: This function allows you to destroy the issued NFT and use the item in-game, enabling item exchange and removal after burning in the game.
After performing the Mint, Convert, Lock, Unlock, and Burn functions, the results are delivered through the callbackUrl.
Note
An Action that has been created is valid for 5 minutes, and after 5 minutes or once the Action function has been completed, it can no longer be used.
Request URL¶
| Live URL | https://bc-api.qpyou.cn/xpla-platform/v1/actions |
|---|---|
| Sandbox URL | https://sandbox-bc-api.qpyou.cn/xpla-platform/v1/actions |
| HTTP Method | POST |
| Content-Type | application/json |
Header Parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | Authentication token for calling the API | string | Y |
요청 본문¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| actionType | Classification of blockchain functions {MINT | CONVERT | LOCK | UNLOCK | BURN} | string | Y |
| info | Option information for each blockchain function | json | Y |
| appid | This is the unique ID of the blockchain app. You can find it in the Hive console app center > AppID list. | string | Y |
| gameAppid | This is the unique ID of the game app. You can find it in the Hive console app center > AppID list. | string | Y |
| playerId | Player ID | number | Y |
| callbackUrl | The address to receive success/failure results after recording the transaction on the blockchain | string | Y |
| language | Language code | string | Y |
Information of each element contained in the request body by actionType¶
- MINT
Field Name Description Type nftContract NFT contract address string itemName In-game item name string tokenId NFT identifier (unique value of the item) string metadata Metadata (refer to NFT issuance API request body) json - CONVERT
Field Name Description Type convertPool Convert pool account address string gameCurrencyCode Game currency code string userGameCurrencyAmount Amount of game currency the user will exchange number minCurrencyAmount Minimum amount of game currency that can be exchanged number maxCurrencyAmount Maximum amount of game currency that can be exchanged number totalExchangedCurrencyAmount Amount of game currency the user has exchanged so far number - LOCK
Field Name Description Type nftContract NFT contract address string lockContract Lock contract address string - UNLOCK
Field Name Description Type nftContract NFT contract address string lockContract Lock contract address string tokenId NFT identifier (unique value of the item) string - BURN
Field Name Description Type nftContract NFT contract address string
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | API call result code, 0: success | number |
| message | Result message | string |
| data | API response data | json |
| data.id | Unique ID of the Action | string |
| data.actionType | Classification of blockchain functions {MINT | CONVERT | LOCK | UNLOCK | BURN} | string |
| data.info | Response information by actionType | json |
| data.info.serviceFee | Service fee cost for using blockchain functions | number |
| data.appid | Unique ID of the blockchain app. You can check it in the Hive console app center > AppID list. | json |
| data.gameAppid | Unique ID of the game app. You can check it in the Hive console app center > AppID list. | string |
| data.playerId | Player ID | number |
| data.language | Language code | string |
| data.callbackUrl | Address to receive success/failure results after recording the transaction on the blockchain | string |
| data.company | Company unique number | number |
| data.gameindex | Game index | number |
| data.appindex | Unique number assigned to the app by the Hive app center | number |
| data.actionLink | Webpage link to perform blockchain functions | string |
| data.result | Processing result of the Action | string |
| data.createdAt | Action registration date | string |
| data.updatedAt | Action modification date | string |
Information of each element contained in the response data info by actionType¶
- MINT: Same as MINT in request body info
- CONVERT
Field Name Description Type convertPool Convert pool account address string gameCurrencyCode Game currency code string userGameCurrencyAmount Amount of game currency the user will exchange number minCurrencyAmount Minimum amount of game currency that can be exchanged number maxCurrencyAmount Maximum amount of game currency that can be exchanged number totalExchangedCurrencyAmount Amount of game currency the user has exchanged so far number currencyName Game currency name string currencyLogoUrl Game currency logo URL string assetType Token type {token | coin} string ftContract Game token address string tokenName Game token name string tokenLogoUrl Game token logo URL string - LOCK: Same as LOCK in request body info
- UNLOCK: Same as UNLOCK in request body info
- BURN: Same as BURN in request body info
Request Sample¶
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¶
When the user requests the callbackUrl after using the Action features (MINT, LOCK, UNLOCK, BURN, CONVERT), the results of the Action performed can be received.
Request URL¶
| URL | Custom |
|---|---|
| HTTP Method | POST |
| Content-Type | application/json |
Header Parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | Token query parameter exists in callbackUrl: Bearer ${token} omitted if query parameter is not present | string | N |
| X-Request-ID | ID issued when requesting Action | string | Y |
| User-Agent | XplaPlatform/1.0 | string | Y |
Request Body (When using MINT, LOCK, UNLOCK, BURN callbackUrl)¶
- Provides the action status (result.actionStatus) for Mint, Lock, Unlock, Burn operations and the availability of items that need to be updated in-game (result.isAvailableItem).
- Updates are needed for the items (data.nft.tokenId) held by the user (data.user.playerId).
| Field Name | Description | Type | Required |
|---|---|---|---|
| result | Result of the action performed | json | Y |
| result.actionStatus | Action status {SUCCESS, FAILURE, EXPIRATION, CANCELLATION} | string | Y |
| result.actionType | Type of the action MINT, BURN, LOCK, UNLOCK | json | Y |
| result.txHash | Transaction hash | string | Y |
| result.isAvailableItem | Availability of the item in the game | boolean | Y |
| data | Details of the action performed | json | Y |
| data.user | User information used for the action | json | Y |
| data.user.playerId | Player ID | string | Y |
| data.user.wallet | Player wallet address | string | Y |
| data.nft | NFT information used for the action | json | Y |
| data.nft.nftContract | NFT contract address | string | Y |
| data.nft.tokenId | NFT ID | string | Y |
| data.serviceFeeAmount | Service fee paid by the user (XPLA) | number | Y |
Request Body (When using CONVERT, callbackUrl)¶
- Pass the action status of the conversion (result.actionStatus) and the quantity of in-game currency that needs to be updated (result.amount).
- An update is needed for the quantity of in-game currency (result.amount) that the user holds corresponding to the currency code (result.amount.currencyCode).
| Field Name | Description | Type | Required |
|---|---|---|---|
| result | Result of the action performed | json | Y |
| result.actionStatus | Action status {SUCCESS, FAILURE, EXPIRATION, CANCELLATION} | string | Y |
| result.actionType | Type of action CONVERT | json | Y |
| result.txHash | Transaction hash | string | Y |
| result.amount | Quantity information of the conversion result | json | Y |
| result.amount.changeUserAmount | Change in user's game currency amount (+, -) | number | Y |
| result.amount.changePoolAmount | Change in conversion pool's game currency amount (+, -) | number | Y |
| result.amount.currencyCode | Game currency code | string | Y |
| data | Details of the action performed | json | Y |
| data.user | User information used for the action performed | json | Y |
| data.user.playerId | Player ID | string | Y |
| data.user.wallet | Player wallet address | string | Y |
| data.convert | Conversion information used for the action performed | json | Y |
| data.convert.type | Conversion type (CONVERT_TO_TOKEN, CONVERT_TO_CURRENCY) | string | Y |
| data.convert.convertPool | Conversion pool address | string | Y |
| data.convert.ftContract | Token address (or XPLA) | string | Y |
| data.convert.currencyCode | Game currency code | string | Y |
| data.in | Quantity information flowing into the conversion pool | json | Y |
| data.in.amount | Quantity of tokens (currency) requested by the user | number | Y |
| data.in.txFeeAmount | Transaction fee paid by the user | number | Y |
| data.in.txFeeType | XPLA or CURRENCY | string | Y |
| data.out | Quantity information flowing out of the conversion pool | json | Y |
| data.out.amount | Quantity of tokens (currency) to be received by the user | number | Y |
| data.serviceFeeAmount | Service fee paid by the user (XPLA) | number | Y |
XPLA Platform API¶
The XPLA Platform API is an API that provides a webpage URL in conjunction with games based on the XPLA blockchain. Users can perform Mint, Convert, Lock, Unlock, and Burn functions between in-game currency and game tokens (XPLA) through the XPLA Platform API.
XPLA Web Link Generation API¶
After the user requests the XPLA Web Link generation, they can access the received webpage (actionLink) to perform blockchain functions as follows:
- Mint: A function to issue items as NFTs, setting a unique value for the item as the NFT ID (tokenId). Once the NFT is issued, the in-game item needs to be deactivated.
- Convert: A function to exchange in-game currency and XPLA or game tokens, requiring the game currency code (gameCurrencyCode) registered in the Hive console. After the exchange between in-game currency and tokens (XPLA) is completed, an update to the in-game currency quantity is needed.
- Lock: A function to lock issued NFTs for use again in the game, requiring activation of the in-game item. (Items that can be used in-game after Lock should not be exchanged or removed within the game to enable Unlock.)
- Unlock: A function to unlock NFTs, allowing items used in-game to be used again in the user's wallet. This requires the unique value NFT ID (tokenId), and can only be unlocked from the account and wallet that locked (Lock) the NFT. Once Unlock is performed, the in-game item needs to be deactivated.
- Burn: A function to destroy issued NFTs and allows for the exchange and removal of the corresponding item in-game.
After performing the Mint, Convert, Lock, Unlock, and Burn functions, the results are communicated through callbackUrl.
Note
Once generated, the XPLA Web Link is valid for 5 minutes, and after 5 minutes or upon completion of the function, it can no longer be used.
Responses¶
| Field Name | Description | Type |
|---|---|---|
| code | API call result code, 0: success | number |
| message | Result message | string |
| data | API response data | json |
| data.id | Unique ID of the XPLA Web Link | string |
| data.actionType | Classification of blockchain function {MINT | CONVERT |
| data.info | Response information by actionType | json |
| data.info.serviceFee | Service fee cost for using blockchain functions | number |
| data.appid | Unique ID of the blockchain app. You can check it in Hive console App Center > AppID List. | json |
| data.gameAppid | Unique ID of the game app. You can check it in Hive console App Center > AppID List. | string |
| data.playerId | Player ID | number |
| data.language | Language code | string |
| data.callbackUrl | Address to receive success/failure results after recording the transaction on the blockchain | string |
| data.company | Company unique number | number |
| data.gameindex | Game index | number |
| data.appindex | Unique number assigned by the Hive App Center | number |
| data.actionLink | Webpage link to perform blockchain functions | string |
| data.result | Processing result of the XPLA Web Link | string |
| data.createdAt | Creation date of the XPLA Web Link | string |
| data.updatedAt | Modification date of the XPLA Web Link | string |
CallbackUrl API¶
After using the Action functions (MINT, LOCK, UNLOCK, BURN, CONVERT), users can request callbackUrl to receive the results of the Action performed.
Header Parameters¶
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | If the token query parameter exists in callbackUrl: Bearer ${token}If the query parameter is absent: omit | string | N |
| X-Request-ID | ID issued when requesting the XPLA Web Link generation | string | Y |
| User-Agent | XplaPlatform/1.0 | string | Y |
Request Body (For MINT, LOCK, UNLOCK, BURN using CallbackUrl)¶
This provides the action status of the Mint, Lock, Unlock, Burn operations (result.actionStatus) and whether the item in-game needs to be updated (result.isAvailableItem).
The user's (data.user.playerId) item (data.nft.tokenId) needs to be updated.
| Field Name | Description | Type | Required |
|---|---|---|---|
| result | Result processed after exchange in the XPLA Web Link | json | Y |
| result.actionStatus | Action status | string | Y |
| result.actionType | XPLA Web Link type MINT, BURN, LOCK, UNLOCK | json | Y |
| result.txHash | Transaction hash | string | Y |
| result.isAvailableItem | Whether the item can be used in-game | boolean | Y |
| data | Content processed in the XPLA Web Link | json | Y |
| data.user | User information processed in the XPLA Web Link | json | Y |
| data.user.playerId | Player ID | string | Y |
| data.user.wallet | Player wallet address | string | Y |
| data.nft | NFT information processed in the XPLA Web Link | json | Y |
| data.nft.nftContract | NFT contract address | string | Y |
| data.nft.tokenId | NFT ID | string | Y |
| data.serviceFeeAmount | Service fee paid by the user (XPLA) | number | Y |
Request Body (For CONVERT using CallbackUrl)¶
This provides the action status (result.actionStatus) for the Convert operation and the quantity of game currency that needs to be updated (result.amount).
The quantity of game currency that the user holds (result.amount) corresponding to the game currency code (result.amount.currencyCode) needs to be updated.
| Field Name | Description | Type | Required |
|---|---|---|---|
| result | Result processed after exchange in the XPLA Web Link | json | Y |
| result.actionStatus | Action status | string | Y |
| result.actionType | XPLA Web Link type CONVERT | json | Y |
| result.txHash | Transaction hash | string | Y |
| result.amount | Information about the quantity resulting from the conversion | json | Y |
| result.amount.changeUserAmount | Change in the user's game currency amount (+, -) | number | Y |
| result.amount.changePoolAmount | Change in the conversion pool's game currency amount (+, -) | number | Y |
| result.amount.currencyCode | Game currency code | string | Y |
| data | Content processed in the XPLA Web Link | json | Y |
| data.user | User information processed in the XPLA Web Link | json | Y |
| data.user.playerId | Player ID | string | Y |
| data.user.wallet | Player wallet address | string | Y |
| data.convert | Conversion information processed in the XPLA Web Link | json | Y |
| data.convert.type | Conversion type (CONVERT_TO_TOKEN, CONVERT_TO_CURRENCY) | string | Y |
| data.convert.convertPool | Conversion pool address | string | Y |
| data.convert.ftContract | Token address (or XPLA) | string | Y |
| data.convert.currencyCode | Game currency code | string | Y |
| data.in | Incoming quantity information to the conversion pool | json | Y |
| data.in.amount | Quantity of tokens (currency) requested by the user | number | Y |
| data.in.txFeeAmount | Transaction fee paid by the user | number | Y |
| data.in.txFeeType | XPLA or CURRENCY | string | Y |
| data.out | Outgoing quantity information from the conversion pool | json | Y |
| data.out.amount | Quantity of tokens (currency) to be received by the user | number | Y |
| data.serviceFeeAmount | Service fee paid by the user (XPLA) | number | Y |