Skip to content

KMS API

The cloud Key Management System (KMS) is a service where the cloud manages encrypted keys on behalf of users (Google Cloud Platform (GCP) KMS, Amazon Web Services (AWS) KMS).

Blockchain Open API - KMS API allows you to use keys stored in cloud KMS as your blockchain account wallet keys (private Key, or wallet private key). With the KMS API, users can generate transactions, sign them, and send them to the blockchain without directly managing their blockchain account wallet keys, via the keys stored in KMS instead. The cloud KMS platforms supported by the KMS API are GCP and AWS.

For example, the KMS API can be used as follows:


 

If you already have a key in cloud KMS

  1. Prepare cloud credentials
  2. Register cloud service account information (Credentials) at Hive Console > Blockchain > KMS Credentials > Add Credentials and obtain x-credential-id
  3. Prepare cloud KMS key information
  4. Call an API to register wallet address
  5. Acquire wallet address
  6. Query KMS wallet information
  7. Create transactions with KMS wallet: Call APIs for generating new transactions such as sending tokens and deploying smart contracts
  8. Sign the created transaction with KMS Sign API
  9. Send the signed transaction to the blockchain network


If you are not using cloud KMS, or if there are no keys in cloud KMS

  1. Prepare the cloud KMS service account
  2. Create wallet key: Generated it by the wallet key creation API
    1. Prepare cloud credentials
    2. Prepare Blockchain API authentication key
    3. Register cloud service account information (Credentials) at Hive Console > Blockchain > KMS Credentials > Add Credentials and obtain x-credential-id
    4. Use x-credential-id and the API authentication key to create KMS wallet key
    5. Acquire wallet key and wallet address
  3. Query KMS wallet information
  4. Create transactions with KMS wallet: Call APIs for generating new transactions such as sending tokens and deploying smart contracts
  5. Sign the created transaction with KMS Sign API
  6. Send the signed transaction to the blockchain network


Note

The transactions that can be signed with the KMS Sign API are only those created with the KMS wallet key.


Pre-requisites

Register your Cloud KMS Credentials in Hive Console > Blockchain > KMS Credentials > Add Credentials.

Creating blockchain account wallet address and KMS wallet key

Creates a wallet key in KMS using your cloud service account, and based on this wallet key, creates a blockchain account wallet address. The wallet key is stored in KMS and cannot be verified. If there is a delay during key creation process, the wallet address might not be included in the API response. You can retrieve the wallet address using the KMS Wallet Information Inquiry API with the key ID (keyId).

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/kms
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/kms
HTTP Method POST
Content-Type application/json

Header parameters

Field Name Description Type Required
x-network Blockchain network string Y
x-credential-id The unique value obtained when registering Credentials in the Hive Console string Y
Authorization The authentication token required to call the API string Y

Request body

Field Name Description Type Required
keyName Enter the desired name for the key to be created. string Y
keyOptions KMS wallet key option information json Y
keyOptions.location The location where the key will be stored. This refers to the KMS location information used by each cloud service. string * GCP: Y (location, example: asia-northeast3)
* AWS: Y (region, example: ap-northeast-2d)
keyOptions.project GCP project ID string * GCP: Y
* AWS: N
keyOptions.keyRing Information on GCP KeyRing string * GCP: Y
* AWS: N

Responses

