Hive Blockchain API (Blockchain Game API) is a standard API that supports the development of web 3 games of different genres.

It provides easy application of blockchain functions to games through the blockchain game API server for developing web 3 games.

Introduction

The blockchain game API provides the functions to exchange game currency for tokens or to create them. By the user’s request, the blockchain game API requests the game information to the game server and writes it on the blockchain. When using an blockchain game API that requires writing on the blockchain, you will receive an unsigned transaction (unsignedTx) as the response of a API. After signing this transaction, you can finally record the information you want on the blockchain through broadcasting.

  • Converting function that allows game currency to be exchanged for game tokens
  • Minting function that can issue game currency as NFT
  • Lock/unlock function that can lock/unlock issued NFTs
  • Burn function that can burn issued NFTs

Basic Requirements

  • You need to complete the setups for blockchain and game server API registration in the Hive console.
  • You need to receive an access token and send it when you call a blockchain game API.
  • You need to turn off the firewall so that the blockchain game API server can call your game server.
  • You need to get an authentication token (auth-token API) to call each API. There is a timeout, and when it expires, the authentication tokens are issued through re-authentication.

Authentication

auth-token

The API that issues authentication tokens required to use the blockchain game APIs.

  • Request URL
Commercial Server URL https://bc-platform-auth.withhive.com/v1/auth-token
Sandbox Server URL https://sandbox-bc-platform-auth.withhive.com/v1/auth-token
HTTP Method GET
Content-Type application/json
  • Request Body
Field Name Description Type Required
address The address of an account that can perform mint, burn, convert, and lock. string Y
secretKey The secret key required to use an API string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.accessToken The authentication token required to use an API string
data.refreshToken A token that is used to issue a new accessToken when the old accessToken is expired string
  • Request Sample
  • Response Sample

refresh-token

It is an API that uses the refresh token issued from the auth-token to issue a new authentication token required to use the blockchain game API when an access token expires.

  • Request URL
Commercial Server URL https://bc-platform-auth.withhive.com/v1/refresh-token
Sandbox Server URL https://sandbox-bc-platform-auth.withhive.com/v1/refresh-token
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization refreshToken required when calling an API string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.accessToken The authentication token required to use an API string
data.refreshToken A token that is used to issue a new accessToken when the old accessToken is expired string
  • Request Sample
  • Response Sample

Mint

mint/confirm

This API checks whether game assets (items/characters) can be minted and checks the minting fee and the metadata required for minting.

You can request the confirmation of issuance of NFT with the game asset information received from the game asset API. The blockchain game API calculates the minting fee based on the fee set in the Hive console, and makes a request to the game server to check that minting is available. The blockchain game API receives the metadata and whether the minting is available or not from the game developer, and delivers the result along with fee information.

  • API Task Flow

  • Request URL
    Commercial Server URL https://bc-platform-api.withhive.com/game/v1/mint/confirm
    Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/mint/confirm
    HTTP Method POST
    Content-Type application/json

     

  • Request Header
    Field Name Description Type Required
    Authorization the access token required when calling an API string Y
    appid the AppID of the game an user is logged into string Y
    pid player id after the hive login is successfully done string Y
    address a user’s xpla wallet address string Y

     

  • Request Body (the item and the token can be requested separately or together)
    Field Name Description Type Required
    Server the information of the game server (channel) string Y
    characterId the id of a game character string N
    categoryId the minting type (the single/joint minting of character or item) code, set in the Hive console number Y
    assets the list of game assets array depending on the condition
    assets.uniqueId the unique id of the item string
    assets.mintingFeeCode the fee required for minting number
    tokens token list array depending on the condition
    tokens.tokenId the id of the NFT item string
    tokens.mintingFeeCode the fee required for minting number

     

  • Response
    Field Name Description Type
    code api request result code, 0: success number
    message the result message string
    data API Response json
    data.governanceTokenFee the service fee string
    data.gameTokenFee the game fee string
    data.metadata.name metadata – the name of the item string
    data.metadata.description metadata – the description for the item string
    data.metadata.image metadata – the image of the item string
    data.metadata.animation_url metadata – the item’s animation address string
    data.metadata.youtube_url metadata – the YouTube address of the item string
    data.metadata.image_data metadata – the image data of the item string
    data.metadata.external_url metadata – the market registration address of the item string
    data.metadata.background_color Metadata – the background color of the item string
    data.metadata.attributes{} metadata – the attributes that were defined by the game studio array(json)
    data.metadata.attributes.trait_type metadata – attribute name string
    data.metadata.attributes.value metadata – value string
    data.requestId API request id string
    data.id the unique id of item/character string

     

  • data.metadata.attributes: details
