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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-auth.withhive.com/v1/auth-token' \ -H 'accept: */*' \ -H 'Content-Type: application/json' \ -d '{ "address": "xpla19pwda2lut9xaefr8gsmgktuqew90sc5ajlxhkg", "secretKey": "1234"}' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzM4MjY5NSwiZXhwIjoxNjY3NDY5MDk1fQ.xRq3ew5GAcn0zEcTEyRAXByjAbhgRQb3aWqaxy_iQ68", "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzM4MjY5NSwiZXhwIjoxNjY3OTg3NDk1fQ.s8dL3tCwdbHUTQnWqAWbDSaGumKF3Jc_aYXVJUp1VxQ" }} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-auth.withhive.com/v1/refresh-token' \ -H 'accept: */*' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzQ3MTE4NywiZXhwIjoxNjY4MDc1OTg3fQ.wj0r0w2DH1aua02qKp_qApSBXVcMDRyvdprhM5XE0pM' |
- Response Sample
|
1 |
{ "code": 1000, "message": "success", "data": { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzQ3MTIwMSwiZXhwIjoxNjY3NTU3NjAxfQ.icFnROeEU7RI0FvEdPR5Oa26YqEihwcBN-KT_n_iq_o", "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzQ3MTIwMSwiZXhwIjoxNjY4MDc2MDAxfQ.fclh8qVxLRG0Z1Fn2KRtW7Dmm6KFY5H4jvRSroy-mag" }} |
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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/mint/confirm' \ -H 'accept: application/json' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'address: xpla1h086yrxdzhgqzftk2hzcgst9gywttqd2d32g6q' \ -H 'pid: 1234' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzM4NzYzOSwiZXhwIjoxNjY3NDc0MDM5fQ.JeU7Y3IcaY35yc0w1jK3OVWzD5kHrTpLztcc4arQt-o' \ -H 'Content-Type: application/json' \ -d '{ "server": "1,1,1", "characterId": "test", "categoryId": 520, "items": [ { "uniqueId": "itemUniqCode1", "mintingFeeCode": 0 } ], "tokens": [ { "tokenId": "84039", "mintingFeeCode": 2 } ]}' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "governanceTokenFee": "0.000700000000000000", "gameTokenFee": "0.000700", "metadata": { "name": "Fire Lord's Helmet", "description": "[UR] Fire Lord's Helmet\nKnight [Head]\nCraft Count: 0/5\nMain Stat\nDEF: 182044\nEVA: 46948\n[R] Fire Lord's Essence\n[Lv. 1] Increases damage, healing, and Barrier absorption of Fire skills by 12%.\n[Lv. 10] Increases damage/healing/Barrier absorption of the next Fire skill by 6% when a Fire skill is used.\n", "image": "https://image01.c2x.world/equip_93041010.gif", "animation_url": "https://image01.c2x.world/equip_93041010.gif", "youtube_url": "", "image_data": "", "external_url": "https://dex.c2xnft.com/market?key=4838", "background_color": "", "attributes": [ { "trait_type": "Category", "max_value": "", "value": "Game", "display_type": "" } ] }, "requestId": "fd20d928-8f60-41dd-9595-8f6ca52484ad", "id": "unique-id-7immqv" }} |
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
- The user signs the transaction received from the API.
- The user writes the signed tx to the blockchain through a broadcast API call.
- The game server should delete (deactivate) the game assets depending on the success/failure of the transaction.
- 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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/mint' \ -H 'accept: application/json' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'address: xpla1h086yrxdzhgqzftk2hzcgst9gywttqd2d32g6q' \ -H 'pid: 1234' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzQ0ODE1MSwiZXhwIjoxNjY3NTM0NTUxfQ.9XmjT6h-A9qTs7c3ia7fPRrHCizccRRX3XaK_qErEs4' \ -H 'Content-Type: application/json' \ -d '{ "server": "1,1,1", "characterId": "com2us", "categoryId": 520, "requestId": "fd20d928-8f60-41dd-9595-8f6ca52484ad", "id": "unique-id-7immqv", "data.governanceTokenFee": "0.000700000000000000", "data.gameTokenFee": "0.000700", "metadata": { "name": "Fire Lord'\''s Helmet", "description": "[UR] Fire Lord'\''s Helmet\nKnight [Head]\nCraft Count: 0/5\nMain Stat\nDEF: 182044\nEVA: 46948\n[R] Fire Lord'\''s Essence\n[Lv. 1] Increases damage, healing, and Barrier absorption of Fire skills by 12%.\n[Lv. 10] Increases damage/healing/Barrier absorption of the next Fire skill by 6% when a Fire skill is used.\n", "image": "https://image01.c2x.world/equip_93041010.gif", "animation_url": "https://image01.c2x.world/equip_93041010.gif", "youtube_url": "", "image_data": "", "external_url": "https://dex.c2xnft.com/market?key=4838", "background_color": "", "attributes": [ { "trait_type": "Category", "max_value": "", "value": "Game", "display_type": "" } ] }}' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "tokenId": "unique-id-7immqv", "unsignedTx": "CrsPCpIDCiQvY29zbXdhc20ud2FzbS52MS5Nc2dFeGVjdXRlQ29udHJhY3QS6QIKK3hwbGExOXB3ZGEybHV0OXhhZWZyOGdzbWdrdHVxZXc5MHNjNWFqbHhoa2cSP3hwbGExNWszdmFtendsMzB0eHl2cGU1Zjh4NmZkZWxoN3djZXZ3d3gzeHJ3OHB3amowaGd4d2tzcXc0M3NmZhr4AXsibWludCI6eyJzZW5kZXJBZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsInRva2VuX2lkIjoidW5pcXVlLWlkLTdpbW1xdiIsIm93bmVyIjoieHBsYTFoMDg2eXJ4ZHpoZ3F6ZnRrMmh6Y2dzdDlneXd0dHFkMmQzMmc2cSIsInRva2VuX3VyaSI6Imh0dHA6Ly8zNC42NC4xNDUuMTgyOjgwODAvaXBmcy9RbWZHR0FzMU5QNWJzZkFvM1FtWTczSEdhY29Ta0tKeml6VGRZb2o2OXNRTDN0In19CpQBChwvY29zbW9zLmJhbmsudjFiZXRhMS5Nc2dTZW5kEnQKK3hwbGExaDA4NnlyeGR6aGdxemZ0azJoemNnc3Q5Z3l3dHRxZDJkMzJnNnESK3hwbGExNnY2eTQ4eGxsd3k3YW1jbXZoa3YwYTN6cDdqZXBsNDR5dmh2eHQaGAoFYXhwbGESDzM1MDAwMDAwMDAwMDAwMAqUAQocL2Nvc21vcy5iYW5rLnYxYmV0YTEuTXNnU2VuZBJ0Cit4cGxhMWgwODZ5cnhkemhncXpmdGsyaHpjZ3N0OWd5d3R0cWQyZDMyZzZxEit4cGxhMWdkenNrZDR2MnFqNDA0YTI4OGR4anlwcmV3a3F2cjh4N2NmM3A3GhgKBWF4cGxhEg8xMTIwMDAwMDAwMDAwMDAKkwEKHC9jb3Ntb3MuYmFuay52MWJldGExLk1zZ1NlbmQScworeHBsYTFoMDg2eXJ4ZHpoZ3F6ZnRrMmh6Y2dzdDlneXd0dHFkMmQzMmc2cRIreHBsYTFuMzVzZ3AyY21zNWt6MnZ5cnQzZXVzdThkNTlqdGp2dDJlZmhkYxoXCgVheHBsYRIOMjgwMDAwMDAwMDAwMDAKlAEKHC9jb3Ntb3MuYmFuay52MWJldGExLk1zZ1NlbmQSdAoreHBsYTFoMDg2eXJ4ZHpoZ3F6ZnRrMmh6Y2dzdDlneXd0dHFkMmQzMmc2cRIreHBsYTF3ank5cWhrcWg2a3ZmbjB5MDZucGVyZ2x5NGo3MDZkem5ubTh6MBoYCgVheHBsYRIPMjEwMDAwMDAwMDAwMDAwCvABCiQvY29zbXdhc20ud2FzbS52MS5Nc2dFeGVjdXRlQ29udHJhY3QSxwEKK3hwbGExaDA4NnlyeGR6aGdxemZ0azJoemNnc3Q5Z3l3dHRxZDJkMzJnNnESP3hwbGExaGtjcDhhdnpjaGVodnQ1eTgzNzNhYzB4eXFrbHo2eWFseXoycTJ0MjhrMHFwdnBrZXl6c3ZncWY2cxpXeyJ0cmFuc2ZlciI6eyJyZWNpcGllbnQiOiJ4cGxhMTlwd2RhMmx1dDl4YWVmcjhnc21na3R1cWV3OTBzYzVhamx4aGtnIiwiYW1vdW50IjoiMzUwIn19CvABCiQvY29zbXdhc20ud2FzbS52MS5Nc2dFeGVjdXRlQ29udHJhY3QSxwEKK3hwbGExaDA4NnlyeGR6aGdxemZ0azJoemNnc3Q5Z3l3dHRxZDJkMzJnNnESP3hwbGExaGtjcDhhdnpjaGVodnQ1eTgzNzNhYzB4eXFrbHo2eWFseXoycTJ0MjhrMHFwdnBrZXl6c3ZncWY2cxpXeyJ0cmFuc2ZlciI6eyJyZWNpcGllbnQiOiJ4cGxhMWdkenNrZDR2MnFqNDA0YTI4OGR4anlwcmV3a3F2cjh4N2NmM3A3IiwiYW1vdW50IjoiMTEyIn19Cu8BCiQvY29zbXdhc20ud2FzbS52MS5Nc2dFeGVjdXRlQ29udHJhY3QSxgEKK3hwbGExaDA4NnlyeGR6aGdxemZ0azJoemNnc3Q5Z3l3dHRxZDJkMzJnNnESP3hwbGExaGtjcDhhdnpjaGVodnQ1eTgzNzNhYzB4eXFrbHo2eWFseXoycTJ0MjhrMHFwdnBrZXl6c3ZncWY2cxpWeyJ0cmFuc2ZlciI6eyJyZWNpcGllbnQiOiJ4cGxhMW4zNXNncDJjbXM1a3oydnlydDNldXN1OGQ1OWp0anZ0MmVmaGRjIiwiYW1vdW50IjoiMjgifX0K8AEKJC9jb3Ntd2FzbS53YXNtLnYxLk1zZ0V4ZWN1dGVDb250cmFjdBLHAQoreHBsYTFoMDg2eXJ4ZHpoZ3F6ZnRrMmh6Y2dzdDlneXd0dHFkMmQzMmc2cRI/eHBsYTFoa2NwOGF2emNoZWh2dDV5ODM3M2FjMHh5cWtsejZ5YWx5ejJxMnQyOGswcXB2cGtleXpzdmdxZjZzGld7InRyYW5zZmVyIjp7InJlY2lwaWVudCI6InhwbGExcXNyd3c1dGcyY2xkZThmOHNjcjBjNXBldjZuc2R6c3QzNGxkaHEiLCJhbW91bnQiOiIyMTAifX0SfgpZCk8KKC9ldGhlcm1pbnQuY3J5cHRvLnYxLmV0aHNlY3AyNTZrMS5QdWJLZXkSIwohA1sEfoFt+jL+4LSZHKF5oVrFYGQOVY/QsqpxJDt4nZtoEgQKAgh/GDwSIQobCgVheHBsYRISODQ1NDc3MTUwMDAwMDAwMDAwEPfaPBpAiy889zaFpq0dJCoRPIrtcQzAUYKC/+ZHzcuHBX9qld9ogtcbHq06+Kn3O7tOxfHfSBCJFKkGb+BUWpn/kVaLjA==", "tokenUri": "http://34.64.145.182:8080/ipfs/QmfGGAs1NP5bsfAo3QmY73HGacoSkKJzizTdYoj69sQL3t", "requestId": "fd20d928-8f60-41dd-9595-8f6ca52484ad" }} |
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
- The user signs the transaction received from the API.
- The user writes the signed tx to the blockchain through a broadcast API call.
- The game server needs to handle the game assets based on whether the transaction is successful or unsuccessful.
- 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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/burn' \ -H 'accept: application/json' \ -H 'address: xpla1h086yrxdzhgqzftk2hzcgst9gywttqd2d32g6q' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'pid: 1234' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzQ0ODE1MSwiZXhwIjoxNjY3NTM0NTUxfQ.9XmjT6h-A9qTs7c3ia7fPRrHCizccRRX3XaK_qErEs4' \ -H 'Content-Type: application/json' \ -d '{ "characterId": "com2us", "tokenId": "unique-id-7immqv", "server": "1,1,1"}' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "unsignedTx": "CsQBCsEBCiQvY29zbXdhc20ud2FzbS52MS5Nc2dFeGVjdXRlQ29udHJhY3QSmAEKK3hwbGExaDA4NnlyeGR6aGdxemZ0azJoemNnc3Q5Z3l3dHRxZDJkMzJnNnESP3hwbGExNWszdmFtendsMzB0eHl2cGU1Zjh4NmZkZWxoN3djZXZ3d3gzeHJ3OHB3amowaGd4d2tzcXc0M3NmZhooeyJidXJuIjp7InRva2VuX2lkIjoidW5pcXVlLWlkLTdpbW1xdiJ9fRIjEiEKGwoFYXhwbGESEjIwNDgxNTM2MjUwMDAwMDAwMBC/2g4=", "requestId": "dc9598ce-f835-47b2-834b-4e2402afc308" }} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/v1/convert/currency?characterId=1&server=1%2C1%2C1' \ -H 'accept: application/json' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'pid: 234' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzQ0ODE1MSwiZXhwIjoxNjY3NTM0NTUxfQ.9XmjT6h-A9qTs7c3ia7fPRrHCizccRRX3XaK_qErEs4' \ -H 'address: xpla1ps6r4ja93a64lwn4gh0yhjt9rlnk0me0ef4djs' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "server": "1,1,1", "pid": "234234", "characterId": "1", "providerAddress": "xpla1e6lczuu7n46xqy7gnkf3qkupdsteqz0tp50tcp", "tokenContract": "xpla1hkcp8avzchehvt5y8373ac0xyqklz6yalyz2q2t28k0qpvpkeyzsvgqf6s", "currency": [ { "convertTypeCd": "1001000801", "goodsName": "gold", "goodsCode": "goldcode", "goodsImage": "https://c2xnft.qpyou.cn/blockchain-sdk/blockchain/48479951-8fc3-7aa5-b2a8-433c312a30d2.png", "minConvertQuantityOneTime": 10, "maxConvertQuantityDays": 10000, "tokenName": "CTXT", "tokenImage": "https://assets.xpla.io/icon/CTXT.png", "tokenAmount": { "tokenName": "CTXT", "tokenSymbol": "CTXT", "decimals": 6, "amount": "999904.244998" }, "currencyAmount": "2000", "avalibleAmount": "10000" }, { "convertTypeCd": "1001000802", "goodsName": "crystal", "goodsCode": "crystalcode", "goodsImage": "https://c2xnft.qpyou.cn/blockchain-sdk/blockchain/48479951-8fc3-7aa5-b2a8-433c312a30d2.png", "minConvertQuantityOneTime": 10, "maxConvertQuantityDays": 10000, "tokenName": "CPBC", "tokenImage": "https://c2xnft.qpyou.cn/blockchain-sdk/blockchain/7b60c566-8c65-2dac-876d-fb3be3ce8eed.png", "tokenAmount": { "tokenName": "cp-bc-test", "tokenSymbol": "cpbc", "decimals": 6, "amount": "4009.466806" }, "currencyAmount": "2000", "avalibleAmount": "100000" } ] } } |
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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-api.withhive.com/v1/convert/simul-to-currency' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzQ0ODE1MSwiZXhwIjoxNjY3NTM0NTUxfQ.9XmjT6h-A9qTs7c3ia7fPRrHCizccRRX3XaK_qErEs4' \ -H 'accept: application/json' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'pid: 123123' \ -H 'address: xpla1ps6r4ja93a64lwn4gh0yhjt9rlnk0me0ef4djs' \ -H 'Content-Type: application/json' \ -d '{ "convertTypeCd": "1001000802", "amount": "10000" }' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "result": 0, "ratio": 26.827581, "value": 4158, "expected_return_amount": 4158, "expected_offer_amount": 154.989747 }} |
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
- The user signs the transaction delivered from the API.
- The user calls the broadcast API to write the signed transaction to the blockchain.
- The game server should increase the game currency depending on whether the transaction is successful or not.
- 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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-api.withhive.com/v1/convert/to-currency' \ -H 'accept: application/json' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'pid: 234234' \ -H 'address: xpla1ps6r4ja93a64lwn4gh0yhjt9rlnk0me0ef4djs' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTFlNmxjenV1N240NnhxeTdnbmtmM3FrdXBkc3RlcXowdHA1MHRjcCIsImlhdCI6MTY2NzQ0MzUyOSwiZXhwIjoxNjY3NTI5OTI5fQ.CHZyoDfjPeikLpaU0EcInLeCzeD8Hqb2jW1xDxIknDA' \ -H 'Content-Type: application/json' \ -d '{ "server": "1,1", "characterId": "character Id", "convertTypeCd": "1001000801", "amount": "1.5"}' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "server": "1,1", "characterId": "12345", "requestId": "0bcb3d46-e8b3-45cd-8c4b-e791244a3590", "unSignedTx": "Co0BCooBChwvY29zbW9zLmJhbmsudjFiZXRhMS5Nc2dTZW5kEmoKLHRlcnJhMXg0NnJxYXk0ZDNjc3NxOGd4eHZxejh4dDZud2x6NHRkMjBrMzh2Eix0ZXJyYTE3NTd0a3gwOG4wY3FydzdwODZueTlsbnhzcWV0aDB3Z3AwZW05NRoMCgR1dXNkEgQxMDAwEhUSEwoNCgR1dXNkEgUxMzg5MBC30wU=", "appId": "com.com2us.hivesdk.c2xwallet.hivepc.kr.test", "pid": "13453245", "address": "xpla1ps6r4ja93a64lwn4gh0yhjt9rlnk0me0ef4djs", "convertTypeCd": "1001000801", "inputAmount": "1321", "amount": "1322.123", "convertCurrencyAmount": "12344" }} |
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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-api.withhive.com/v1/convert/simul-to-token' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzQ0ODE1MSwiZXhwIjoxNjY3NTM0NTUxfQ.9XmjT6h-A9qTs7c3ia7fPRrHCizccRRX3XaK_qErEs4' \ -H 'accept: application/json' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'pid: 345' \ -H 'address: xpla1ps6r4ja93a64lwn4gh0yhjt9rlnk0me0ef4djs' \ -H 'Content-Type: application/json' \ -d '{ "convertTypeCd": "1001000801", "amount": "10000"}' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "result": 0, "ratio": 0.025485181818181817, "value": 3.924718, "expected_return_amount": 0, "expected_offer_amount": 0 }} |
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
- The user signs the transaction received from the API.
- The user calls the broadcast API to write the signed transaction to the blockchain.
- 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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/convert/to-token' \ -H 'accept: application/json' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'pid: 234234' \ -H 'address: xpla1ps6r4ja93a64lwn4gh0yhjt9rlnk0me0ef4djs' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTFlNmxjenV1N240NnhxeTdnbmtmM3FrdXBkc3RlcXowdHA1MHRjcCIsImlhdCI6MTY2NzUyNTE4NiwiZXhwIjoxNjY3NjExNTg2fQ.ah6V98Dyk7UwJslsEuJO6LjCfFBBy8Nxd7Ut8gXzSJA' \ -H 'Content-Type: application/json' \ -d '{ "server": "1,1", "characterId": "character Id", "convertTypeCd": "1001000801", "amount": "1000"}' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "requestId": "793b981a-24d3-4ed7-aec5-14b44d7c904d", "txHash": "F9DEBD575AAFE2800844AB15E78F1E99BB752044103D4D68DB3828BC7B5A257F", "appId": "com.com2us.c2xwallet.global.normal", "pid": "234234", "address": "xpla1ps6r4ja93a64lwn4gh0yhjt9rlnk0me0ef4djs", "server": "1,1", "characterId": "character Id", "convertTypeCd": "1001000801", "amount": "1000", "convertTokenAmount": "0.333304" }} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/lock/nft-list' \ -H 'accept: application/json' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'address: xpla1ump5yp4l5f2ulp5ps8k6sdgdcrs2ne8rjurwmk' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTFlNmxjenV1N240NnhxeTdnbmtmM3FrdXBkc3RlcXowdHA1MHRjcCIsImlhdCI6MTY2NzUyNTE4NiwiZXhwIjoxNjY3NjExNTg2fQ.ah6V98Dyk7UwJslsEuJO6LjCfFBBy8Nxd7Ut8gXzSJA' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "address": "xpla1ump5yp4l5f2ulp5ps8k6sdgdcrs2ne8rjurwmk", "lockedNft": [ { "owner": "xpla1ump5yp4l5f2ulp5ps8k6sdgdcrs2ne8rjurwmk", "nft_address": "xpla1fk9u5txf05ftp3rnuqlafef0yunz0786tdw7ksrw669h5003ahxqpaafc2", "token_id": "test#1", "lock_info": "test#1_nft_uri" } ] }} |
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
- The user signs the transaction received from the API.
- The user writes the signed tx to the blockchain through a broadcast API call.
- 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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/lock' \ -H 'accept: application/json' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'address: xpla1ump5yp4l5f2ulp5ps8k6sdgdcrs2ne8rjurwmk' \ -H 'pid: 23234' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTFlNmxjenV1N240NnhxeTdnbmtmM3FrdXBkc3RlcXowdHA1MHRjcCIsImlhdCI6MTY2NzUyNTE4NiwiZXhwIjoxNjY3NjExNTg2fQ.ah6V98Dyk7UwJslsEuJO6LjCfFBBy8Nxd7Ut8gXzSJA' \ -H 'Content-Type: application/json' \ -d '{ "serverId": "1,1", "characterId": "character Id", "tokenId": "qa#1"}' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "requestId": "ae848975-b4e2-4cdb-8151-9caad7388299", "tokenId": "qa#1", "nftContract": "xpla15k3vamzwl30txyvpe5f8x6fdelh7wcevwwx3xrw8pwjj0hgxwksqw43sff", "unSignedTx": "Cr8CCrwCCiQvY29zbXdhc20ud2FzbS52MS5Nc2dFeGVjdXRlQ29udHJhY3QSkwIKK3hwbGExdW1wNXlwNGw1ZjJ1bHA1cHM4azZzZGdkY3JzMm5lOHJqdXJ3bWsSP3hwbGExNWszdmFtendsMzB0eHl2cGU1Zjh4NmZkZWxoN3djZXZ3d3gzeHJ3OHB3amowaGd4d2tzcXc0M3NmZhqiAXsic2VuZF9uZnQiOnsibXNnIjoiZXlKc2IyTnJJanA3SW14dlkydGZhVzVtYnlJNkluRmhYM1Z5YVY4eEluMTkiLCJjb250cmFjdCI6InhwbGExNWh4aGY4bW40ZGU0cXZnajZlZGZkOGdmMmpxZ213eXN6djZsZG5lZnk3Z3BtbDk2OXBqc3BtdXQ2bSIsInRva2VuX2lkIjoicWEjMSJ9fRIjEiEKGwoFYXhwbGESEjM2MDUxMTk4NzUwMDAwMDAwMBDD8Rk=" }} |
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
- The user signs the transaction received from the API.
- The user writes the signed tx to the blockchain through a broadcast API call.
- The game server should delete (deactivate) the game assets depending on the success/failure of the transaction.
- 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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/unlock' \ -H 'accept: application/json' \ -H 'appid: com.com2us.c2xwallet.global.normal' \ -H 'address: xpla1ump5yp4l5f2ulp5ps8k6sdgdcrs2ne8rjurwmk' \ -H 'pid: 234234' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTFlNmxjenV1N240NnhxeTdnbmtmM3FrdXBkc3RlcXowdHA1MHRjcCIsImlhdCI6MTY2NzUyNTE4NiwiZXhwIjoxNjY3NjExNTg2fQ.ah6V98Dyk7UwJslsEuJO6LjCfFBBy8Nxd7Ut8gXzSJA' \ -H 'Content-Type: application/json' \ -d '{ "serverId": "1,1", "characterId": "character Id", "tokenId": "nft#1"}' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "requestId": "e816cc57-5c1a-4718-833c-c13b636c0578", "tokenId": "nft#1", "nftContract": "xpla15k3vamzwl30txyvpe5f8x6fdelh7wcevwwx3xrw8pwjj0hgxwksqw43sff", "txHash": { "height": 0, "txhash": "2C4F55E04CA780629319636544AC61886CCC25F978571D93CEBDC0A04CA18704", "raw_log": "[]" } }} |
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
|
1 |
curl -X 'POST' \ 'https://sandbox-bc-platform-api.withhive.com/v1/broadcast' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "requestId": "cdaf3abe-630b-44eb-926c-feb77eae95ce", "signedTx": "CrQCCpgBChwvY29zbW9zLmJhbmsudjFiZXRhMS5Nc2dTZW5kEngKK3hwbGExcHM2cjRqYTkzYTY0bHduNGdoMHloanQ5cmxuazBtZTBlZjRkanMSK3hwbGExZTZsY3p1dTduNDZ4cXk3Z25rZjNxa3VwZHN0ZXF6MHRwNTB0Y3AaHAoFYXhwbGESEzE0NTUwMDAwMDAwMDAwMDAwMDAKlgEKHC9jb3Ntb3MuYmFuay52MWJldGExLk1zZ1NlbmQSdgoreHBsYTFwczZyNGphOTNhNjRsd240Z2gweWhqdDlybG5rMG1lMGVmNGRqcxIreHBsYTFkdGM3OXc5NTk5NDcweHhyNmpuejl3MHpkdmRqZnBmdXY5dmtqeBoaCgVheHBsYRIRNDUwMDAwMDAwMDAwMDAwMDASfgpZCk8KKC9ldGhlcm1pbnQuY3J5cHRvLnYxLmV0aHNlY3AyNTZrMS5QdWJLZXkSIwohAwSHOe+5dDe23kksG8QDIdhBOsjg4PV9HS9LNGuVdw5HEgQKAgh/GBMSIQobCgVheHBsYRISMTM5MzQzMDUwMDAwMDAwMDAwEN2AChpAGSijq3j2ghuVs7X49tOxDHIs9BPCF6DJ8y7+JyQV2OYxjBEdD5Vy2CA2hv2shdqUQEC8BbytND6uluGW0JSn+g=="}' |
- Response Sample
|
1 |
{ "code": 1000, "message": "success", "data": { "height": 0, "txhash": "50833F6C8214299C4DA25FBF218F03CDE62DC685FD4C5F4BB0166D509CFB8BB4", "raw_log": "[]" }} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/tx?txHash=7E48EE001092EC0F8631B6AFBDAF7F8AE18BD1BBC23DC3C67B60DFC88B660571' \ -H 'accept: */*' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "error": false, "code": 0, "txInfo": { "height": 14684, "txhash": "7E48EE001092EC0F8631B6AFBDAF7F8AE18BD1BBC23DC3C67B60DFC88B660571", "raw_log": "[{\"events\":[{\"type\":\"coin_received\",\"attributes\":[{\"key\":\"receiver\",\"value\":\"xpla1nlnang3a8wwgwx0sm4zut9ygx8mrvdes5n9m3g\"},{\"key\":\"amount\",\"value\":\"150000000000000000axpla\"}]},{\"type\":\"coin_spent\",\"attributes\":[{\"key\":\"spender\",\"value\":\"xpla16v6y48xllwy7amcmvhkv0a3zp7jepl44yvhvxt\"},{\"key\":\"amount\",\"value\":\"150000000000000000axpla\"}]},{\"type\":\"message\",\"attributes\":[{\"key\":\"action\",\"value\":\"/cosmos.bank.v1beta1.MsgSend\"},{\"key\":\"sender\",\"value\":\"xpla16v6y48xllwy7amcmvhkv0a3zp7jepl44yvhvxt\"},{\"key\":\"module\",\"value\":\"bank\"}]},{\"type\":\"transfer\",\"attributes\":[{\"key\":\"recipient\",\"value\":\"xpla1nlnang3a8wwgwx0sm4zut9ygx8mrvdes5n9m3g\"},{\"key\":\"sender\",\"value\":\"xpla16v6y48xllwy7amcmvhkv0a3zp7jepl44yvhvxt\"},{\"key\":\"amount\",\"value\":\"150000000000000000axpla\"}]}]}]", "logs": [ { "msg_index": 0, "log": "", "events": [ { "type": "coin_received", "attributes": [ { "key": "receiver", "value": "xpla1nlnang3a8wwgwx0sm4zut9ygx8mrvdes5n9m3g" }, { "key": "amount", "value": "150000000000000000axpla" } ] }, { "type": "coin_spent", "attributes": [ { "key": "spender", "value": "xpla16v6y48xllwy7amcmvhkv0a3zp7jepl44yvhvxt" }, { "key": "amount", "value": "150000000000000000axpla" } ] }, { "type": "message", "attributes": [ { "key": "action", "value": "/cosmos.bank.v1beta1.MsgSend" }, { "key": "sender", "value": "xpla16v6y48xllwy7amcmvhkv0a3zp7jepl44yvhvxt" }, { "key": "module", "value": "bank" } ] }, { "type": "transfer", "attributes": [ { "key": "recipient", "value": "xpla1nlnang3a8wwgwx0sm4zut9ygx8mrvdes5n9m3g" }, { "key": "sender", "value": "xpla16v6y48xllwy7amcmvhkv0a3zp7jepl44yvhvxt" }, { "key": "amount", "value": "150000000000000000axpla" } ] } ], "eventsByType": { "coin_received": { "receiver": [ "xpla1nlnang3a8wwgwx0sm4zut9ygx8mrvdes5n9m3g" ], "amount": [ "150000000000000000axpla" ] }, "coin_spent": { "spender": [ "xpla16v6y48xllwy7amcmvhkv0a3zp7jepl44yvhvxt" ], "amount": [ "150000000000000000axpla" ] }, "message": { "action": [ "/cosmos.bank.v1beta1.MsgSend" ], "sender": [ "xpla16v6y48xllwy7amcmvhkv0a3zp7jepl44yvhvxt" ], "module": [ "bank" ] }, "transfer": { "recipient": [ "xpla1nlnang3a8wwgwx0sm4zut9ygx8mrvdes5n9m3g" ], "sender": [ "xpla16v6y48xllwy7amcmvhkv0a3zp7jepl44yvhvxt" ], "amount": [ "150000000000000000axpla" ] } } } ], "gas_wanted": 135836, "gas_used": 92842, "tx": { "body": { "messages": [ "{\"@type\":\"/cosmos.bank.v1beta1.MsgSend\",\"amount\":[{\"amount\":\"150000000000000000\",\"denom\":\"axpla\"}],\"from_address\":\"xpla16v6y48xllwy7amcmvhkv0a3zp7jepl44yvhvxt\",\"to_address\":\"xpla1nlnang3a8wwgwx0sm4zut9ygx8mrvdes5n9m3g\"}" ], "memo": "", "timeout_height": 0 }, "auth_info": { "signer_infos": [ { "public_key": "{\"@type\":\"/ethermint.crypto.v1.ethsecp256k1.PubKey\",\"key\":\"Ak4Z1NlvU543QIPi4/i3vA1S2q+X3eP7ApQYIqT12Vw4\"}", "sequence": 21, "mode_info": { "single": { "mode": 127 } } } ], "fee": "{\"amount\":[{\"amount\":\"115461237500000000\",\"denom\":\"axpla\"}],\"gas_limit\":\"135836\",\"granter\":\"\",\"payer\":\"\"}" }, "signatures": [ "QQkdXm4Q2J/usJJMEj3xOuva1KyNuu81Ftzxq6vwdXhPpBQAGjqGv4/9e6zSmTSXvi08ujJFIGlYKVE6lrOP5w==" ] }, "timestamp": "2022-08-31T10:13:36Z", "code": 0, "codespace": "" }, "message": "" }} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/channels?server=Wallet' \ -H 'accept: application/json' \ -H 'appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.sandbox' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS56ZW5hYWQuZ2FtZXMucGN3ZWIuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJpYXQiOjE2NzI3OTUxNjEsImV4cCI6MTY3Mjg4MTU2MX0.0PMEM1t5yb4abvWKEft2VJQghV7BIywmnA9iehjxe58' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": [ { "channelName": "channel 1", "channelId": "1" } ]} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/server/Wallet/maintenance' \ -H 'accept: application/json' \ -H 'appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.sandbox' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS56ZW5hYWQuZ2FtZXMucGN3ZWIuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJpYXQiOjE2NzI3OTUxNjEsImV4cCI6MTY3Mjg4MTU2MX0.0PMEM1t5yb4abvWKEft2VJQghV7BIywmnA9iehjxe58' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "type": "1", "action": "1", "url": "1", "startDate": "2016-05-24 10:32", "endDate": "2016-05-24 10:32", "remainingTime": "2016-05-24 10:32", "title": "server maintenance notification", "message": "There will be a regular maintenance today.", "button": "OK", "buttonLists": [ { "action": "1", "url": "1", "button": "OK" } ] }} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/mint/category' \ -H 'accept: application/json' \ -H 'appid: com.zenaad.games.pcweb.c2xwallet.global.normal' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJpYXQiOjE2NzM0MDc3OTMsImV4cCI6MTY3MzQ5NDE5M30.anOrJJ-d8Am8r3wATtlz795QzO4eI62ndHChzt1DPDo' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": [ { "id": 21, "activeTypeCd": "1001000601", "mintTypeCd": "1001000701", "name": "monster" } ]} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/mint/category/21/fee' \ -H 'accept: application/json' \ -H 'appid: com.zenaad.games.pcweb.c2xwallet.global.normal' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS56ZW5hYWQuZ2FtZXMucGN3ZWIuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJpYXQiOjE2NzM0MDgxMjksImV4cCI6MTY3MzQ5NDUyOX0.cumIqQ6HmCIxdtEmng4qPvejbXgQGYFKcHwFHZNAkj0' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": [ { "nativeTokenFee": "10.0000", "gameTokenFee": "10.0000", "mintCount": 0 } ]} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/convert/type' \ -H 'accept: application/json' \ -H 'appid: com.zenaad.games.pcweb.c2xwallet.global.normal' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS56ZW5hYWQuZ2FtZXMucGN3ZWIuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJpYXQiOjE2NzM0MDgxMjksImV4cCI6MTY3MzQ5NDUyOX0.cumIqQ6HmCIxdtEmng4qPvejbXgQGYFKcHwFHZNAkj0' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": [ { "convertTypeCd": "1001000801", "goodsName": "crystal", "goodsCode": "crystalcode", "goodsImage": "https://c2xnft.qpyou.cn/blockchain-sdk/blockchain/48479951-8fc3-7aa5-b2a8-433c312a30d2.png", "maxConvertQuantityDays": 100000, "minConvertQuantityOneTime": 10 } ]} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/blockchain-games?page=1' \ -H 'accept: application/json' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "betagames": [ { "gameindex": 995, "appid": "com.zenaad.games.pcweb.c2xwallet.global.normal", "title": [ { "language": "en", "name": "gamesen)" }, { "language": "ko", "name": "games" } ], "iconImage": "https://hive-fn.qpyou.cn/hubweb/gmnotice/appcenter/production/1671088460519.png", "genre": "TEST", "characterSelect": 0, "gameTokenName": "ZEN", "gameTokenImage": "https://c2xnft.qpyou.cn/blockchain-sdk/blockchain/75845154-5b9f-b255-90ec-d3d81779b4d4.png", "settingCompleteTypeCd": "1001000901", "apiSettingCompleteTypeCd": "1001000901", "mintActiveTypeCd": "1001000601", "unionMintActiveTypeCd": "1001000601", "charMintActiveTypeCd": "1001000601", "androidDownLink": "https://play.google.com/store/apps/details?id=com.com2us.chronicles.android.google.kr.normal&referrer=utm_source%3Dglobal%26utm_medium%3Dhub%26utm_term%3Dfix%26utm_content%3D%26utm_campaign%3Dsp_so", "iosDownLink": "https://apps.apple.com/kr/app/chronicleskr/id1612757020", "pcDownLink": null, "gameServerLists": [ { "serverId": "GLOBAL", "serverNameKO": "GLOBAL", "serverNameEN": "GLOBAL", "timezone": "America/Los_Angeles" }, { "serverId": "KR", "serverNameKO": "KR", "serverNameEN": "KR", "timezone": "Asia/Seoul" } ] } ], "meta": { "totalItems": 1, "currentPage": "1", "totalPages": 1 } } } |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/characters?server=1%2C1%2C1' \ -H 'accept: */*' \ -H 'pid: 1234' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2ODUwNzcwNiwiZXhwIjoxNjY4NTk0MTA2fQ.GAoKetB-pS47ZRFOOtJ9wdDU-HeChBMKAe8gzsbwXEE' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "characters": [ { "characterName": "character name (nick name)1", "characterId": "1234-1" }, { "characterName": "character name (nick name)2", "characterId": "1234-2" } ] }} |
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
|
1 |
curl -X 'GET' \ 'https://sandbox-bc-platform-api.withhive.com/game/v1/mint/items?server=1%2C1%2C1&characterId=1234&categoryId=519' \ -H 'accept: application/json' \ -H 'address: xpla19pwda2lut9xaefr8gsmgktuqew90sc5ajlxhkg' \ -H 'pid: 1234' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2FsbGV0Lmdsb2JhbC5ub3JtYWwiLCJyb2xlIjoib3BlcmF0b3IiLCJhZGRyZXNzIjoieHBsYTE5cHdkYTJsdXQ5eGFlZnI4Z3NtZ2t0dXFldzkwc2M1YWpseGhrZyIsImlhdCI6MTY2NzM4NzYzOSwiZXhwIjoxNjY3NDc0MDM5fQ.JeU7Y3IcaY35yc0w1jK3OVWzD5kHrTpLztcc4arQt-o' |
- Response Sample
|
1 |
{ "code": 0, "message": "success", "data": { "items": [ { "name": "sword1", "description": "sword1 description", "uniqueId": "itemUniqCode1", "nftStatus": "none", "tokenId": null }, { "name": "sword2", "description": "sword1 description", "uniqueId": "itemUniqCode2", "nftStatus": "unlocked", "tokenId": "sword2" } ], "characters": [] }} |
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. |