Field Name Description Type
code API call result code, 0: Success number
message Result message string
data API response data json
data.keyId The unique ID of the created key string
data.keyName The alias of the created key string
data.address Blockchain account wallet address created with the KMS key string
data.purpose Purpose of the key usage string
data.algorithm Type of key generation algorithm string
data.cloudType Type of cloud platform string
data.network Blockchain network the key will be used on string
data.options Key option information json
data.options.project GCP project ID string
data.options.location The location where the key is stored string
data.options.keyRing Information on GCP KeyRing string
data.options.keyVersion Information on GCP key version string
data.regId Key registrant ID string
data.modId Key modifier ID string
data.createdAt Key registration date string
data.updatedAt Key modification date string

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms' 
  -H 'accept: application/json' 
  -H 'x-credential-id: eb6cc005-b8d0-bc96-8b60-a531c2f15fd2' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiO... 
  -H 'Content-Type: application/json' 
  -d '{
  "keyName": "test-key",
  "keyOptions": {
    "project": "test-project",
    "location": "asia-northeast3",
    "keyRing": "test-keyring"
    },
    "requesterId": "system"
    }'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "keyId": "test1-game-provider",
    "keyName": "projects/tribal-octane-403302/locations/asia-northeast3/keyRings/test-keyring-001/cryptoKeys/test1-game-provider/cryptoKeyVersions/1",
    "address": "0xc5AC98006fe612395b132742Fbe80a6Dc184670a",
    "purpose": "ASYMMETRIC_SIGN",
    "algorithm": "EC_SIGN_SECP256K1_SHA256",
    "cloudType": "gcp",
    "network": "polygon",
    "options": {
      "project": "project",
      "location": "asia-northeast3",
      "keyRing": "keyring",
      "keyVersion": "1"
    },
    "regId": "test",
    "modId": null,
    "createdAt": "2024-02-22T08:28:04.000Z",
    "updatedAt": null
  }
}

Register blockchain account wallet address

Create a blockchain account wallet address based on the KMS wallet key and register it to the Hive Server. When using GCP, you must specify the key version (keyVersion).

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/kms/import
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/kms/import
HTTP Method POST
Content-Type application/json

Header parameters

Field Name Description Type Required
x-network Blockchain network string Y
x-credential-id The unique value obtained when registering Credentials in the Hive Console string Y
Authorization The authentication token required to call the API string Y

Request body

Field Name Description Type Required
keys KMS wallet key information array(json) Y
keys.keyId The unique ID of the created key string Y
keys.keyVersion Key version information when using GCP string * GCP: Y
* AWS: N
keyOptions Key option information json Y
keyOptions.location The location to store the key. This is the KMS location information used by each cloud. string * GCP: Y (location, example: asia-northeast3)
* AWS: Y (region, example: ap-northeast-2d)
keyOptions.project GCP project ID string * GCP: Y
* AWS: N
keyOptions.keyRing Information on GCP key ring string * GCP: Y
* AWS: N
requesterId The requester ID. It is an arbitrary value to distinguish the API caller. The account ID logged into the Hive Console is entered as requesterId when a KMS wallet is created. string N

Responses

Field Name Description Type
code API call result code, 0: Success number
message Result message string
data API response data json
data.keyId The unique ID of the created key string
data.keyName The alias of the created key string
data.address Blockchain account wallet address created with the KMS key string
data.purpose Purpose of using the key string
data.algorithm Type of key generation algorithm string
data.cloudType Type of cloud platform string
data.network Blockchain network the key will be used on string
data.options Key option information json
data.options.project GCP project ID string
data.options.location Location where the key is stored string
data.options.keyRing Information on GCP key ring string
data.options.keyVersion Information on GCP key version string
data.regId ID of the key registrant. It is the same as requesterId. string
data.modId ID of the key modifier string
data.createdAt Key registration date string
data.updatedAt Key modification date string

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms/import' 
  -H 'accept: application/json' 
  -H 'x-credential-id: 9b3c0c1d-868c-71ea-a1a9-e615148b7f14' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiOm51bGwsInJvb...' 
  -H 'Content-Type: application/json' 
  -d '{
  "keys": [
    {
      "keyId": "test1-game-provider",
      "keyVersion": "1"
    }
  ],
  "keyOptions": {
    "project": "kms-test",
    "location": "asia-northeast3",
    "keyRing": "key-ring"
  },
  "requesterId": "system"
}'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "keyId": "kms-key-002",
    "keyName": "projects/quixotic-carver-412405/locations/asia-northeast3/keyRings/keyring/cryptoKeys/kms-key-002/cryptoKeyVersions/1",
    "address": "0x1e0481127b0ed12b6b6911bec32d414d76042860",
    "purpose": "ASYMMETRIC_SIGN",
    "algorithm": "EC_SIGN_SECP256K1_SHA256",
    "cloudType": "gcp",
    "network": "polygon",
    "options": {
      "project": "quixotic-carver-412405",
      "location": "asia-northeast3",
      "keyRing": "keyring",
      "keyVersion": "1"
    },
    "regId": "system",
    "modId": null,
    "createdAt": "2024-02-22T08:28:04.000Z",
    "updatedAt": null
  }
}