trait_type Description value Required
category the categories of NFT items, Ex: Entertainment, Art, Game Game Y
collection a collection to classify NFT items of similar characteristics. NFT items from the same collection belong to the same category Summoners War Y
creator the creator or copyright holder of the NFT item Blueberry Studio Y
provider the provider who have the right to sell or distribute NFT items Com2uS Corp. Y
thumbnail_url A URL that provides the displayed thumbnail image for the NFT item list (580 x 580 size images are recommended, JPG: max. 300kB recommended / Gif: max. 5MB recommended) https://cdn.c2xnft.com/nft/item/f7MPrUmecf1648091769.jpg Y
file_type a value that identifies the file type and can be one of image, audio, video, or 3d. image Y
serial the serial number to distinguish each item when multiple NFT items are issued for the same content #1 N
serial_max the total amount issued when multiple NFT items are issued for the same content 100 N
series a series used to classify a collection into multiple categories. APPLEVERY series1 N
pack_name the name of the package that becomes the unit of sale APPLEVERY ZERO: FEVER EPILOGUE PACK N
pack_url a URL that provides multimedia that can be seen on the detail view of the package (580 x 580 size images are recommended, JPG: max. 300kB recommended / Gif: max. 5MB recommended) https://cdn.c2xnft.com/nft/item/xjQJEJWRFj1648091989.jpg N
rarity a rating for the value or rarity of an NFT item GOLD N
extension_url this is the url used when exposing a changeable value on an NFT item. the address cannot be changed. https://cdn.c2xnft.com/extensionUrlTest/dkTdfk32.json N
  • Request Sample

  • Response Sample

mint

the API that issues game assets (items/characters) as NFTs.

NFTs can be issued with the game assets that have been verified for NFT issuance. The blockchain game API split the fee based on the fee setting in the Hive console (Game Provider, Fan Card Holder, C2X Staking Holder, Convert Pool, Treasury). When the Minting API is called, the Hive blockchain server requests the game server to issue NFT. At this stage, the game assets are not issued as NFTs yet, so they should be locked or be processed to be locked. This API will create transactions required to make NFTs and deliver the results.

  • Additional Task
  1. The user signs the transaction received from the API.
  2. The user writes the signed tx to the blockchain through a broadcast API call.
  3. The game server should delete (deactivate) the game assets depending on the success/failure of the transaction.
  4. The users can find successfully issued NFTs in wallets or https://explorer.xpla.io.

 

  • API Task Flow

  • Request URL
    Commercial Server URL https://bc-platform-api.withhive.com/game/v1/mint
    Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/mint
    HTTP Method POST
    Content-Type application/json
  • Request Header
    Field Name Description Type Required
    Authorization the access token required when calling an API string Y
    appid the AppID of the game an user is logged into string Y
    pid player id after the Hive login is successfully done string Y
    address a user’s xpla wallet address string Y
  • Request Body
    Field Name Description Type Required
    server the information of the game server (channel) string Y
    characterId the id of a game character string N
    categoryId the classification code for items, characters, etc. number Y
    requestId the requestId returned from mint/confirm API string Y
    id the item/character unique ID returned from mint/confirm API string Y
    data.governanceTokenFee the service fee returned by mint/confirm API string Y
    data.gameTokenFee the game fee returned from mint/confirm API string Y
    metadata the metadata generated by the mint/confirm API string Y
  • Response
    Field Name Description Type
    code api request result code, 0: success number
    message the result message string
    data API Response json
    data.tokenId NFT ID string
    data.unsignedTx the unsigned transaction string
    data.tokenUri the address of metadata string
    data.requestId API request id string

 

  • Request Sample
  • Response Sample

Burn

The API to burn issued NFTs.

