Contract API
Contract API offers the following features.
- Register, query, and modify contract resources
- Deploy, query, modify contract and execute contract methods
Pre-requisites: Get API authentication token
To call a Contract API, you have to append an auth token to the header of an API. This is how to get your API auth token.
- Sign up at the Hive Console, go to AppCenter > Game List > Register new game.
- Create an new AppID at AppCenter > AppID List > Register new AppID.
- Register new AppID: Web Login AppID
- Purpose of use: Blockchain
- AppID to use:Choose “automatically generated AppID” or “automatically generated AppID” with “Additional Information”
- Go to the the Hive Console > Blockchain > Search for API Authentication Key, select and search the game name, and get the ID and the Secret key.
- Insert the ID and the Secret key in the request body of auth-token APIand call this API.
- You can get your API auth key as
data.accessToken in the API responses.
Register contract resources
Registers the resources of a contract. Register the contract name (contractName), the contract description (contractDesc), and the bytecode and ABI/Scheme generated after the contract is compiled.
Note
- The contract resources are not recorded on a blockchain.
- The contract must be written in Solidity or Rust.
Request URL
| Field Name | Description | Type | Required |
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
Request body
| Field Name | Description | Type | Required |
| from | the address of the contract owner | string | Y |
| contractName | the contract name | string | Y |
| contractDesc | the description for the contract | string | Y |
| contractAbi | the application binary interface that is generated when the contract is compiled. | file | Y |
| contractBytecode | the byte code that is generated when the contract is compiled | file | Y |
Responses
| Field Name | Description | Type |
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.resourceId | the contract resource ID | number |
Request sample
curl -X 'POST'
'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource'
-H 'accept: */*'
-H 'x-network: polygon'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2...'
-H 'Content-Type: multipart/form-data'
-F 'from=0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0'
-F 'contractName=Com2us Sample Token Contract'
-F 'contractDesc=Fungible Token Contract'
-F 'contractAbi=@erc20-capped.json;type=application/json'
-F 'contractBytecode=@erc20-capped.code'
Response sample
// polygon
{
"code": 0,
"message": "success",
"data": {
"resourceId": 1
}
}
// xpla
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f873830138810c8451f4d5c08451f4d5cf83018c0694572f47db51a98...",
"resourceId": 1
}
}
Returns the information of the registered contract resources.
Request URL
| Field Name | Description | Type | Required |
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
Query parameters
| Field Name | Description | Type | Required |
| resourceId | the contract resource ID | string | N |
Responses
| Field Name | Description | Type |
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.resourceId | the contract resource ID | number |
| data.network | the blockchain network | string |
| data.tenantId | the ID of the one who registered the contract resource | string |
| data.contractName | the contract name | string |
| data.contractDesc | the description for the contract | string |
| data.codeId | the contract code ID (only for XPLA blockchain) | string |
| data.updatedAt | the date the contract was registered | string |
| data.createdAt | the date the contract was modified | string |
Request sample
curl -X 'GET'
'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource?resourceId=1'
-H 'accept: */*'
-H 'x-network: polygon'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb...'
Response sample
{
"code": 0,
"message": "success",
"data": [
{
"resourceId": 1,
"network": "polygon",
"tenantId": "com.com2us.c2xwallet.global.normal",
"contractName": "Com2us Sample Token Contract",
"contractDesc": "Fungible Token Contract",
"codeId": null,
"updatedAt": "2023-07-27T18:05:25.000Z",
"createdAt": "2023-07-27T18:05:25.000Z"
}
]
}
Modify contract resources
Modifies the registered contract resources. Modifies the contract description (contractDesc), the bytecode, or the ABI/Scheme.
Request URL
Path parameters
| Field Name | Description | Type | Required |
| resourceId | the contract resource ID | string | Y |
| Field Name | Description | Type | Required |
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
Request body
| Field Name | Description | Type | Required |
| from | the address of the contract owner | string | Y |
| contractDesc | the description for the contract | string | N |
| codeId | This is the contract code ID (only for XPLA blockchain). It is obtained when you deploy a contract on the XPLA blockchain. | string | N |
| contractAbi | the application binary interface that is generated when the contract is compiled. | file | N |
| contractBytecode | the byte code that is generated when the contract is compiled | file | N |
Note
Send the contract deploying transaction to XPLA blockchain, get txHash, and search it on the XPLA Explorer, and then you can find codeId at the Event Logs.
Responses
| Field Name | Description | Type |
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.resourceId | the contract resource ID | number |
Request sample
curl -X 'PATCH'
'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/1'
-H 'accept: */*'
-H 'x-network: polygon'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNv...'
-H 'Content-Type: multipart/form-data'
-F 'from=0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0'
-F 'contractDesc=Fungible Token Contract'
-F 'codeId=20'
Response sample
{
"code": 0,
"message": "success",
"data": {
"resourceId": 1
}
}
Deploy contract
Creates a transaction that can deploy a new contract based on the previously registered contract resources (the bytecode and ABI/Scheme). This API can deploy all types (including NFT and FT, the Fungible Token) of contract.
Request URL
| Field Name | Description | Type | Required |
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
Path parameters
| Field Name | Description | Type | Required |
| resourceId | the contract resource ID | string | Y |
Request body
| Field Name | Description | Type | Required |
| from | the wallet address that deploys the contract | string | Y |
| message | the initial configuration information that is required to deploy the contract | json | Y |
| encoded | whether the returned transaction is encoded or not
* true: Receive the encoded raw transaction string (data.rawTx).
* false: Receive the decoded data.rawTx (JSON). | boolean | N |
Responses
| Field Name | Description | Type |
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | json |
| data.rawTx | the transaction data | string or json |
| data.instanceId | the contract instance ID | number |
Request sample
curl -X 'POST'
'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/2'
-H 'accept: */*'
-H 'x-network: polygon'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb...'
-H 'Content-Type: application/json'
-d '{
"from": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0",
"message": {
"name": "testft",
"symbol": "tft",
"decimals": 6,
"initialSupply": "1000000000"
},
"encoded": true
}'
Response sample
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f91c9c830138811a84513619a084513619b...",
"instanceId": 1
}
}
Returns the contract information deployed on a blockchain.
Request URL
| Field Name | Description | Type | Required |
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
Query parameters
| Field Name | Description | Type | Required |
| instanceId | the contract instance ID | string | N |
Responses
| Field Name | Description | Type |
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | array |
| data.resourceId | the contract resource ID | number |
| data.instanceId | the contract instance ID | number |
| data.contractAddress | the contract address | string |
| data.initMsg | the initial configuration information when deploying the contract | json |
| data.createdAt | the date when the contract was recorded on a blockchain | string |
| data.network | the blockchain network information | string |
| data.tenantId | the ID of the contract deployer | string |
Request sample
curl -X 'GET'
'https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance?instanceId=1'
-H 'accept: */*'
-H 'x-network: polygon'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20yd...'
Response sample
{
"code": 0,
"message": "success",
"data": [
{
"resourceId": 2,
"instanceId": 1,
"contractAddress": null,
"initMsg": {
"name": "testft",
"symbol": "tft",
"decimals": 6,
"initialSupply": "1000000000"
},
"createdAt": "2023-07-28T17:35:22.000Z",
"network": "polygon",
"tenantId": "com.com2us.c2xwallet.global.normal"
}
]
}
Modify contract instance address
Update the deployed contract address with the contract instance ID (instanceId).
Request URL
Path parameters
| Field Name | Description | Type | Required |
| instanceId | the contract instance ID | string | Y |
| Field Name | Description | Type | Required |
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
Query parameters
| Field Name | Description | Type | Required |
| contractAddress | the contract address | string | Y |
Responses
| Field Name | Description | Type |
| code | api request result code, 0: success | number |
| message | the result message | string |
Request sample
curl -X 'PATCH'
'https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/1?contractAddress=0x78ce8698bd69fc96d425a82ae6813f553a673e63'
-H 'accept: */*'
-H 'x-network: polygon'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJp...'
Response sample
{
"code": 0,
"message": "success"
}
Query contract method list
Returns the list of the contract methods by the contract resource ID (resourceId).
Request URL
Path parameters
| Field Name | Description | Type | Required |
| resourceId | the contract resource ID | string | Y |
| Field Name | Description | Type | Required |
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
Responses
| Field Name | Description | Type |
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | API response data | array |
| data.methodName | the contract method name | string |
| data.type | the contract method type
* execute: insert data into the contract or modify the existing data in the contract
* query: Get Contract Information | string |
Request sample
curl -X 'GET'
'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/1/methods'
-H 'accept: */*'
-H 'x-network: polygon'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20yd...'
Response sample
{
"code": 0,
"message": "success",
"data": [
{
"methodName": "allowance",
"type": "query"
},
{
"methodName": "totalSupply",
"type": "query"
},
...
]
}
Returns the function signature required to execute contract methods with the contract resource ID (resourceId) and the method name (method).
Request URL
Path parameters
| Field Name | Description | Type | Required |
| resourceId | the contract resource ID | string | Y |
| method | the contract method name | string | Y |
| Field Name | Description | Type | Required |
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
Responses
| Field Name | Description | Type |
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | This is the data required to execute contract methods (the method name and the input parameters of the method). | json |
Request sample
curl -X 'GET'
'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/2/method/balanceOf'
-H 'accept: */*'
-H 'x-network: polygon'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20...'
Response sample
{
"code": 0,
"message": "success",
"data": {
"balanceOf": {
"account": "address"
}
}
}
Execute contract method
Executes the contract method with the method name and the input parameters (message) of the method.
Request URL
Path parameters
| Field Name | Description | Type | Required |
| instanceId | the contract instance ID | string | Y |
| Field Name | Description | Type | Required |
| Authorization | The authentication token required to call APIs | string | Y |
| x-network | the blockchain networks | string | Y |
Request body
| Field Name | Description | Type | Required |
| from | the wallet address that requests executing the contract method | string | Y |
| message | the contract method name and the input parameters of the method | string | Y |
| encoded | whether the returned transaction is encoded or not
* true: Receive the encoded raw transaction string (data.rawTx).
* false: Receive the decoded data.rawTx (JSON). | boolean | N |
Responses
| Field Name | Description | Type |
| code | api request result code, 0: success | number |
| message | the result message | String |
| data | the returned value after executing the contract method | json |
Request sample
curl -X 'POST'
'https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/1/query'
-H 'accept: */*'
-H 'x-network: polygon'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb2...'
-H 'Content-Type: application/json'
-d '{
"from": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0",
"message": {
"balanceOf": {
"account": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0"
}
},
"encoded": true
}'
In general the contract methods are divided into 2 types: the query type and the execute type. The query type method just queries the data, and the execute type method writes new data in the contract or modifies the existing data in the contract. The execute type always returns the raw transaction, not like the query type.
Response sample: Query type
{
"code": 0,
"message": "success",
"data": "1000000000"
}
Response sample: Execute type (encoded is true)
{
"code": 0,
"message": "success",
"data": {
"rawTx": "02f8738301388181c2846fc23ac0846fc23ad882cdc49494853bdc9c6add50d7...",
}
}
Response sample: Execute type (encoded is false)
{
"code": 0,
"message": "success",
"data": {
"rawTx": {
"from": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",
"to": "0x94853BdC9c6AdD50D7842D1A3117fab385457470",
"data": "0xa9059cbb000000000000000000000000fbd488d1b00604d3b05124d80e35fea...",
"nonce": 224,
"chainId": 80001,
"gas": 52676,
"maxFeePerGas": 1575000048,
"maxPriorityFeePerGas": 1575000000
}
}
}