Hive 블록체인 API는 Hive에서 제공하는 AppID, PlayerID 기반으로 동작하는 웹3 게임 API입니다. 게임 유저가 한 번에 200개까지 발행할 수 있는 대량 발행 기능과 유저별 트랜잭션 로그 조회와 같은 웹3 게임에 최적화된 기능을 제공합니다. Hive 블록체인 API를 이용하면 웹 3 게임의 개발부터 운영 및 관리까지 프로젝트를 효율적으로 관리할 수 있습니다. Hive 블록체인 API는 Polygon 블록체인과 XPLA 블록체인을 지원합니다.

사전 준비: API 인증 토큰 발급하기

Hive 블록체인 API를 호출하려면 API Header에 인증 토큰을 첨부해야 합니다. API 인증 토큰을 발급받는 방법은 다음과 같습니다.

Hive 콘솔에 가입 후 앱센터 > 게임목록 > 새 게임 등록하기에서 게임을 등록합니다.
앱센터 > AppID 목록 > 새 AppID 등록하기에서 AppID를 생성합니다.
- AppID 만들기: 웹 로그인 AppID
- 사용 용도 선택: 블록체인
- 사용할 AppID 선택: “자동 생성된 AppID” 또는 “자동 생성된 AppID + 추가정보” 선택
Hive 콘솔 > 블록체인 > API 인증키 조회에서 게임명을 선택하고 ID와 인증키(SecretKey)를 발급받습니다.
auth-token API Request Body에 ID와 SecretKey를 넣고 API를 호출합니다.
API 응답값에서 data.accessToken이 인증 토큰입니다.

NFT API

NFT 발행

특정 주소(to)로 토큰을 발행하는 트랜잭션을 생성합니다. 발행할 NFT 정보(mintMsg.tokenId, mintMsg.metadata 등)를 배열에 담아 호출합니다. API 호출당 1개 계정에게 XPLA는 최대 200 토큰, Polygon은 최대 50 토큰을 발행할 수 있습니다. from은 발행 권한을 가진 계정이어야 합니다.

Request URL

Live URL	https://bc-api.qpyou.cn/service/v1/nft/{contract}/mint
Sandbox URL	https://sandbox-bc-api.qpyou.cn/service/v1/nft/{contract}/mint
HTTP Method	POST
Content-Type	application/json

Path Parameters

필드명	설명	타입	필수 여부
contract	NFT 컨트랙트 주소	string	Y

Header Parameters

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y
x-network	블록체인 네트워크{ploygon, xpla}	string	Y
x-appid	앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y

Request Body

필드명	설명	타입	필수 여부
playerId	플레이어 ID	string	Y
from	NFT를 발행하는 계정 주소	string	Y
to	NFT를 받을 지갑 주소	string	Y
isSend	`true`이면 KMS에 지갑 키가 있을 때, 이 키로 트랜잭션에 자동으로 서명 후 이를 블록체인에 전송합니다. 응답값으로 `txHash`를 받습니다. `false`이면 사용자가 직접 서명해야 하는 트랜잭션 데이터인 `data.rawTx`를 응답값으로 받습니다.	boolean	Y
mintMsg	발행 시 필요한 정보	array	Y
mintMsg.tokenId	NFT ID입니다. NFT 발행자가 지정하며 중복을 허용하지 않습니다. Polygon: 문자열, 정수(0~2²⁵⁶-1)만 사용 가능 XPLA: 문자열만 사용 가능	string	Y
mintMsg.royaltyPercentage	로열티 비율입니다. NFT가 판매 또는 재판매될 때마다 NFT 작성자 또는 권리를 가진 보유자에게 지불할 금액입니다. 총 판매금액에 로열티로 지불할 비율이 설정됩니다. 아티스트 및 기타 NFT 제작자에게 지속적인 자금을 지원하려는 NFT 마켓 플레이스를 위한 기능입니다. NFT 전송 시 수취인에게 로열티가 자동으로 지불되지 않으며, 마켓 플레이스에서 NFT 로열티를 확인하고 수취인에게 지불합니다. OpenSea에 적용된 기능입니다. Polygon: 소수점 둘째자리까지 허용합니다. XPLA: 소수점을 허용하지 않습니다.	number	Y
mintMsg.metadata	메타데이터 메타데이터 입력 시 타입 및 url(`animationUrl`, `youtubeUrl`, `externalUrl`) 포맷을 확인합니다. 정확하지 않은 데이터 전송 시 API가 정상 작동하지 않습니다. 메타데이터가 IPFS에 저장될 때는 OpenSea와 연동 가능한 snake case로 저장됩니다(예시: `animationUrl` → `animation_url`)	json	Y
mintMsg.metadata.name	NFT 이름	string	Y
mintMsg.metadata.description	NFT 설명	string	N
mintMsg.metadata.image	NFT 이미지 주소입니다. IPFS에 업로드하기 위한 외부에서 접근 가능한 웹사이트 주소 또는 Public IPFS 주소입니다.	string	Y
mintMsg.metadata.animationUrl	NFT 관련 애니메이션 주소	string	N
mintMsg.metadata.youtubeUrl	유투브 주소	string	N
mintMsg.metadata.imageData	NFT 이미지 정보	string	N
mintMsg.metadata.externalUrl	외부로 연결되는 주소	string	N
mintMsg.metadata.backgroundColor	OpenSea에서 토큰의 배경색 정보	string	N
mintMsg.metadata.attributes	메타데이터 속성 정보입니다. 메타데이터에 명시하지 않았던 부가적인 정보입니다.	json	N
mintMsg.metadata.attributes.traitType	attributes를 구성하는 항목명입니다.	string	N
mintMsg.metadata.attributes.maxValue	trait 최대값	number	N
mintMsg.metadata.attributes.value	trait값입니다. `mintMsg.metadata.attributes.maxValue`보다 작아야 합니다. `mintMsg.metadata.attributes.displayType`이 date이면 value에 unix timestamp (seconds)를 입력합니다.	string 또는 number	N
mintMsg.metadata.attributes.displayType	trait 노출 유형입니다. 기본값은 string 타입입니다. number: Number 타입 boost_percentage: OpenSea Boosts에 % 정보로 노출 boost_number: OpenSea Boosts에 노출 date: 날짜 형식으로 노출(예시: Tuesday, January 1st, 2019)	string	N
encoded	반환받을 트랜잭션의 인코딩 여부 `true`: `data.rawTx`으로 인코딩된 Raw Transaction String을 받습니다. `false`: `data.rawTx`으로 인코딩을 디코딩한 JSON 결과값을 받습니다.	boolean	Y
callbackUrl	트랜잭션을 블록체인에 기록하는 데 성공/실패했는지 결과를 전달 받을 주소	string	Y