The users can burn the issued NFTs. Upon burning, the target NFT is checked and the game server is requested to burn it. At this stage, the NFT is not burnt yet, and the game server have to wait before it actually burns the NFT. This API create the transaction required for NFT burning and deliver the result.

  • Additional Task
  1. The user signs the transaction received from the API.
  2. The user writes the signed tx to the blockchain through a broadcast API call.
  3. The game server needs to handle the game assets based on whether the transaction is successful or unsuccessful.
  4. The users can find successfully issued NFTs in wallets or https://explorer.xpla.io.
  • API Task Flow

  • Request URL
    Commercial Server URL https://bc-platform-api.withhive.com/game/v1/burn
    Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/burn
    HTTP Method POST
    Content-Type application/json

     

  • Request Header
    Field Name Description Type Required
    Authorization the access token required when calling an API string Y
    appid the AppID of the game an user is logged into string Y
    pid player id after the Hive login is successfully done string Y
    address a user’s xpla wallet address string Y

     

  • Request Body
    Field Name Description Type Required
    server the information of the game server (channel) string Y
    characterId the id of a game character string N
    tokenId NFT ID string Y

     

  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.unsignedTx the unsigned transaction string
data.requestId API request id string
  • Request Sample

  • Response Sample

Convert

convert/currency

This API retrieves the information of the game currency and the coins (tokens) held by users, and their minimum and maximum quantities that can be converted.

  • the API task flow (the API server in the picture -> the blockchain game API server)

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/convert/currency
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/convert/currency
HTTP Method GET
Content-Type application/json

 

  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
pid player id after the Hive login is successfully done string Y
address a user’s xpla wallet address string Y

 

  • Request Query String
Field Name Description Type Required
characterId the character id selected in the game where a user is logged into string Y
server the DID returned after successful login string Y
  • Response

\wiki\pages\viewpage.action

Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.server the server information string
data.pid the player id string
data.providerAddress the game provider’s wallet address string
data.tokenContract the game token contract address string
data.currency the information of coin/token and game currency array(json)
data.currency.convertTypeCd the type of currency. the primary currency and the secondary currency. string
data.currency.goodsName the name of the game currency string
data.currency.goodsCode the code of the game currency string
data.currency.goodsImge the image of the game currency string
data.currency.minConvertQuantityOneTime the minimum amount of game currency that can be exchanged per time number
data.currency.maxConvertQuantityDays the maximum amount of game currency that can be exchanged per day number
data.currency.tokenName the coin/token name string
data.currency.tokenImage the coin/token image string
data.currency.tokenAmount the amount of coins/tokens held json
data.currency.tokenAmount.tokenSymbol the coin/token symbol string
data.currency.tokenAmount.decimals the decimal places of coin/token number
data.currency.tokenAmount.amount the amount of coins held string
data.currency.currencyAmount the quantity of game currency held string
data.currency.avalibleAmount the quantity of game currency that can be exchanged string

 

  • Request Sample
  • Response Sample

convert/simul-to-currency

This API retrieves the expected ratio and expected quantity according to the ratio stored in the conversion pool when converting coins/tokens to game currency (primary or secondary).

  • the API task flow (the API server in the picture -> the blockchain game API server)

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/convert/simul-to-currency
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/convert/simul-to-currency
HTTP Method POST
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
pid player id after the Hive login is successfully done string Y
address a user’s xpla wallet address string Y
  • Request Body
Field Name Description Type Required
convertTypeCd the code of the currency type. the primary currency and the secondary currency. string Y
amount the amount of coins/tokens to be converted string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.result the retrieved results about the convert pool number
data.ratio the convert ratio number
data.value the quantity of game currency generated from the conversion number
data.expected_return_amount the expected quantity of game currency generated from the conversion number
data.expected_offer_amount the expected amount of coins/tokens to be converted number
  • Request Sample
  • Response Sample

convert/to-currency

This API changes coins/tokens into game currency (primary, secondary).

It checks the exchangeable quantity and exchange ratio, and transfers coins/tokens from the user’s wallet address to the Provider address.

  • Additional Task
  1. The user signs the transaction delivered from the API.
  2. The user calls the broadcast API to write the signed transaction to the blockchain.
  3. The game server should increase the game currency depending on whether the transaction is successful or not.
  4. The tokens that have been processed successfully can be found at https://explorer.xpla.io.

 

  • the API task flow (the API server in the picture -> the blockchain game API server)

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/convert/to-currency
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/convert/to-currency
HTTP Method POST
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
pid player id after the Hive login is successfully done string Y
address a user’s xpla wallet address string Y
  • Request Body
