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.

1. Sign up at the Hive Console, go to AppCenter > Game List > Register new game.
2. 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”
3. 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.
4. Insert the ID and the Secret key in the request body of auth-token APIand call this API.
5. 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

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

Header parameters

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
  }
}

Query contract resource information

Returns the information of the registered contract resources.

Request URL

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

Header parameters

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

Live URL	https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
Sandbox URL	https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
HTTP Method	PATCH
Content-Type	application/json

Path parameters

Field Name	Description	Type	Required
resourceId	the contract resource ID	string	Y

Header parameters

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

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

Header parameters

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
  }
}

Get deployed contract information

Returns the contract information deployed on a blockchain.

Request URL

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

Header parameters

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

Live URL	https://bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}
Sandbox URL	https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}
HTTP Method	PATCH
Content-Type	application/json

Path parameters

Field Name	Description	Type	Required
instanceId	the contract instance ID	string	Y

Header parameters

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

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

Path parameters

Field Name	Description	Type	Required
resourceId	the contract resource ID	string	Y

Header parameters

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"
    },
    ...
  ]
}

Get contract method information

Returns the function signature required to execute contract methods with the contract resource ID (resourceId) and the method name (method).

Request URL

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

Path parameters

Field Name	Description	Type	Required
resourceId	the contract resource ID	string	Y
method	the contract method name	string	Y

Header parameters

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

Live URL	https://bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}/query
Sandbox URL	https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}/query
HTTP Method	POST
Content-Type	application/json

Path parameters

Field Name	Description	Type	Required
instanceId	the contract instance ID	string	Y

Header parameters

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
    }
  }
}