Responses

필드명	설명	타입
code	api 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json
data.rawTx	트랜잭션 데이터입니다. `isSend`가 `false`일 때에만 이 값을 받습니다.	string 또는 json
data.hashedTx	해시한 `data.rawTx`입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다. `x-network`가 `polygon` `from`이 다중 서명 지갑 주소 `isSend`가 `false`	string
data.txhash	트랜잭션 전송 결과로 받는 트랜잭션 해시입니다. `isSend`가 `true`일 때만 이 값을 받습니다.	string
data.status	전송한 트랜잭션 상태입니다. `isSend`가 `true`일 때, 트랜잭션이 잘 전송되었다면 `PENDING`을 받습니다. `isSend`가 `false`이면, 트랜잭션을 전송하기 전에 서명이 필요한 상태라는 의미에서 `WAITING` 값을 받습니다.	string
data.reqeustId	API 요청을 식별할 수 있는 고유값	string

Request Sample

curl -X 'POST' \
  'https://sandbox-bc-api.qpyou.cn/service/v1/nft/0x31a6854383c81daab14089cba0b9de1d42ecd65f/mint' \
  -H 'accept: */*' \
  -H 'x-network: polygon' \
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20y...' \
  -H 'Content-Type: application/json' \
  -d '{
  "playerId": 1324,
  "from": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0",
  "to": "0xA10078576Ca6f63dc6f78ff9a8ed8bd05B51f463",
  "isSend": true,
  "royaltyPercentage": 7.5,
  "mintMsg": [
    {
      "tokenId": "1",
      "metadata": {
        "name": "Arbiter'\''s Robe",
        "description": "desc",
        "image": "https://image01.c2x.world/equip_92053030.gif",
        "animationUrl": "https://image01.c2x.world/equip_92053030.gif",
        "externalUrl": "https://dex.c2xnft.com/market?key=4423",
        "attributes": [
          {
            "traitType": "Category",
            "value": "Game",
          }
        ]
      }
    }
  ],
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

curl -X 'POST' \

'https://sandbox-bc-api.qpyou.cn/service/v1/nft/0x31a6854383c81daab14089cba0b9de1d42ecd65f/mint' \

-H 'accept: */*' \

-H 'x-network: polygon' \

-H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20y...' \

-H 'Content-Type: application/json' \

-d '{

"playerId": 1324,

"from": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0",

"to": "0xA10078576Ca6f63dc6f78ff9a8ed8bd05B51f463",

"isSend": true,

"royaltyPercentage": 7.5,

"mintMsg": [

{

"tokenId": "1",

"metadata": {

"name": "Arbiter'\''s Robe",

"description": "desc",

"image": "https://image01.c2x.world/equip_92053030.gif",

"animationUrl": "https://image01.c2x.world/equip_92053030.gif",

"externalUrl": "https://dex.c2xnft.com/market?key=4423",

"attributes": [

{

"traitType": "Category",

"value": "Game",

}

]

}

"encoded": true,

"callbackUrl": "https://withhive.com/"

Response Sample

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}

// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"txhash": "02f8f3830138810b8459682f008459682f1083023...",

"status": "pending",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8f3830138810b8459682f008459682f1083023...",

"hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8f3830138810b8459682f008459682f1083023...",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false일 때: data.rawTx가 string

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",

"requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"

}

// Request Body의 isSend가 false일 때: data.rawTx가 json

{

"code": 0,

"message": "success",

"data": {

"rawTx": {

"from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",

"to": "0xebd9144485089ebe248f8490984a60579407c262",

"data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",

"nonce": 11,

"chainId": 80001,

"gas": 190228,

"maxFeePerGas": 1491259270,

"maxPriorityFeePerGas": 1491259255

"requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"

}

NFT 조회

토큰 ID(tokenId)에 해당하는 NFT를 조회합니다.

Request URL

Live URL	https://bc-api.qpyou.cn/service/v1/nft/{contract}/tokens/{tokenId}
Sandbox URL	https://sandbox-bc-api.qpyou.cn/service/v1/nft/{contract}/tokens/{tokenId}
HTTP Method	POST
Content-Type	application/json

Path Parameters

필드명	설명	타입	필수 여부
contract	NFT 컨트랙트 주소	string	Y
tokenId	토큰 ID	string	Y

Header Parameters

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y
x-network	블록체인 네트워크{ploygon, xpla}	string	Y
x-appid	앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y

Responses

필드명	설명	타입
code	api 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json
data.nftContract	NFT 컨트랙트 주소	string
data.tokenId	토큰 ID	string
data.tokenUri	토큰의 IPFS 주소	string
data.gatewayUrl	토큰의 Gateway 주소	string
data.metadata	메타데이터 정보	json
data.metadata.name	NFT 이름	string
data.metadata.description	NFT 설명	string
data.metadata.image	NFT 이미지 주소입니다. 외부에서 접근 가능한 웹사이트 주소 또는 Public IPFS 주소입니다.	string
data.metadata.animationUrl	NFT 관련 애니메이션 주소	string
data.metadata.youtubeUrl	유투브 주소	string
data.metadata.imageData	NFT 이미지 정보	string
data.metadata.externalUrl	외부로 연결되는 주소	string
data.metadata.backgroundColor	OpenSea에서 토큰의 배경색 정보	string
data.metadata.attributes	메타데이터 속성 정보입니다. 메타데이터에 명시하지 않았던 부가적인 정보입니다.	json
data.metadata.attributes.traitType	attributes를 구성하는 항목명입니다.	string
data.metadata.attributes.maxValue	trait 최대값	string
data.metadata.attributes.value	trait값입니다. `data.metadata.attributes.maxValue`보다 작아야 합니다. `data.metadata.attributes.displayType`이 date이면 value에 unix timestamp (seconds)를 입력합니다.	string 또는 number
data.metadata.attributes.displayType	trait 노출 유형입니다. 기본값은 string 타입입니다. number: Number 타입 boost_percentage: OpenSea Boosts에 % 정보로 노출 boost_number: OpenSea Boosts에 노출 date: 날짜 형식으로 노출(예시: Tuesday, January 1st, 2019)	string

Request Sample

curl -X 'GET' \
  'https://sandbox-bc-api.qpyou.cn/service/v1/nft/0x31a6854383c81daab14089cba0b9de1d42ecd65f/tokens/1' \
  -H 'accept: application/json' \
  -H 'x-network: polygon' \
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6...'

curl -X 'GET' \

'https://sandbox-bc-api.qpyou.cn/service/v1/nft/0x31a6854383c81daab14089cba0b9de1d42ecd65f/tokens/1' \

-H 'accept: application/json' \

-H 'x-network: polygon' \

-H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6...'

Response Sample

{
  "code": 0,
  "message": "success",
  "data": {
    "nftContract": "0x31a6854383c81daab14089cba0b9de1d42ecd65f",
    "tokenId": "5",
    "tokenUri": "ipfs://QmTPp6KFmBiDQyVL5b9fUGgp9tJtKrVEayRiXadDuBaPSD",
    "gatewayUrl": "https://test-bc-file.qpyou.cn/ipfs/QmTPp6KFmBiDQyVL5b9fUGgp9tJtKrVEayRiXadDuBaPSD",
    "metadata": {
      "name": "Arbiter's Robe",
      "description": "desc",
      "image": "https://image01.c2x.world/equip_92053030.gif",
      "animationUrl": "https://image01.c2x.world/equip_92053030.gif",
      "externalUrl": "https://dex.c2xnft.com/market?key=4423",
      "backgroundColor": "orange",
      "attributes": [
        {
          "traitType": "Category",
          "value": "Game",
          "displayType": "string"
        }
      ]
    }
  }
}

{

"code": 0,

"message": "success",

"data": {

"nftContract": "0x31a6854383c81daab14089cba0b9de1d42ecd65f",

"tokenId": "5",

"tokenUri": "ipfs://QmTPp6KFmBiDQyVL5b9fUGgp9tJtKrVEayRiXadDuBaPSD",

"gatewayUrl": "https://test-bc-file.qpyou.cn/ipfs/QmTPp6KFmBiDQyVL5b9fUGgp9tJtKrVEayRiXadDuBaPSD",

"metadata": {

"name": "Arbiter's Robe",

"description": "desc",

"image": "https://image01.c2x.world/equip_92053030.gif",

"animationUrl": "https://image01.c2x.world/equip_92053030.gif",

"externalUrl": "https://dex.c2xnft.com/market?key=4423",

"backgroundColor": "orange",

"attributes": [

{

"traitType": "Category",

"value": "Game",

"displayType": "string"

}

]

}

Lock API

NFT 잠금

NFT 잠금이란 발행한 NFT를 거래할 수 없도록 잠그는 것입니다. 게임 유저가 게임 아이템을 민팅해서 NFT를 얻은 후 다시 게임에서 해당 아이템 사용을 원할 경우 NFT를 거래할 수 없도록 잠급니다. 소유자(owner)는 보유한 NFT(tokenId)를 사용할 수 없도록 잠금 설정 트랜잭션을 생성합니다.

Request URL

Live URL	https://bc-api.qpyou.cn/service/v1/nft/contract/{contract}/lock
Sandbox URL	https://sandbox-bc-api.qpyou.cn/ service/v1/nft/contract/{contract}/lock
HTTP Method	POST
Content-Type	application/json

Path Parameters

필드명	설명	타입	필수 여부
contract	NFT 컨트랙트 주소	string	Y

Header Parameters

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y
x-network	블록체인 네트워크{ploygon, xpla}	string	Y
x-appid	앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y

Request Body

필드명	설명	타입	필수 여부
playerId	플레이어 ID	string	Y
from	NFT 소유자 지갑 주소	string	Y
isSend	`true`이면 KMS에 지갑 키가 있을 때, 이 키로 트랜잭션에 자동으로 서명 후 이를 블록체인에 전송합니다. 응답값으로 `txHash`를 받습니다. `false`이면 사용자가 직접 서명해야 하는 트랜잭션 데이터인 `data.rawTx`를 응답값으로 받습니다.	boolean	Y
lockContract	잠금 컨트랙트 주소	string	Y
tokenId	NFT ID	string	Y
encoded	반환받을 트랜잭션의 인코딩 여부 `true`: `data.rawTx`으로 인코딩된 Raw Transaction String을 받습니다. `false`: `data.rawTx`으로 인코딩을 디코딩한 JSON 결과값을 받습니다.	boolean	Y
callbackUrl	트랜잭션을 블록체인에 기록하는 데 성공/실패했는지 결과를 전달 받을 주소	string	Y

Responses

필드명	설명	타입
code	api 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json
data.rawTx	트랜잭션 데이터입니다. `isSend`가 `false`일 때에만 이 값을 받습니다.	string 또는 json
data.hashedTx	해시한 `data.rawTx`입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다. `x-network`가 `polygon` `from`이 다중 서명 지갑 주소 `isSend`가 `false`	string
data.txhash	트랜잭션 전송 결과로 받는 트랜잭션 해시입니다. `isSend`가 `true`일 때만 이 값을 받습니다.	string
data.status	전송한 트랜잭션 상태입니다. `isSend`가 `true`일 때, 트랜잭션이 잘 전송되었다면 `PENDING`을 받습니다. `isSend`가 `false`이면, 트랜잭션을 전송하기 전에 서명이 필요한 상태라는 의미에서 `WAITING` 값을 받습니다.	string
data.reqeustId	API 요청에 대한 고유 식별 정보	string

Request Sample

curl -X 'POST' \
  'https://sandbox-bc-api.qpyou.cn/service/v1/nft/contract/0xebd9144485089ebe248f8490984a60579407c262/lock' \
  -H 'accept: application/json' \
  -H 'x-network: polygon' \
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20...' \
  -H 'Content-Type: application/json' \
  -d '{
  "playerId": 1324,
  "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
  "isSend": true,
  "lockContract": "0x572f47db51a98ae0d51324c2703d9d63ee3c9f03",
  "tokenId": "1",
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

curl -X 'POST' \

'https://sandbox-bc-api.qpyou.cn/service/v1/nft/contract/0xebd9144485089ebe248f8490984a60579407c262/lock' \

-H 'accept: application/json' \

-H 'x-network: polygon' \

-H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20...' \

-H 'Content-Type: application/json' \

-d '{

"playerId": 1324,

"from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",

"isSend": true,

"lockContract": "0x572f47db51a98ae0d51324c2703d9d63ee3c9f03",

"tokenId": "1",

"encoded": true,

"callbackUrl": "https://withhive.com/"

Response Sample

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}

// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"txhash": "02f8f3830138810b8459682f008459682f1083023...",

"status": "pending",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8f3830138810b8459682f008459682f1083023...",

"hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8f3830138810b8459682f008459682f1083023...",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false일 때: data.rawTx가 string

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",

"requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"

}

// Request Body의 isSend가 false일 때: data.rawTx가 json

{

"code": 0,

"message": "success",

"data": {

"rawTx": {

"from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",

"to": "0xebd9144485089ebe248f8490984a60579407c262",

"data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",

"nonce": 11,

"chainId": 80001,

"gas": 190228,

"maxFeePerGas": 1491259270,

"maxPriorityFeePerGas": 1491259255

"requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"

}

NFT 잠금 해제

소유자(owner)가 NFT(tokenId)를 사용할 수 있도록 잠금 설정을 해제하는 트랜잭션을 생성합니다.

Request URL

Live URL	https://bc-api.qpyou.cn/service/v1/lock/contract/{contract}/unlock
Sandbox URL	https://sandbox-bc-api.qpyou.cn/service/v1/lock/contract/{contract}/unlock
HTTP Method	POST
Content-Type	application/json

Path Parameters

필드명	설명	타입	필수 여부
contract	잠금 컨트랙트 주소	string	Y

Header Parameters

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y
x-network	블록체인 네트워크{ploygon, xpla}	string	Y
x-appid	앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y

Request Body

필드명	설명	타입	필수 여부
playerId	플레이어 ID	string	Y
nftContract	NFT 컨트랙트 주소	string	Y
from	잠금 컨트랙트 소유주 지갑 주소	string	Y
isSend	`true`이면 KMS에 지갑 키가 있을 때, 이 키로 트랜잭션에 자동으로 서명 후 이를 블록체인에 전송합니다. 응답값으로 `txHash`를 받습니다. `false`이면 사용자가 직접 서명해야 하는 트랜잭션 데이터인 `data.rawTx`를 응답값으로 받습니다.	boolean	Y
tokenId	NFT ID	string	Y
encoded	반환받을 트랜잭션의 인코딩 여부 `true`: `data.rawTx`으로 인코딩된 Raw Transaction String을 받습니다. `false`: `data.rawTx`으로 인코딩을 디코딩한 JSON 결과값을 받습니다.	boolean	Y
callbackUrl	트랜잭션을 블록체인에 기록하는 데 성공/실패했는지 결과를 전달 받을 주소	string	Y

Responses

필드명	설명	타입
code	api 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json
data.rawTx	트랜잭션 데이터입니다. `isSend`가 `false`일 때에만 이 값을 받습니다.	string 또는 json
data.hashedTx	해시한 `data.rawTx`입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다. `x-network`가 `polygon` `from`이 다중 서명 지갑 주소 `isSend`가 `false`	string
data.txhash	트랜잭션 전송 결과로 받는 트랜잭션 해시입니다. `isSend`가 `true`일 때만 이 값을 받습니다.	string
data.status	전송한 트랜잭션 상태입니다. `isSend`가 `true`일 때, 트랜잭션이 잘 전송되었다면 `PENDING`을 받습니다. `isSend`가 `false`이면, 트랜잭션을 전송하기 전에 서명이 필요한 상태라는 의미에서 `WAITING` 값을 받습니다.	string
data.reqeustId	API 요청을 식별할 수 있는 고유값	string

Request Sample

curl -X 'POST' \
  'https://sandbox-bc-api.qpyou.cn/service/v1/lock/contract/0x572f47db51a98ae0d51324c2703d9d63ee3c9f03/unlock' \
  -H 'accept: application/json' \
  -H 'x-network: polygon' \
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuaGl2ZXNka...' \
  -H 'Content-Type: application/json' \
  -d '{
  "playerId": 1324,
  "isSend": true,
  "nftContract": "0xebd9144485089ebe248f8490984a60579407c262",
  "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
  "tokenId": "2",
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

curl -X 'POST' \

'https://sandbox-bc-api.qpyou.cn/service/v1/lock/contract/0x572f47db51a98ae0d51324c2703d9d63ee3c9f03/unlock' \

-H 'accept: application/json' \

-H 'x-network: polygon' \

-H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuaGl2ZXNka...' \

-H 'Content-Type: application/json' \

-d '{

"playerId": 1324,

"isSend": true,

"nftContract": "0xebd9144485089ebe248f8490984a60579407c262",

"from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",

"tokenId": "2",

"encoded": true,

"callbackUrl": "https://withhive.com/"

Response Sample

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}

// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"txhash": "02f8f3830138810b8459682f008459682f1083023...",

"status": "pending",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8f3830138810b8459682f008459682f1083023...",

"hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8f3830138810b8459682f008459682f1083023...",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false일 때: data.rawTx가 string

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",

"requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"

}

// Request Body의 isSend가 false일 때: data.rawTx가 json

{

"code": 0,

"message": "success",

"data": {

"rawTx": {

"from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",

"to": "0xebd9144485089ebe248f8490984a60579407c262",

"data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",

"nonce": 11,

"chainId": 80001,

"gas": 190228,

"maxFeePerGas": 1491259270,

"maxPriorityFeePerGas": 1491259255

"requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"

}

Convert API

게임 재화와 게임 토큰을 교환

게임 토큰과 게임 재화를 교환합니다.

to-token: 게임 재화(gameCurrencyCode)를 게임 토큰(gameToken)으로 교환합니다.
to-currency: 게임 토큰(gameToken)을 게임 재화(gameCurrencyCode)로 교환합니다.

Request URL

Live URL	https://bc-api.qpyou.cn/service/v1/convert/{type}
Sandbox URL	https://sandbox-bc-api.qpyou.cn/service/v1/convert/{type}
HTTP Method	POST
Content-Type	application/json

Path Parameters

필드명 설명 타입 필수 여부

type

필드명	설명	타입	필수 여부
type	컨버트 타입 to-token: 게임 재화(`gameCurrencyCode`)를 게임 토큰(`gameToken`)으로 교환합니다. to-currency: 게임 토큰(`gameToken`)을 게임 재화(`gameCurrencyCode`)로 교환합니다.	string	Y

컨버트 타입

to-token: 게임 재화(gameCurrencyCode)를 게임 토큰(gameToken)으로 교환합니다.
to-currency: 게임 토큰(gameToken)을 게임 재화(gameCurrencyCode)로 교환합니다.

string

Header Parameters

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y
x-network	블록체인 네트워크{ploygon, xpla}	string	Y
x-appid	앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y

Request Body

필드명	설명	타입	필수 여부
playerId	플레이어 ID	string	Y
isSend	`true`이면 KMS에 지갑 키가 있을 때, 이 키로 트랜잭션에 자동으로 서명 후 이를 블록체인에 전송합니다. 응답값으로 `txHash`를 받습니다. `false`이면 사용자가 직접 서명해야 하는 트랜잭션 데이터인 `data.rawTx`를 응답값으로 받습니다.	boolean	Y
owner	사용자의 지갑 주소	string	Y
convertPool	컨버트풀 주소	string	Y
gameTokenAmount	게임 토큰 수량	string	Y
gameCurrencyCode	게임 재화 코드	string	Y
gameCurrencyAmount	게임 재화 수량	string	Y
encoded	반환받을 트랜잭션의 인코딩 여부 `true`: `data.rawTx`으로 인코딩된 Raw Transaction String을 받습니다. `false`: `data.rawTx`으로 인코딩을 디코딩한 JSON 결과값을 받습니다.	boolean	Y
callbackUrl	트랜잭션을 블록체인에 기록하는 데 성공/실패했는지 결과를 전달 받을 주소	string	Y

Responses

필드명	설명	타입
code	api 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json
data.rawTx	트랜잭션 데이터입니다. `isSend`가 `false`일 때에만 이 값을 받습니다.	string 또는 json
data.hashedTx	해시한 `data.rawTx`입니다. 아래 조건을 모두 만족할 때에만 이 값을 받습니다. `x-network`가 `polygon` `from`이 다중 서명 지갑 주소 `isSend`가 `false`	string
data.txhash	트랜잭션 전송 결과로 받는 트랜잭션 해시입니다. `isSend`가 `true`일 때만 이 값을 받습니다.	string
data.status	전송한 트랜잭션 상태입니다. `isSend`가 `true`일 때, 트랜잭션이 잘 전송되었다면 `PENDING`을 받습니다. `isSend`가 `false`이면, 트랜잭션을 전송하기 전에 서명이 필요한 상태라는 의미에서 `WAITING` 값을 받습니다.	string
data.reqeustId	API 요청을 식별할 수 있는 고유값	string

Request Sample

curl -X 'POST' \
  'https://sandbox-bc-api.qpyou.cn/service/v1/convert/to-token' \
  -H 'accept: application/json' \
  -H 'x-network: polygon' \
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvb...' \
  -H 'Content-Type: application/json' \
  -d '{
  "playerId": 1324,
  "isSend": true,
  "owner": "0xA10078576Ca6f63dc6f78ff9a8ed8bd05B51f463",
  "convertPool": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
  "gameTokenAmount": "1",
  "gameCurrencyCode": "A39539HFTGOLD0001",
  "gameCurrencyAmount": "1000",
  "encoded": true,
  "callbackUrl": "https://withhive.com/"
}'

curl -X 'POST' \

'https://sandbox-bc-api.qpyou.cn/service/v1/convert/to-token' \

-H 'accept: application/json' \

-H 'x-network: polygon' \

-H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvb...' \

-H 'Content-Type: application/json' \

-d '{

"playerId": 1324,

"isSend": true,

"owner": "0xA10078576Ca6f63dc6f78ff9a8ed8bd05B51f463",

"convertPool": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",

"gameTokenAmount": "1",

"gameCurrencyCode": "A39539HFTGOLD0001",

"gameCurrencyAmount": "1000",

"encoded": true,

"callbackUrl": "https://withhive.com/"

Response Sample

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "txhash": "02f8f3830138810b8459682f008459682f1083023...",
    "status": "pending",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8f3830138810b8459682f008459682f1083023...",
    "requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"
  }
}

// Request Body의 isSend가 false일 때: data.rawTx가 string
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",
    "requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"
  }
}

// Request Body의 isSend가 false일 때: data.rawTx가 json
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",
      "to": "0xebd9144485089ebe248f8490984a60579407c262",
      "data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",
      "nonce": 11,
      "chainId": 80001,
      "gas": 190228,
      "maxFeePerGas": 1491259270,
      "maxPriorityFeePerGas": 1491259255
    },
    "requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"
  }
}

