Mint
Mint is a feature that issues game items as NFTs. In the Hive console, it issues NFTs based on the configured details in the user issuance tab under the Blockchain > XPLA > NFT menu.
Mint function implementation flow¶
Below is the implementation process for the Mint feature. To implement the Mint feature, please follow the flowchart image and the guide content below to implement the code in the game client (Hive SDK, game client) and game server area. The part marked with blue asterisks in the image below is the part that the developers need to work on. For more details on the main tasks, please refer to the guide below.
Note
After completing the preparation, you need to implement the Mint feature.
Note
To implement the Mint feature, you must use the Hive SDK.
Implementing login in hive SDK¶
Implement code in the game client to allow users to log in using IdP login with the Hive SDK authentication feature. Web login is also supported as a login method.
Implementing the NFT minting button¶
Implement a UI in the game client that allows users to open the NFT issuance page. For example, when a user selects an item from the character inventory after accessing the game, a Convert Item to NFT button should appear. When this button is pressed, the NFT issuance page should be opened according to the content below.
Request to convert item to NFT¶
Implementing the code to request the issuance of user game items as NFTs from the game client to the game server. This is to implement the action when the user selects the NFT issuance button. When the game server receives the request from the game client, it checks the game items to be issued as NFTs, and then calls the API to create a link for the NFT issuance page to issue the item as an NFT.
NFT issuance page link creation API call¶
The NFT issuance page is a webpage where users can convert their owned items into NFTs. This webpage is provided by the Hive blockchain server. The game server calls the link generation API to obtain this webpage URL (webLinkUrl
). When the user accesses this webpage, they can mint in-game items as NFTs on the blockchain.
Notes¶
Here are the precautions for developers when making API calls.
Gameserverurl¶
gameServerUrl
is used as the Request URL for the API that the Hive blockchain server calls to the game server (Item Validation API and Result Check API).
Gameserverurl and token¶
When the Hive blockchain server calls the Item Validation API or the Result Check API, the game server can use an authentication token (Header Parameters) for the API call, which is optional for the developers. If the game server opts to use an authentication token for the API call, it must pre-send this authentication token as token
(Query Parameter) to the Hive blockchain server when calling the NFT issuance page link generation API. An example is shown below.
Attributes¶
attributes
is used as the Request Body when the Hive blockchain server calls the item validation API and result confirmation API to the game server.
When you call the API with the item unique code contained in attributes
, the unique code can also be included in the Request Body attributes
of the Result Check API. In this case, you can update the item status with the corresponding unique code.
NFT issuance page link validity period¶
A link to a page created once is valid for only 10 minutes based on the first accessed session.
Request URL¶
Item | Value |
---|---|
Live URL | https://bc-platform-api.withhive.com/web3/v1/web-link |
Sandbox URL | https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link |
HTTP Method | POST |
Content-Type | application/json |
Header Parameters¶
Field Name | Description | Type | Required |
---|---|---|---|
Authorization | Authentication token for API calls | string | Y |
Request Body¶
Field Name | Description | Type | Required |
---|---|---|---|
type | MINT | string | Y |
playerId | Player ID | number | Y |
characterId | Character ID | string | Y |
gameServerUrl | The address to receive the success/failure results after item validation and function execution. Send the authentication token as a token Query Parameter for item validation/result confirmation API header | string | Y |
data | Request parameter information according to type | json | N |
Data object¶
Field Name | Description | Type | Required |
---|---|---|---|
itemId | User NFT template identifier (console registration) | string | Y |
attributes | Additional metadata properties to be applied per token (e.g., unique item code, strength, agility, etc. properties to be included in the NFT) | json array | N |
attributes.traitType | Item name that makes up attributes | string | N |
attributes.value | Trait value | string | N |
Request Sample¶
curl -X 'POST' \
'https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link' \
-H 'accept: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6NiwiaWQiOiIvVWpXN....' \
-H 'Content-Type: application/json' \
-d '{
"type": "MINT",
"playerId": 1276814678,
"characterId": "zeratu",
"gameServerUrl": "https://api.com2us.com/hive" //인증 토큰 전송 시: "gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."
"data": {
"itemId": "HIVE",
"attributes": [
{
"traitType": "item_id",
"value": "sward-3283272101239"
},
{
"traitType": "strength",
"value": "50"
},
{
"traitType": "agility",
"value": "10"
}
]
},
}'
Responses¶
Field Name | Description | Type |
---|---|---|
code | API call result code, 0: success | number |
message | Result message | string |
data | API response data | json |
data.webLinkId | Web link ID (UUID) | string |
data.webLinkUrl | Generated one-time web link (URL) | string |
data.expiration | Web link expiration date (ISO 8601) | string |
Response sample¶
{
"code": 0,
"message": "success",
"data": {
"webLinkid": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
"webLinkUrl": "https://sandbox-xpla-platform.withhive.com/api/v1/web-link/redirect?token=b256c85c-aee8-4837-b54d-9a03fe8a7435.f94140b71c9ebf058956547753131adde9968a0266f208d7e3059bbb6dd0c7bc",
"expiration": "2024-08-05T08:33:15.448Z"
}
}
Implementing the NFT issuance page with hive SDK¶
NFT issuance page link creation API The webpage URL received as a response is exposed to an external browser using Hive SDK.
Below is an example of the NFT issuance page.
Item information to be issued as NFT |
---|
![]() |
When you open the NFT issuance page, a window will appear for logging into the X-PLANET wallet or XLPA Vault. Users must select a specific wallet address to perform Mint or Burn after logging in to either the X-PLANET wallet or XLPA Vault.
Note
XPLA Vault is scheduled to be supported in June 2025.
X-PLANET | XPLA Vault |
---|---|
![]() | ![]() |
NFT minting (executing mint)¶
On the NFT issuance page, users select an item and then execute Mint.
Confirm commission before issuing NFT |
---|
![]() |
Item validation API call (hive blockchain server → game server)¶
Note
This API is not an API that the game server calls the Hive blockchain server, but rather an API that the Hive blockchain server calls the game server. Therefore, the game server must configure the API endpoint in the form desired by the Hive blockchain server.
Before converting game items to NFTs, the Hive blockchain server requests item verification from the game server. The Hive blockchain server issues the NFT on the blockchain after verifying the item information from the response provided by the game server. If the item verification fails, the Hive blockchain server does not issue the NFT.
Note
In the game server, until the NFT issuance result is received via the result confirmation API, the use of items that have been verified in the game should be restricted.
Notes¶
Here are some considerations for developers when configuring API endpoints.
Gameserverurl¶
This API requests verification from the game server using the gameServerUrl
requested from the NFT issuance page link creation API.
Authorization header¶
If the token
Query Parameter exists in the gameServerUrl
requested from the NFT issuance page link creation API, use this token
value in Bearer format.
Attributes¶
Includes attributes
in the API Request Body for generating the NFT issuance page link.
Request URL¶
The following is the API endpoint information that needs to be prepared on the game server.
Item | Value |
---|---|
URL | {gameServerUrl}/items/validate |
HTTP Method | POST |
Content-Type | application/json |
Header Parameters¶
Field Name | Description | Type | Required |
---|---|---|---|
Authorization | The authentication token sent as a token Query Parameter in the gameServerUrl of the NFT issuance page API. It is called in the form of Bearer ${token}. | Bearer | N |
User-Agent | HiveBlockchain/1.0 | string | Y |
Request Body¶
Field Name | Description | Type | Required |
---|---|---|---|
type | MINT | string | Y |
itemId | NFT item identifier code | string | Y |
playerId | Player ID | number | Y |
characterId | Character ID | string | N |
webLinkId | Web link ID (UUID) | string | Y |
tokenId | NFT ID | string | N |
attributes | Additional metadata properties to apply per token (for example, unique item code, strength, agility, etc. properties included in the NFT) | json array | N |
attributes.traitType | Item name that makes up attributes | string | N |
attributes.value | Trait value | string | N |
Request sample¶
curl -X 'POST' \
'https://api.com2us.com/hive/items/validate' \
-H 'accept: */*' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \ // 인증 토크 사용 시
-H 'User-Agent: HiveBlockchain/1.0' \
-d '{
"type": "MINT",
"itemId": "HIVE",
"playerId": 2319123897,
"characterId": "zeratu",
"webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
"attributes": [ // NFT 발행 페이지 링크 생성 시 attributes
{
"traitType": "item_id",
"value": "sward-3283272101239"
},
{
"traitType": "strength",
"value": "50"
},
{
"traitType": "agility",
"value": "10"
}
]
}'
Responses¶
The HTTP status codes are as follows.
- Success
- 200
- Failure
- 4xx: Error status codes for bad requests
- 5xx: Error status codes for server errors
Result check API call (hive blockchain → game server)¶
Note
This API is not an API that the game server calls the Hive blockchain server, but an API that the Hive blockchain server calls the game server. Therefore, the game server must configure the API endpoint in the form desired by the Hive blockchain server.
When the Hive blockchain server delivers the NFT issuance result to the game server in the Request Body, the game server processes it so that the item cannot be used in the game, and then delivers the result back to the Hive blockchain server through an API.
The actions the game server will perform based on the issuance results are as follows.
- NFT issuance successful
- Process to make the item unusable in the game (e.g., delete the item from the game user's inventory)
- NFT issuance failed
- Process to make the item usable in the game (e.g., lift usage restrictions to allow the item to be used again in the game user's inventory)
- Send NFT issuance failure results if the user cancels the NFT issuance or if a certain time limit is exceeded
Warning
You must restrict the use of the corresponding item in the game on the game server until you receive the NFT issuance result.
Below is an example of the NFT issuance page screen when the game server responds with a successful NFT issuance.
Notes¶
Here are some considerations for developers when configuring API endpoints.
Attributes¶
By including the unique item code in attributes
and calling the NFT issuance page link creation API, you can also include the unique code in the Request Body attributes
. In this case, you can update the item status with the corresponding unique code.
Authorization header¶
If the token
Query Parameter exists in the gameServerUrl
requested from the NFT issuance page link creation API, use this token
value in Bearer form.
Request URL¶
Item | Value |
---|---|
URL | {gameServerUrl}/items/callback |
HTTP Method | POST |
Content-Type | application/json |
Header Parameters¶
Field Name | Description | Type | Required |
---|---|---|---|
Authorization | The authentication token sent as a token Query Parameter in the NFT issuance page link creation API's gameServerUrl . It is called in the form of Bearer ${token}. | Bearer | N |
User-Agent | HiveBlockchain/1.0 | string | Y |
Request Body¶
Field Name | Description | Type | Required |
---|---|---|---|
type | MINT | string | Y |
itemId | NFT item identification code | string | Y |
playerId | Player ID | number | Y |
characterId | Character ID | string | N |
webLinkId | Web link ID (UUID) | string | Y |
tokenId | NFT ID (included in case of success) | string | N |
status | Transaction result (success, failure) | string | Y |
attributes | Additional metadata properties to apply per token (e.g., unique item code, strength, agility, etc. properties included in the NFT) | json array | N |
attributes.traitType | Name of the item that makes up attributes | string | N |
attributes.value | Trait value | string | N |
Request Sample¶
curl -X 'POST' \
'https://api.com2us.com/hive/items/callback' \
-H 'accept: */*' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \ // 인증 토크 사용 시
-H 'User-Agent: HiveBlockchain/1.0' \
-d '{
"type": "MINT",
"itemId": "HIVE",
"playerId": 2319123897,
"characterId": "zeratu",
"webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
"tokenId": "HIVE#348",
"status": "success",
"attributes": [ // NFT 발행 페이지 링크 생성 시 attributes
{
"traitType": "item_id",
"value": "sward-3283272101239"
},
{
"traitType": "strength",
"value": "50"
},
{
"traitType": "agility",
"value": "10"
}
]
}'
Responses¶
The HTTP status codes are as follows.
- Success
- 200
- Failure
- 4xx: Error status code for bad requests
- 5xx: Error status code for server errors