Field Name Description Type Required
server the server information string Y
characterId the character ID to receive game currency upon conversion string Y
convertTypeCd the code of the currency type. the primary currency and the secondary currency. string Y
amount the amount of coins/tokens to be converted String Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.requestId the unique value of api string
data.unSignedTx { “unsignedTx”: “ string
data.appId app id string
data.pid the player id string
data.address the user wallet address string
data.server the game server information string
data.characterId the game character unique id string
data.convertTypeCd the type of currency. the primary currency and the secondary currency. string
data.inputAmount the amount of input coins/tokens string
data.amount the amount of coins/tokens requested to be converted string
data.convertCurrencyAmount the quantity of game currency generated from the conversion string
  • Request Sample
  • Response Sample

convert/simul-to-token

This API retrieves the expected ratio and expected quantity according to the ratio stored in the conversion pool when converting game currency (primary or secondary) to coins/tokens.

  • the API task flow (the API server in the picture -> the blockchain game API server)

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/convert/simul-to-token
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/convert/simul-to-token
HTTP Method POST
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
pid player id after the Hive login is successfully done string Y
address a user’s xpla wallet address string Y
  • Request Body
Field Name Description Type Required
convertTypeCd the code of the currency type. the primary currency and the secondary currency. string Y
amount the quantity of game currency to be converted string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.result the retrieved results about the convert pool number
data.ratio the convert ratio number
data.value the token quantity generated from the conversion number
data.expected_return_amount the expected quantity of game currency to be converted number
data.expected_offer_amount the expected amount of coins/tokens generated from the conversion number
  • Request Sample
  • Response Sample

convert/to-token

This API changes game currency (primary, secondary) into coins/tokens.

It checks the exchangeable quantity and exchange ratio, reduces the game currency from the user’s game character, and transfers coins/tokens from the Provider wallet to the user’s wallet address.

  • Additional Task
  1. The user signs the transaction received from the API.
  2. The user calls the broadcast API to write the signed transaction to the blockchain.
  3. The successfully converted tokens can be found at the wallet or https://explorer.xpla.io.
  • the API task flow (the API server in the picture -> the blockchain game API server)

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/convert/to-token
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/convert/to-token
HTTP Method POST
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
pid player id after the Hive login is successfully done string Y
address a user’s xpla wallet address string Y
  • Request Body
Field Name Description Type Required
server the server information string Y
characterId the character ID to reduce game currency upon conversion string Y
convertTypeCd the code of the currency type. the primary currency and the secondary currency. string Y
amount the quantity of game currency to be converted string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.requestId the unique value of api string
data.appId app id string
data.txHash the transaction hash value string
data.server the server information string
data.pid the player id string
data.characterId the game character unique id string
data.address the user wallet address string
 data.convertTypeCd the type of currency. the primary currency and the secondary currency. string
data.amount the input quantity of game currency string
data.convertTokenAmount the amount of coins/tokens generated from the conversion string
  • Request Sample
  • Response Sample

Lock/unlock

lock/nft-list

This API queries the list of NFTs that are locked.

  • the API task flow (the API server in the picture -> the blockchain game API server)

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/nft-list
Sandbox URL https://sandbox-bc-platform-api.withhive.com/game/v1/nft-list
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
address a user’s xpla wallet address string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.address the user wallet address string
data.lockedNft the list of locked NFTs array(json)
data.lockedNft.owner the owner of the token string
data.lockedNft.nft_address the NFT contract address string
data.lockedNft.token_id the token ID string
data.lockedNft.lock_info the token URL string
  • Request Sample
  • Response Sample

lock

This API locks the NFTs you are holding.

To use the game assets that were already issued as NFTs in the game again, lock the NFTs so that they cannot be traded. The users will transfer their NFTs to the lock contract and then they can use these game assets. They cannot transfer these NFTs to other wallets.

  • Additional Task
  1. The user signs the transaction received from the API.
  2. The user writes the signed tx to the blockchain through a broadcast API call.
  3. The game server needs to create (enable) the game assets based on whether the transaction is successful or unsuccessful.
  • the API task flow (the API server in the picture -> the blockchain game API server)

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/lock
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/lock
HTTP Method POST
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
pid player id after the Hive login is successfully done string Y
address a user’s xpla wallet address string Y
  • Request Body
Field Name Description Type Required
server the server information string Y
characterId the character ID to receive game currency upon conversion string Y
tokenId the token id to be locked string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.requestId the unique value of api string
data.tokenId the unique id of the NFT string
data.nftContract the NFT contract address string
data.unSignedTx { “unsignedTx”: “ string
  • Request Sample
  • Response Sample

unlock

This API unlocks the NFTs you are holding.

It makes the game assets that are used in the game be NFTs that can be traded again. This API disable the user’s game assest, and send this NFT (the game asset) back to the user’s wallet.

  • Additional Task
  1. The user signs the transaction received from the API.
  2. The user writes the signed tx to the blockchain through a broadcast API call.
  3. The game server should delete (deactivate) the game assets depending on the success/failure of the transaction.
  4. The users can find the unlocked NFTs in the wallets or https://explorer.xpla.io.

 

  • the API task flow (the API server in the picture -> the blockchain game API server)

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/unlock
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/unlock
HTTP Method POST
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
pid player id after the Hive login is successfully done string Y
address a user’s xpla wallet address string Y
  • Request Body
Field Name Description Type Required
server the server information string Y
characterId the character ID to receive game currency upon conversion string Y
tokenId the token id to be locked string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.requestId the unique value of api string
data.tokenId the unique id of the NFT string
data.nftContract the NFT contract address string
data.txHash the transaction hash information json
data.txHash.height the block height information, 0: Normal number
data.txHash.txhash the transaction hash value string
data.txHash.raw_log log info, []: normal string
  • Request Sample
  • Response Sample

Transaction

broadcast

This API writes the signed transactions on the blockchain. The Convert, Lock, Mint, and Burn API require the user’s signature to be recorded on the blockchain.

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/broadcast
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/broadcast
HTTP Method POST
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
  • Request Body
Field Name Description Type Required
requestId the unique value of the transaction (for db storage) string Y
signedTx the encoded value of the signed transaction string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.height the block height information, 0: Normal number
data.txhash the transaction hash value string
data.raw_log log info, []: normal string
  • Request Sample
  • Response Sample

tx

This API retrieves the transaction information recorded in the blockchain. After the broadcast API is called, you can retrieve the information with the generated transaction hash to identify the transaction.

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/tx
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/tx
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
  • Request Body
Field Name Description Type Required
txHash the transaction hash value of the blockchain String Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.error the indicator that an error occurred boolean
data.code transaction status code , 0: OK number
  • Request Sample
  • Response Sample

Game

channels

This API retrieves the game channel information.

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/channels
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/channels
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
  • Request Body
Field Name Description Type Required
server the server information string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response array(json)
data.channelName the channel name string
data.channelId the channel ID string
  • Request Sample
  • Response Sample

maintenance

If a notice/notification is set for the games registered in Hive, this API retrieves that notice/notification.

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/server/{server}/maintenance
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/server/{server}/maintenance
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
  • Request Body
Field Name Description Type Required
server the server information string Y
appid the AppID of the game an user is logged into string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.type the type of notification (1: server maintenance, 2: forced update, 3: general notice) string
data.action the action for a button. this value exists only if there is a buttonlist (1: a URL, 2: forced closing, 3: closing window) string
data.url this value exists only when the URL and the buttonlist exist (the target URL for an action, “” if action is not 1). string
data.startDate the maintenance start date string
data.endDate the maintenance end date string
data.remainingTime the time remaining until the end of maintenance string
data.title the title string
data.message the message detail string
data.button the button text string
data.buttonLists the button list array(json)
data.buttonLists.action the action for a button. this value exists only if there is a buttonlist (1: a URL, 2: forced closing, 3: closing window) string
data.buttonLists.url this value exists only when the URL and the buttonlist exist (the target URL for an action, “” if action is not 1). string
data.buttonLists.button the button text string
  • Request Sample
  • Response Sample

category

This API retrieves the minting category group information. The minting is available depending on whether the category is enabled or not. For example, the code for the active category could be 1001000601 and the code for the inactive category could be 1001000602. The category consists of the single minting, the joint minting, and the character minting by the minting type. For example, the single minting could be 1001000701, the joint minting could be 1001000702, and the character minting could be 1001000703.

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/mint/category
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/mint/category
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response array(json)
data.id the unique identification number number
data.activeTypeCd the activation status (active: 1001000601, inactive: 1001000602) string
data.mintTypeCd the minting type (single minting: 1001000701, joint minting: 1001000702, character minting: 1001000703) string
data.name the category name string
  • Request Sample
  • Response Sample

category/fee

This API retrieves the fee information which was set by the minting category. The fee required for minting can be set by the code.

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/mint/category/{categoryId}/fee
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/mint/category/{categoryId}/fee
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
  • Request Body
Field Name Description Type Required
categoryId the category ID by the minting type string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response array(json)
data.nativeTokenFee the minting fee in token (CTXT) string
data.gameTokenFee the game token fee required for minting (active: 1001000601, inactive: 1001000602) string
data.mintCount the fee based on the minting count (the minting fee code) string
  • Request Sample
  • Response Sample

convert/type

This API queries the configuration information of the conversion between tokens and game currency. For each conversion type, it retrieves the exchangeable token, the game currency information, and exchange policy information.

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/convert/type
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/convert/type
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
appid the AppID of the game an user is logged into string Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response array(json)
data.convertTypeCd the convert type token (CTX <=> game currency): 1001000801, the game token (game token <=> game currency): 1001000802 string
data.goodsName the name of the game currency string
data.goodsCode the code of the game currency string
data.goodsImage the icon image of the game currency string
data.maxConvertQuantityDays the maximum amount that can be exchanged per day number
data.minConvertQuantityOneTime the minimum amount that can be exchanged per time number
  • Request Sample
  • Response Sample

betagames

This API queries the blockchain games registered through the beta game launcher. The game is exposed depending on the configurations and API setup made in the Hive console.

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/betagames
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/betagames
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
  • Request Parameters
Field Name Description Type Required
page the page information number Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.betagames the beta game information array(json)
data.betagames.gameindex the unique number for the game string
data.betagames.appid the registered and issued appId in the Hive console > AppCenter string
data.betagames.title the game name by language, registered in the Hive array(json)
data.betagames.title.language the language information for the game name string
data.betagames.title.name the game name by language string
data.betagames.iconImage the address of the icon image string
data.betagames.genre the character selection (0: not selected, 1: selected) number
data.betagames.characterSelect the game genre string
data.betagames.gameTokenName the name of the token issued by your game string
data.betagames.gameTokenImage the image of the token issued in the game string
data.betagames.settingCompleteTypeCd the indicator for the completion of the Hive console settings string
data.betagames.apiSettingCompleteTypeCd the indicator for the completion of the Hive console API settings string
data.betagames.mintActiveTypeCd the activation status of the single minting (active: 1001000601, inactive: 1001000602) string
data.betagames.unionMintActiveTypeCd the activation status of the joint minting (active: 1001000601, inactive: 1001000602) string
data.betagames.charMintActiveTypeCd the activation status of the character minting (active: 1001000601, inactive: 1001000602) string
data.betagames.androidDownLink the Android download link string
data.betagames.iosDownLink the iOS download link string
data.betagames.pcDownLink the PC download link string
data.betagames.gameServerLists the game server information array(json)
data.betagames.gameServerLists.serverId the unique id of the server string
data.betagames.gameServerLists.serverNameKO the server name (Korean) string
data.betagames.gameServerLists.serverNameEN the server name (English) string
data.betagames.gameServerLists.timezone the server time zone string
data.meta.totalItems the total number of items number
data.meta.currentPage the information of the current page number
data.meta.totalPages the total number of pages number
  • Request Sample
  • Response Sample

characters

This API retrieves the character information.

The blockchain game API requests the character information to the game server and delivers the results.

  • API Task Flow

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/characters
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/characters
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
pid player id after the Hive login is successfully done string Y
  • Request Parameters
Field Name Description Type Required
server the information of the game server (channel) String Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.characters the unique number for the game array(json)
data.characters.characterName the character name string
data.characters.characterId the character ID string
  • Request Sample
  • Response Sample

assets

This API retrieves the game assets (item/character) that can be minted.

It requests the list of game assets that can be minted from the game server. Each game asset is categorized by the minting type (single, joint, character minting) and also by the category code (category id), which are set in the Hive console. The game server should return the fee code (mintingFeeCode) set in the Hive console.

  • API Task Flow

  • Request URL
Commercial Server URL https://bc-platform-api.withhive.com/game/v1/mint/items
Sandbox Server URL https://sandbox-bc-platform-api.withhive.com/game/v1/mint/items
HTTP Method GET
Content-Type application/json
  • Request Header
Field Name Description Type Required
Authorization the access token required when calling an API string Y
pid player id after the Hive login is successfully done string Y
address a user’s xpla wallet address string Y
  • Request Parameters
Field Name Description Type Required
server the information of the game server (channel) string Y
characterId the id of a game character string N
categoryId the category code to distinguish the minting type for each game number Y
  • Response
Field Name Description Type
code api request result code, 0: success number
message the result message string
data API Response json
data.assets the list of game assets array(json)
data.assets.name the name of the game asset string
data.assets.description the description for the game asset string
data.assets.uniqueId the unique ID of the game asset, designated as the the token ID when issuing the NFT string
data.assets.nftStatus the NFTs issuance of the game assets string
data.assets.tokenId the token ID if issued as a token from a game asset string
data.assets.mintingFeeCode the fee code required when minting game assets number
  • Request Sample
  • Response Sample

Error Codes

Code Description
1002 API request failed
1003 The information retrieval about beta game failed.
1004 An error occurred on the server.
1005 An error occurred when calling an external service.
1006 Incomplete API setup in the Hive console.
4000 The validity check failed when minting a game asset
4001 Failed to mint the NFT from the game asset.
4002 Invalid minting fee
4003 Unable to retrieve the game currency
4004 Failed to burn the NFT that was issued from the game asset.
4005 Tried to issue the NFT that already exists.
4006 Tried to burn the NFT that does not exist.
4007 Insufficient tokens to pay for minting fee.
4008 Unable to mint. The minting settings are not set in the Hive console, or it is in deactivated status.
4009 The minting category has not been set.
4010 Incorrect token information is requested.
5000 An error occurred in the server.
5001 Failed to retrieve the game currency information.
5002 Incorrect input quantity & The quantity is below 0.
5003 Input quantity is greater than the quantity currently held.
5004 Input quantity is less than the minimum exchange quantity.
5005 Input quantity is greater than the maximum exchange quantity.
5006 Input quantity is less than the quantity currently held.
5007 Incorrect operator address sequence.
5008 Failed to retrieve the valid game token contract information.
5009 Failed to retrieve the valid information from the Hive console.
5010 Failed to retrieve the valid game currency information from the game server.
5011 Failed to update the game currency information in the game server.
5012 Failed to retrieve the valid convert pool information
5013 Failed to broadcast the conversion transaction to Hive blockchain server
5014 Failed to retrieve the valid operatore address key
5100 Failed to upload digital assets.
5101 Failed to upload digital assets via URL.
5200 Failed to upload metadata.
6000 An error occurred in the server.
6001 Failed to get NFT information from the contract that locks NFT.
6002 Failed to retrieve the valid list of lock NFTs when calling unlock API.
6003 The owner of the NFT is incorrect.
6004 An error occurred in Unlock API.
6005 Failed to retrieve the valid information of the locked NFT contract owner.
6006 Failed to sign the contract that locks an NFT.
9003 Failed to create the transaction.
9004 Failed to sign the transaction.
9005 Unable to retrieve the xpla balance.
9006 Unable to retrieve the cw20 balance.
9007 An error occurred in transferring xpla.
9008 An error occurred in transferring token.
9009 An error occurred in minting NFT.
9010 An error occurred in burning NFT.
9011 An error occurred in retrieving the held NFT list.
9012 An error occurred in retrieving the details of an NFT.
9013 Failed to transfer the NFT (transfer, wallet->wallet)
9014 Failed to transfer the NFT (send, wallet->contract)
9015 An error occurred in locking NFT.
9016 An error occurred in unlocking NFT.
9017 An error occurred in creating the transaction that unlocks NFT.
9018 An error occurred in retrieving the locked NFT list.
9019 An error occurred in retrieving the transaction status.
9999 An error occurred in broadcasting the transaction.