// Request Body의 isSend가 true이고 from이 KMS 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"txhash": "02f8f3830138810b8459682f008459682f1083023...",

"status": "pending",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false이고 from이 다중 서명 지갑 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8f3830138810b8459682f008459682f1083023...",

"hashedTx": "0x53e8783e4da707daf58c96a8cea278e7b2a8a5f185af0913b518974556c79076...",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false이고 from이 KMS 주소나 일반 지갑 주소일 경우

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8f3830138810b8459682f008459682f1083023...",

"requestId": "6fb62650-d52e-4bec-bb91-dd081813d7f1"

}

// Request Body의 isSend가 false일 때: data.rawTx가 string

{

"code": 0,

"message": "success",

"data": {

"rawTx": "02f8d3830138810b8458e948068458e948168302e71494ebd9144485089ebe248f8...",

"requestId": "5743f0aa-0323-47fc-a3da-173eee27bbe4"

}

// Request Body의 isSend가 false일 때: data.rawTx가 json

{

"code": 0,

"message": "success",

"data": {

"rawTx": {

"from": "0xdcd51770d06B54204abd8c30A25b4583D4cABa39",

"to": "0xebd9144485089ebe248f8490984a60579407c262",

"data": "0xb88d4fde000000000000000000000000dcd51770d06b54204abd8c30a25b4583d4caba3900...",

"nonce": 11,

"chainId": 80001,

"gas": 190228,

"maxFeePerGas": 1491259270,

"maxPriorityFeePerGas": 1491259255

"requestId": "dd33ddd8-31fa-4491-9c3c-2f912f7059bc"

}

컨버트 풀 확인

컨버트 풀이란 게임사가 발행한 게임 토큰과 게임 재화을 서로 교환할 수 있는 곳입니다. 컨버트 풀의 잔여 토큰 수량과 게임 재화 수량을 조회합니다.

Request URL

Live URL	https://bc-api.qpyou.cn/service/v1/convert/pool/{convertPool}
Sandbox URL	https://sandbox-bc-api.qpyou.cn/service/v1/convert/pool/{convertPool}
HTTP Method	GET
Content-Type	application/json

Path Parameters

필드명	설명	타입	필수 여부
convertPool	컨버트풀 주소	string	Y

Header Parameters

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y
x-network	블록체인 네트워크{ploygon, xpla}	string	Y
x-appid	앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y

Responses

필드명	설명	타입
code	api 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json

Request Sample

curl -X 'GET' \
  'https://sandbox-bc-api.qpyou.cn/service/v1/convert/pool/0xdcd51770d06B54204abd8c30A25b4583D4cABa39' \
  -H 'accept: application/json' \
  -H 'x-network: polygon' \
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvb...' \
  -d ''

curl -X 'GET' \

'https://sandbox-bc-api.qpyou.cn/service/v1/convert/pool/0xdcd51770d06B54204abd8c30A25b4583D4cABa39' \

-H 'accept: application/json' \

-H 'x-network: polygon' \

-H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvb...' \

-d ''

Response Sample

{
  "code": 0,
  "message": "success",
  "data": {
    "convertPoolAmount": "1000000000",
    "gameCurrency": [
      {
        "goodsCode": "A39539HFTBRONZE0003",
        "goodsAmount": "10000000000"
      },
      {
        "goodsCode": "A39539HFTGOLD0001",
        "goodsAmount": "1000000000000"
      },
      {
        "goodsCode": "A39539HFTSILVER0002",
        "goodsAmount": "100000000000"
      }
    ]
  }
}

{

"code": 0,

"message": "success",

"data": {

"convertPoolAmount": "1000000000",

"gameCurrency": [

{

"goodsCode": "A39539HFTBRONZE0003",

"goodsAmount": "10000000000"

{

"goodsCode": "A39539HFTGOLD0001",

"goodsAmount": "1000000000000"

{

"goodsCode": "A39539HFTSILVER0002",

"goodsAmount": "100000000000"

}

]

}

Transaction API

Txhash 등록

어떤 트랜잭션을 생성했을 때(mint, convert, lock API 등) 응답값으로 받은 requestId와, 이 트랜잭션을 블록체인에 기록하고 받은 txHash를 등록 합니다. 트랜잭션 생성 요청이 정상적으로 완료되었는지 추적하기 위한 절차입니다.

Request URL

Live URL	https://bc-api.qpyou.cn/service/v1/tx/hash
Sandbox URL	https://sandbox-bc-api.qpyou.cn/service/v1/tx/hash
HTTP Method	PATCH
Content-Type	application/json

Header Parameters

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y
x-network	블록체인 네트워크{ploygon, xpla}	string	Y
x-appid	앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y

Request Body

필드명	설명	타입	필수 여부
requestId	API 요청을 식별할 수 있는 고유값	string	Y
txHash	트랜잭션 해쉬	string	Y

Responses

필드명	설명	타입
code	api 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json

Request Sample

curl -X 'PATCH' \
  'https://sandbox-bc-api.qpyou.cn/service/v1/tx/hash' \
  -H 'accept: application/json' \
  -H 'x-network: polygon' \
  -H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImN...' \
  -H 'Content-Type: application/json' \
  -d '{
  "requestId": "538d0ca4-9d8b-4b8c-ab02-c68bc1623ed3",
  "txHash": "0x99a93c8ba06865bd7054835d5f9abe57424289dca15ea61fe55a33a0651b058c"
}'

curl -X 'PATCH' \

'https://sandbox-bc-api.qpyou.cn/service/v1/tx/hash' \

-H 'accept: application/json' \

-H 'x-network: polygon' \

-H 'x-appid: com.com2us.hivesdk.normal.freefull.apple.global.ios.universal' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImN...' \

-H 'Content-Type: application/json' \

-d '{

"requestId": "538d0ca4-9d8b-4b8c-ab02-c68bc1623ed3",

"txHash": "0x99a93c8ba06865bd7054835d5f9abe57424289dca15ea61fe55a33a0651b058c"

Response Sample

{
  "code": 0,
  "message": "success"
}

{

"code": 0,

"message": "success"

}

트랜잭션 목록 조회

요청한 트랜잭션들 목록을 조회합니다. 요청한 트랜잭션이 블록체인에 잘 기록되면 트랜잭션 상태(transactions.txStatus)가 성공으로 업데이트됩니다.

Request URL

Live URL	https://bc-api.qpyou.cn/service/v1/tx
Sandbox URL	https://sandbox-bc-api.qpyou.cn/service/v1/tx
HTTP Method	GET
Content-Type	application/json

Header Parameters

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y
x-network	블록체인 네트워크{ploygon, xpla}	string	Y
x-appid	앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y

Query Parameters

필드명	설명	타입	필수 여부
playerId	플레이어 ID	string	N
startDate	트랜잭션 생성 일자 검색 조건(시작일, yyyy-mm-dd)	string	N
endDate	트랜잭션 생성 일자 검색 조건(종료일, yyyy-mm-dd)	string	N
page	현재 페이지 번호	number	N
limit	1개 페이지에 노출될 트랜잭션 건수	number	N

Responses

필드명	설명	타입
code	api 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json
transactions	트랜잭션 정보	array
transactions.appid	앱센터에서 등록한 앱 고유 식별 코드	string
transactions.playerId	플레이어 ID	number
transactions.address	트랜잭션을 생성한 지갑의 주소	string
transactions.contract	요청 트랜잭션의 컨트랙트 주소	string
transactions.requestId	API 호출에 대한 고유코드	string
transactions.requestParams	API 호출 파라미터	json
transactions.txType	트랜잭션 유형	string
transactions.txStatus	트랜잭션 상태	string
transactions.txHash	트랜잭션 Hash	string
transactions.createdAt	트랜잭션 생성일자	string
transactions.updatedAt	트랜잭션 업데이트일자	string
meta	페이지네이션 정보	json
meta.totalItems	총 건수	number
meta.itemCount	노출 건수	number
meta.itemsPerPage	페이지당 노출될 건수	number
meta.totalPages	총 페이지 수	number
meta.currentPage	현재 페이지 번호	number

Request Sample

curl -X 'GET' \
  'https://sandbox-bc-api.qpyou.cn/service/v1/tx?playerId=1324&startDate=2023-08-10&endDate=2023-08-10' \
  -H 'accept: application/json' \
  -H 'x-network: polygon' \
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuaGl2...'

curl -X 'GET' \

'https://sandbox-bc-api.qpyou.cn/service/v1/tx?playerId=1324&startDate=2023-08-10&endDate=2023-08-10' \

-H 'accept: application/json' \

-H 'x-network: polygon' \

-H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuaGl2...'

Response Sample

{
  "code": 0,
  "message": "success",
  "data": {
    "transactions": [
      {
        "appid": "com.com2us.hivesdk.c2xwallet.hivepc.kr.test",
        "address": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",
        "contract": "0xB3A634AAC8F04f1946C1c9Fc461055AC1Bdc4b34",
        "requestId": "1643105b-7669-4260-8679-ca967660df41",
        "requestParams": {
          "encoded": true,
          "tokenId": "1",
          "playerId": 1324,
          "callbackUrl": "https://withhive.com/",
          "nftContract": "0xa3fd0377a12b75ac2f70d5f69550332c96582b00",
          "lockContract": "0xB3A634AAC8F04f1946C1c9Fc461055AC1Bdc4b34",
          "lockContractOwner": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765"
        },
        "txType": "UNLOCK",
        "txStatus": "SUCCESS",
        "txHash": "0x78889d58613816c16389a7031634cc781fc725c3b3a88999524c92f67be89236",
        "createdAt": "2023-08-10T07:23:05.000Z",
        "updatedAt": "2023-08-10T07:25:00.000Z"
      }
    ],
    "meta": {
      "totalItems": 11,
      "itemCount": 1,
      "itemsPerPage": 1,
      "totalPages": 11,
      "currentPage": 1
    }
  }
}

{

"code": 0,

"message": "success",

"data": {

"transactions": [

{

"appid": "com.com2us.hivesdk.c2xwallet.hivepc.kr.test",

"address": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",

"contract": "0xB3A634AAC8F04f1946C1c9Fc461055AC1Bdc4b34",

"requestId": "1643105b-7669-4260-8679-ca967660df41",

"requestParams": {

"encoded": true,

"tokenId": "1",

"playerId": 1324,

"callbackUrl": "https://withhive.com/",

"nftContract": "0xa3fd0377a12b75ac2f70d5f69550332c96582b00",

"lockContract": "0xB3A634AAC8F04f1946C1c9Fc461055AC1Bdc4b34",

"lockContractOwner": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765"

"txType": "UNLOCK",

"txStatus": "SUCCESS",

"txHash": "0x78889d58613816c16389a7031634cc781fc725c3b3a88999524c92f67be89236",

"createdAt": "2023-08-10T07:23:05.000Z",

"updatedAt": "2023-08-10T07:25:00.000Z"

}

"meta": {

"totalItems": 11,

"itemCount": 1,

"itemsPerPage": 1,

"totalPages": 11,

"currentPage": 1

}

Token API

토큰 잔액 조회

토큰 소유자 계정 주소(from)의 현재 토큰 잔고를 조회합니다.

Request URL

Live URL	https://bc-api.qpyou.cn/service/v1/ft/{contract}/account/{from}/balance
Sandbox URL	https://sandbox-bc-api.qpyou.cn/service/v1/ft/{contract}/account/{from}/balance
HTTP Method	GET
Content-Type	application/json

Path Parameters

필드명	설명	타입	필수 여부
contract	토큰 컨트랙트 주소	string	Y
from	토큰 소유자 계정	string	Y

Header Parameters

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y
x-network	블록체인 네트워크{ploygon, xpla}	string	Y
x-appid	앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y

Responses

필드명	설명	타입
code	api 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json
data.value	토큰 잔액	string
data.rawValue	`data.decimals`을 적용하지 않은 토큰 잔액	string
data.decimals	토큰 소수점 최대 자리수	number
data.symbol	토큰 심볼	string
data.symbolUri	토큰 심볼 이미지 URI	string

Request Sample

curl -X 'GET' \
  'https://sandbox-bc-api.qpyou.cn/service/v1/ft/0x94853BdC9c6AdD50D7842D1A3117fab385457470/account/0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765/balance' \
  -H 'accept: application/json' \
  -H 'x-network: polygon' \
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6I...'

curl -X 'GET' \

'https://sandbox-bc-api.qpyou.cn/service/v1/ft/0x94853BdC9c6AdD50D7842D1A3117fab385457470/account/0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765/balance' \

-H 'accept: application/json' \

-H 'x-network: polygon' \

-H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6I...'

Response Sample

{
  "code": 0,
  "message": "success",
  "data": {
    "value": "999998999",
    "symbol": "ST",
    "decimals": 18,
    "rawValue": "999998999000000000000000000"
  }
}

{

"code": 0,

"message": "success",

"data": {

"value": "999998999",

"symbol": "ST",

"decimals": 18,

"rawValue": "999998999000000000000000000"

}

Contract API

컨트랙트 조회

컨트랙트를 배포한 계정 주소(owner)에서 배포한 컨트랙트를 조회합니다.

Request URL

Live URL	https://bc-api.qpyou.cn/service/v1/contract/owner/{owner}
Sandbox URL	https://sandbox-bc-api.qpyou.cn/service/v1/contract/owner/{owner}
HTTP Method	GET
Content-Type	application/json

Path Parameters

필드명	설명	타입	필수 여부
owner	컨트랙트를 배포한 계정 주소	string	Y

Header Parameters

필드명	설명	타입	필수 여부
Authorization	API를 호출하기 위한 인증 토큰	string	Y
x-network	블록체인 네트워크{ploygon, xpla}	string	Y
x-appid	앱 고유 ID입니다. Hive 콘솔 앱센터 > AppID 목록에서 확인할 수 있습니다.	string	Y

Query Parameters

필드명	설명	타입	필수 여부
contractType	컨트랙트 종류	string	N
page	현재 페이지 번호	number	N
limit	1개 페이지에 노출할 컨트랙트 개수	number	N

Responses

필드명	설명	타입
code	api 호출 결과 코드, 0:성공	number
message	결과 메시지	string
data	API 응답 데이터	json
data.contracts	컨트랙트 정보	array
data.contracts.network	체인정보	string
data.contracts.owner	컨트랙트 배포한 계정주소	string
data.contracts.address	컨트랙트 주소	string
data.contracts.type	컨트랙트 종류	string
data.contracts.name	컨트랙트 이름	string
data.contracts.gameIndex	게임 인덱스	number
data.contracts.gameName	게임 이름	string
data.contracts.symbol	컨트랙트 심볼 이미지 URI	string
data.contracts.symbolUri	컨트랙트 심볼 이미지 URI	string
data.contracts.createdAt	컨트랙트 등록일자	string
meta	페이지네이션 정보	json
meta.totalItems	총 건수	number
meta.itemCount	노출 건수	number
meta.itemsPerPage	페이지 당 노출될 건수	number
meta.totalPages	총 페이지 수	number
meta.currentPage	현재 페이지 번호	number

Request Sample

curl -X 'GET' \
  'https://sandbox-bc-api.qpyou.cn/service/v1/contract/owner/0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765?contractType=FT&limit=1' \
  -H 'accept: application/json' \
  -H 'x-network: polygon' \
  -H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydX...'

curl -X 'GET' \

'https://sandbox-bc-api.qpyou.cn/service/v1/contract/owner/0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765?contractType=FT&limit=1' \

-H 'accept: application/json' \

-H 'x-network: polygon' \

-H 'x-appid: com.com2us.hivesdk.c2xwallet.hivepc.kr.test' \

-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydX...'

Response Sample

{
  "code": 0,
  "message": "success",
  "data": {
    "contracts": [
      {
        "gameIndex": 539,
        "gameName": "HIVE SDK(en)",
        "owner": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",
        "address": "0x05524fd875255ebd9c5f8871015ccc37b7fb20de",
        "name": "Fungible Token",
        "type": "FT",
        "symbol": "Fungible Token",
        "symbolUri": "https://sandbox-bc-file.qpyou.cn/ipfs/QmfJ9oT8Yb69bGr9bKozoYFYDQ4e1qPy31q4W3xsxfVw9L",
        "createdAt": "2023-08-10T01:09:59.000Z",
        "network": "polygon"
      }
    ],
    "meta": {
      "totalItems": 5,
      "itemCount": 1,
      "itemsPerPage": 1,
      "totalPages": 5,
      "currentPage": 1
    }
  }
}

{

"code": 0,

"message": "success",

"data": {

"contracts": [

{

"gameIndex": 539,

"gameName": "HIVE SDK(en)",

"owner": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",

"address": "0x05524fd875255ebd9c5f8871015ccc37b7fb20de",

"name": "Fungible Token",

"type": "FT",

"symbol": "Fungible Token",

"symbolUri": "https://sandbox-bc-file.qpyou.cn/ipfs/QmfJ9oT8Yb69bGr9bKozoYFYDQ4e1qPy31q4W3xsxfVw9L",

"createdAt": "2023-08-10T01:09:59.000Z",

"network": "polygon"

}

"meta": {

"totalItems": 5,

"itemCount": 1,

"itemsPerPage": 1,

"totalPages": 5,

"currentPage": 1

}

Hive Blockchain API

사전 준비: API 인증 토큰 발급하기

NFT API

NFT 발행

Request URL

Path Parameters

Header Parameters

Request Body

Responses

Request Sample

Response Sample

NFT 조회

Request URL

Path Parameters

Header Parameters

Responses

Request Sample

Response Sample

Lock API

NFT 잠금

Request URL

Path Parameters

Header Parameters

Request Body

Responses

Request Sample

Response Sample

NFT 잠금 해제

Request URL

Path Parameters

Header Parameters

Request Body

Responses

Request Sample

Response Sample

Convert API

게임 재화와 게임 토큰을 교환

Request URL

Path Parameters

Header Parameters

Request Body

Responses

Request Sample

Response Sample

컨버트 풀 확인

Request URL

Path Parameters

Header Parameters

Responses

Request Sample

Response Sample

Transaction API

Txhash 등록

Request URL

Header Parameters

Request Body

Responses

Request Sample

Response Sample

트랜잭션 목록 조회

Request URL

Header Parameters

Query Parameters

Responses

Request Sample

Response Sample

Token API

토큰 잔액 조회

Request URL

Path Parameters

Header Parameters

Responses

Request Sample

Response Sample

Contract API

컨트랙트 조회

Request URL

Path Parameters

Header Parameters

Query Parameters