Retrieve KMS key wallet information and account wallet address

Retrieve KMS key wallet information and account wallet address using the unique ID (keyId) of the KMS wallet key or the key name (keyName). This can be used if you were unable to verify the wallet address when creating the key.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/kms/{key}
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/kms/{key}
HTTP Method GET
Content-Type application/json

Path parameters

Field Name Description Type Required
key Unique ID of the key, or the key name string Y

Header parameters

Field Name Description Type Required
x-credential-id The unique value obtained when registering Credentials in the Hive Console string Y
Authorization The authentication token required to call the API string Y

Responses

Field Name Description Type
code API call result code, 0:success number
message Result message string
data API response data json
data.keyId Unique ID of the created key string
data.keyName Alias of the created key string
data.purpose Purpose of key usage string
data.algorithm Type of key generation algorithm string
data.cloudType Type of cloud platform string
data.network Blockchain network the key will be used on string
data.options Key option information json
data.options.project GCP project ID string
data.options.location Location where the key is stored string
data.options.keyRing GCP key ring information string
data.options.keyVersion GCP key version information string
data.regId Key registrant ID string
data.modId Key modifier ID string
data.createdAt Key registration date string
data.updatedAt Key modification date string

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms/kms-key-002' 
  -H 'accept: application/json' 
  -H 'x-credential-id: 9b3c0c1d-868c-71ea-a1a9-e615148b7f14' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiOm51bGwsInJvbGUiOiJhZG1pb...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "keyId": "test1-game-provider",
    "keyName": "projects/tribal-octane-403302/locations/asia-northeast3/keyRings/test-keyring-001/cryptoKeys/test1-game-provider/cryptoKeyVersions/1",
    "address": "0xc5AC98006fe612395b132742Fbe80a6Dc184670a",
    "purpose": "ASYMMETRIC_SIGN",
    "algorithm": "EC_SIGN_SECP256K1_SHA256",
    "cloudType": "gcp",
    "network": "polygon",
    "options": {
      "project": "project",
      "location": "asia-northeast3",
      "keyRing": "keyring",
      "keyVersion": "1"
    },
    "regId": "test",
    "modId": null,
    "createdAt": "2024-02-22T08:28:04.000Z",
    "updatedAt": null
  }
}

Retrieve KMS key wallet information and account wallet address list

Retrieve the list of KMS key wallet information and account wallet addresses.

Request URL

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

Header parameters

Field Name Description Type Required
x-network Blockchain network string Y
x-credential-id The unique value obtained when registering Credentials in the Hive Console string Y
Authorization The authentication token required to call the API string Y

Query parameters

Field Name Description Type Required
page Current page number number N
limit Number of KMS key wallet information and account wallet addresses to display per page number N

Responses

Field Name Description Type
code API call result code, 0: success number
message Result message string
data API response data json
data.kms List of KMS wallet key information and wallet addresses array(json)
data.meta Pagination information json
data.meta.totalItems Total number of items queried (number of KMS wallet keys and wallet address information) number
data.meta.itemsPerPage Number of KMS wallet key and wallet address information displayed per page number
data.meta.totalPages Total number of pages number
data.meta.currentPage Current page number number

Information of each element contained in the data.kms array: KMS wallet key information and account wallet address

Field Name Description Type
keyId Unique ID of the created key string
keyName Alias of the created key string
address Blockchain account wallet address created with the KMS key string
purpose Purpose of using the key string
algorithm Type of key generation algorithm string
cloudType Type of cloud platform string
network Blockchain network where the key will be used string
options Key options information json
options.project GCP project ID string
options.location Location where the key is stored string
options.keyRing GCP keyring information string
options.keyVersion GCP key version information string
regId Key registrant ID string
modId Key modifier ID string
createdAt Key registration date string
updatedAt Key modification date string

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms?page=1&limit=10' 
  -H 'accept: application/json' 
  -H 'x-credential-id: 41e26545-547e-7632-be1f-289f75c092d2' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiOm51bGwsInJv...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "kms": [
      {
        "keyId": "test-polygon-001",
        "keyName": "projects/tribal-octane-403302/locations/asia-northeast3/keyRings/test-keyring-001/cryptoKeys/test-polygon-001/cryptoKeyVersions/1",
        "address": "0x599220fb6cd54553b9c2dfda3b0f711d7ebc21fb",
        "purpose": "ASYMMETRIC_SIGN",
        "algorithm": "EC_SIGN_SECP256K1_SHA256",
        "cloudType": "gcp",
        "network": "polygon",
        "options": {
          "project": "tribal-octane-403302",
          "location": "asia-northeast3",
          "keyRing": "test-keyring-001",
          "keyVersion": "1"
        },
        "regId": "system",
        "modId": null,
        "createdAt": "2024-02-22T08:27:58.000Z",
        "updatedAt": null
      },{
        "keyId": "kms-key-002",
        "keyName": "projects/quixotic-carver-412405/locations/asia-northeast3/keyRings/keyring/cryptoKeys/kms-key-002/cryptoKeyVersions/1",
        "address": "0x1e0481127b0ed12b6b6911bec32d414d76042860",
        "purpose": "ASYMMETRIC_SIGN",
        "algorithm": "EC_SIGN_SECP256K1_SHA256",
        "cloudType": "gcp",
        "network": "polygon",
        "options": {
          "project": "quixotic-carver-412405",
          "location": "asia-northeast3",
          "keyRing": "keyring",
          "keyVersion": "1"
        },
        "regId": "system",
        "modId": null,
        "createdAt": "2024-02-22T08:28:04.000Z",
        "updatedAt": null
      }
    ],
    "meta": {
      "totalItems": 2,
      "itemCount": 2,
      "itemsPerPage": 10,
      "totalPages": 1,
      "currentPage": 1
    }
  }
}

Sign transaction with KMS wallet key

Sign transactions with the KMS wallet key. Only transactions created with the KMS wallet account can be signed with the KMS wallet key.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/kms/sign
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/kms/sign
HTTP Method POST
Content-Type application/json

Header parameters

Field Name Description Type Required
x-credential-id The unique value obtained when registering Credentials in the Hive Console string Y
Authorization The authentication token required to call the API string Y

Request body

Field Name Description Type Required
from The KMS wallet address from which the signature will be made. It must be identical to the from in the Request Body of the API (example) that creates the transaction. string Y
unsignedTx The unsigned transaction data. This is the data.rawTx you receive as a response when a transaction is created. The following types are supported for unsignedTx:
1. Transaction data
2. Multi-signature transaction data (when x-network is polygon)		 string Y

Responses

Field Name Description Type
code API call result code, 0: success number
message Result message string
data API response data json
data.signedTx The information of signed transaction string

Request sample

curl -X 'POST' 
  'http://sandbox-bc-api.qpyou.cn/core/v1/kms/sign' 
  -H 'accept: application/json' 
  -H 'x-credential-id: eb6cc005-b8d0-bc96-8b60-a531c2f15fd2' 
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20yd...' 
  -d '{
  "from": "0xc5AC98006fe612395b132742Fbe80a6Dc184670a",
  "unsignedTx": "0x5a0ca3a7eebbafa946da6ed0160930fc4f334887dbf11a9b38937ab8831fd125..."
}'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "signedData": "string"
  }
}