Remote Procedure Call (RPC)
RPC API Reference
By default, RPC API
listens on 20336
port.
The following option can be used to change the port at which the client side RPC API
listens:
ontology --rpcport 1024
The following option can be used to stop the client side RPC
service:
ontology --disable-rpc
Interface definition
The JSON-RPC
interface definition is as follows:
Request parameters
The structure of the request message is as follows:
Field
Data type
Description
jsonrpc
String
JSON-RPC version
method
String
Method name
params
String
Method parameters
id
Integer
Arbitrary value
Method list
Method
Parameters
Description
Note
height or blockhash,[verbose]
Get block by block height or block hash
Verbose can be 0 or 1, response is different
transactionhash
Returns the corresponding transaction information based on the specified hash value.
hex,preExec
Broadcast transaction.
Serialized signed transactions constructed in the program into hexadecimal strings
script_hash, key
Returns the stored value according to the contract address hash and storage key.
script_hash,[verbose]
According to the contract address hash, query the contract information.
getbalancev2
address
asset, from, to
Return the allowance from the from account to the to account, with ONT's decimals being 9, a ONG's decimals being 18
getsyncstatus
Fetch the synchronization status of the node
Response parameters
The structure of the response message after a request is sent is as follows:
Field
Data type
Description
desc
String
Request result description
error
Integer
Error code
jsonrpc
String
JSON-RPC
version
id
Integer
Arbitrary value
result
JSON object
RPC
execution result
getbestblockhash
getbestblockhash
Fetch block hash for the highest block for the current node.
Sample request
{
"jsonrpc": "2.0",
"method": "getbestblockhash",
"params": [],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 1,
"result": "773dd2dae4a9c9275290f89b56e67d7363ea4826dfd4fc13cc01cf73a44b0d0e"
}
getblock
getblock
Fetch block details using block hash or block height.
Sample request - using block hash
{
"jsonrpc": "2.0",
"method": "getblock",
"params": ["773dd2dae4a9c9275290f89b56e67d7363ea4826dfd4fc13cc01cf73a44b0d0e"],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 1,
"result": "00000000ccc7612928aab25db55ab31c35c64929ce4d89f9a16d0753fddf9da63d0c339b77be0e825f3180b4d706045e42a101f5becea5d59a7d6aac58cdff0c0bd0b6a949c6405eae477bb053406c0a4f56a830289798e2d70dc77e0a1d927fa9fb93c47625f316f1bb594150e0f4c3b4c4c6394e0444f876c766b0130527ac46c766b0130c3648c00616c766b51c3c0519c009c6c766b0131527ac46c766b0131c3641000616c766b52c30052c461625400616c766b51c300c36c766b0132527ac46c766b0132c36165b3206c..."
}
Sample request - using block height
{
"jsonrpc": "2.0",
"method": "getblock",
"params": [100],
"id": 1
}
Sample response
{
"desc": "SUCCESS",
"error": 0,
"id": 1,
"jsonrpc": "2.0",
"result": {
"Hash": "95555da65d6feaa7cde13d6bf12131f750b670569d98c63813441cf24a99c0d2",
"Header": {
"Version": 0,
"PrevBlockHash": "205c905493c7c1e3be7cd58542e45aafb007edcb8363f8ff555f63745f1b7ce5",
"TransactionsRoot": "4452db2634d81e80048002c2f327b25ded4e547ebfcc1b28f28608938b9d2154",
"BlockRoot": "42e01a2b27c182d4e115883c3b166a0fbc019efe2498b568b7febcc83a35346e",
"Timestamp": 1522295648,
"Height": 2,
"ConsensusData": 10322907760044199803,
"NextBookkeeper": "TAAr9AH4NqxXSKur7XTUbmP8wsKD4KPL2t",
"Bookkeepers": [
"120203e45fe0189a36b284e6080c6983cf12879d239886ecee1e257ab992970ecaa000"
],
"SigData": [
"014ed021011a6e0a4e9771b0be9fd156f9fc411968ce1dc4aed18382c85f6827d50373f3e3931966066cdc7dfab52823b79c80df8af25569c33ddf8140df5385b6"
],
"Hash": "95555da65d6feaa7cde13d6bf12131f750b670569d98c63813441cf24a99c0d2"
},
"Transactions": [
{
"Version": 0,
"Nonce": 0,
"TxType": 0,
"Payload": {
"Nonce": 1522295648487066000
},
"Attributes": [],
"Fee": [],
"NetworkFee": 0,
"Sigs": [
{
"PubKeys": [
"120203e45fe0189a36b284e6080c6983cf12879d239886ecee1e257ab992970ecaa000"
],
"M": 1,
"SigData": [
"01021197ad4140a50442b700ad814aeb2595578bf4d97e187a69aacf35917be4a27f76bc1dad2ee9bb386be79ca9638e78e14c869edbc3556499b06cc9c9b9452e"
]
}
],
"Hash": "4452db2634d81e80048002c2f327b25ded4e547ebfcc1b28f28608938b9d2154"
}
]
}
}
getblockcount
getblockcount
Fetch current block count.
Sample request
{
"jsonrpc": "2.0",
"method": "getblockcount",
"params": [],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 1,
"result": 2519
}
getblockhash
getblockhash
Fetch the block hash for the block at given block height.
Sample request
{
"jsonrpc": "2.0",
"method": "getblockhash",
"params": [10000],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 1,
"result": "4c1e879872344349067c3b1a30781eeb4f9040d3795db7922f513f6f9660b9b2"
}
getconnectioncount
getconnectioncount
The no. of nodes connected to the current network.
Sample request
{
"jsonrpc": "2.0",
"method": "getconnectioncount",
"params": [],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 1,
"result": 10
}
getrawtransaction
getrawtransaction
Fetch transaction details using transaction hash.
Sample request - non verbose
{
"jsonrpc": "2.0",
"method": "getrawtransaction",
"params": ["f4250dab094c38d8265acc15c366dc508d2e14bf5699e12d9df26577ed74d657"],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 1,
"result": "80000001195876cb34364dc38b730077156c6bc3a7fc570044a66fbfeeea56f71327e8ab0000029b7cffdaa674beae0f930ebe6085af9093e5fe56b34a5c220ccdcf6efc336fc500c65eaf440000000f9a23e06f74cf86b8827a9108ec2e0f89ad956c9b7cffdaa674beae0f930ebe6085af9093e5fe56b34a5c220ccdcf6efc336fc50092e14b5e00000030aab52ad93f6ce17ca07fa88fc191828c58cb71014140915467ecd359684b2dc358024ca750609591aa731a0b309c7fb3cab5cd0836ad3992aa0a24da431f43b68883ea5651d548feb6bd3c8e16376e6e426f91f84c58232103322f35c7819267e721335948d385fae5be66e7ba8c748ac15467dcca0693692dac"
}
Sample response - verbose
{
"jsonrpc": "2.0",
"method": "getrawtransaction",
"params": ["5623dbd283a99ff1cd78068cba474a22bed97fceba4a56a9d38ab0fbc178c4ab", 1],
"id": 1
}
Sample response
{
"desc": "SUCCESS",
"error": 0,
"id": 1,
"jsonrpc": "2.0",
"result": {
"Version": 0,
"Nonce": 3743545316,
"GasPrice": 500,
"GasLimit": 20000,
"Payer": "AWM9vmGpAhFyiXxg8r5Cx4H3mS2zrtSkUF",
"TxType": 209,
"Payload": {
"Code": "00c66b149fdd13f41303beb7771ddd0aad6b2d815dcd62916a7cc81400000000000000000000000000000000000000016a7cc8149fdd13f41303beb7771ddd0aad6b2d815dcd62916a7cc8085da07645000000006a7cc86c0c7472616e7366657246726f6d1400000000000000000000000000000000000000020068164f6e746f6c6f67792e4e61746976652e496e766f6b65"
},
"Attributes": [],
"Sigs": [
{
"PubKeys": [
"03e9ac636107c8d5a22e87bf6ae76a5e7a1394930972db72e0c3bebf54e8210a37"
],
"M": 1,
"SigData": [
"01dfcf5328a6587b2e2b30d6fae73bc18343ce7e5db2c00b3c92415a7274cfb1367d74604121dfd2eb8aef95b1a5e688bdde5633f1bde0fe85881db55ea2fd112d"
]
}
],
"Hash": "5623dbd283a99ff1cd78068cba474a22bed97fceba4a56a9d38ab0fbc178c4ab",
"Height": 175888
}
}
sendrawtransaction
sendrawtransaction
Transmit a transaction to the network.
Sample request
{
"jsonrpc": "2.0",
"method": "sendrawtransaction",
"params": ["80000001195876cb34364dc38b730077156c6bc3a7fc570044a66fbfeeea56f71327e8ab0000029b7cffdaa674beae0f930ebe6085af9093e5fe56b34a5c220ccdcf6efc336fc500c65eaf440000000f9a23e06f74cf86b8827a9108ec2e0f89ad956c9b7cffdaa674beae0f930ebe6085af9093e5fe56b34a5c220ccdcf6efc336fc50092e14b5e00000030aab52ad93f6ce17ca07fa88fc191828c58cb71014140915467ecd359684b2dc358024ca750609591aa731a0b309c7fb3cab5cd0836ad3992aa0a24da431f43b68883ea5651d548feb6bd3c8e16376e6e426f91f84c58232103322f35c7819267e721335948d385fae5be66e7ba8c748ac15467dcca0693692dac",0],
"id": 1
}
Sample response
{
"desc": "SUCCESS",
"error": 0,
"id": 1,
"jsonrpc": "2.0",
"result": "498db60e96828581eff991c58fa46abbfd97d2f4a4f9915a11f85c54f2a2fedf"
}
getstorage
getstorage
Fetched the stored value using contract hash and the storage key.
Sample request
{
"jsonrpc": "2.0",
"method": "getstorage",
"params": ["03febccf81ac85e3d795bc5cbd4e84e907812aa3", "5065746572"],
"id": 15
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 15,
"result": "4c696e"
}
The contract address can be generated from the AVM code using SDK methods.
Python SDK
from ontology.common.address import Address
from ontology.utils.contract_data import ContractDataParser
code = '0000000000000000000000000000000000000001'
contract_address = Address.address_from_vm_code(code).to_hex_str()
Go SDK
package demo
import (
"fmt"
"github.com/ontio/ontology/common"
"testing"
)
func TestAddressFromVmCode(t *testing.T) {
var avmCode, _ = common.HexToBytes("0000000000000000000000000000000000000001")
addr := common.AddressFromVmCode(avmCode)
var contractAddr = addr.ToHexString()
}
Java SDK
package demo;
import com.github.ontio.OntSdk;
import com.github.ontio.common.Address;
public class NetworkDemo {
public static void main(String[] args) {
try {
OntSdk sdk = OntSdk.getInstance();
String code = "0000000000000000000000000000000000000004";
String contractAddress = Address.AddressFromVmCode(code).toHexString();
} catch (Exception e) {
e.printStackTrace();
}
}
}
getversion
getversion
Fetch the version of the current node.
Sample request
{
"jsonrpc": "2.0",
"method": "getversion",
"params": [],
"id": 3
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 3,
"result": "v0.9.2-1-g231e"
}
getcontractstate
getcontractstate
Fetch contract details using contract address.
Sample request
{
"jsonrpc": "2.0",
"method": "getcontractstate",
"params": ["0100000000000000000000000000000000000000",1],
"id": 1
}
Sample response
{
"desc": "SUCCESS",
"error": 0,
"id": 1,
"jsonrpc": "2.0",
"result": {
"Code": "0000000000000000000000000000000000000001",
"NeedStorage": true,
"Name": "ONT",
"CodeVersion": "1.0",
"Author": "Ontology Team",
"Email": "[email protected]",
"Description": "Ontology Network ONT Token"
}
}
getmempooltxcount
getmempooltxcount
Fetch the no. of transactions in the node memory pool.
Sample request
{
"jsonrpc": "2.0",
"method": "getmempooltxcount",
"params": [],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 1,
"result": [100,50]
}
getmempooltxstate
getmempooltxstate
Fetch state of transaction in the node memory pool using given transaction hash.
Sample request
{
"jsonrpc": "2.0",
"method": "getmempooltxstate",
"params": ["773dd2dae4a9c9275290f89b56e67d7363ea4826dfd4fc13cc01cf73a44b0d0e"],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 1,
"result": {
"State": [{
"Type": 1,
"Height": 342,
"ErrCode": 0
}, {
"Type": 0,
"Height": 0,
"ErrCode": 0
}]
}
}
getsmartcodeevent
getsmartcodeevent
Fetch smart contract execution result using block height or transaction hash.
Sample request - using block height
{
"jsonrpc": "2.0",
"method": "getsmartcodeevent",
"params": [3],
"id": 3
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 3,
"result": [
{
"TxHash": "7e8c19fdd4f9ba67f95659833e336eac37116f74ea8bf7be4541ada05b13503e",
"State": 1,
"GasConsumed": 0,
"Notify": [
{
"ContractAddress": "0200000000000000000000000000000000000000",
"States": [
"transfer",
"AFmseVrdL9f9oyCzZefL9tG6UbvhPbdYzM",
"AFmseVrdL9f9oyCzZefL9tG6UbvhUMqNMV",
1000000000000000000
]
}
]
},
{
"TxHash": "fc82cd363271729367098fbabcfd0c02cf6ded1e535700d04658b596d53cf07d",
"State": 1,
"GasConsumed": 0,
"Notify": [
{
"ContractAddress": "0200000000000000000000000000000000000000",
"States": [
"transfer",
"AFmseVrdL9f9oyCzZefL9tG6UbvhPbdYzM",
"AFmseVrdL9f9oyCzZefL9tG6UbvhUMqNMV",
1000000000000000000
]
}
]
},
{
"TxHash": "6b391812b6a3230c057b108227f78a1c7caa9fa934817c60540af55e62167507",
"State": 1, // Execution successful
"GasConsumed": 0, // Amount of gas consumed gasLimit * gasprice
"Notify": [
{
"ContractAddress": "49f0908f08b3ebce1e71dc5083cb9a8a54cc4a24", // Contract address
"States": "57b108227f78a1c7caa9fa934817c60540af55e62167507" // Hex string
}
]
}
]
}
Sample request - using transaction hash
{
"jsonrpc": "2.0",
"method": "getsmartcodeevent",
"params": ["3ba4b4e463a717635614595378f2aac78feacc7d4dfda075bfcf9328cbbcdb7c"],
"id": 3
}
Sample response
{
"desc": "SUCCESS",
"error": 0,
"id": 1,
"jsonrpc": "2.0",
"result": {
"TxHash": "20046da68ef6a91f6959caa798a5ac7660cc80cf4098921bc63604d93208a8ac",
"State": 1,
"GasConsumed": 0,
"Notify": [
{
"ContractAddress": "ff00000000000000000000000000000000000001",
"States": [
"transfer",
"T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
"TA4WVfUB1ipHL8s3PRSYgeV1HhAU3KcKTq",
1000000000
]
}
]
}
}
Response parameters
Field
Description
TxHash
Transaction hash
State
Transaction execution status, 0 indicates execution failure, 1 indicates execution success
GasConsumed
Amount of gas consumed for execution
Notify
Contract events triggered by the transaction
The two fields within Notify
:
Field
Description
ContractAddress
Contract address where the event occurred
States
Event details
getblockheightbytxhash
getblockheightbytxhash
Fetch the block height for the block in which a particular transaction is recorded using transaction hash.
Sample request
{
"jsonrpc": "2.0",
"method": "getblockheightbytxhash",
"params": ["c453557af780fe403db6e954ebc9adeafd5818c596c6c60e5cc42851c5b41884"],
"id": 1
}
Sample response
{
"desc": "SUCCESS",
"error": 0,
"id": 1,
"jsonrpc": "2.0",
"result": 10
}
getbalance
getbalance
Fetch the current balance of a Base58 address.
Sample request
{
"jsonrpc": "2.0",
"method": "getbalance",
"params": ["TA5uYzLU2vBvvfCMxyV2sdzc9kPqJzGZWq"],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result":{
"ont": "2500",
"ong": "0"
}
}
getbalancev2
getbalancev2
Return the allowance from the from account to the to account, with ONT's decimals being 9, a ONG's decimals being 18.
Sample request
{
"jsonrpc": "2.0",
"method": "getbalancev2",
"params": ["TA5uYzLU2vBvvfCMxyV2sdzc9kPqJzGZWq"],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result":{
"ont": "999999996000000000",
"ong": "999999998000000000000000000",
"height":"1455"
}
}
getmerkleproof
getmerkleproof
Fetches the merkle proof for a transaction using given transaction hash.
Sample request
{
"jsonrpc": "2.0",
"method": "getmerkleproof",
"params": ["0087217323d87284d21c3539f216dd030bf9da480372456d1fa02eec74c3226d"],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result":{
"Type": "MerkleProof",
"TransactionsRoot": "fe3a4ee8a44e3e588de55de1b8fe08f08b6184d9c062cf7316fb9481eb57b9e6",
"BlockHeight": 600,
"CurBlockRoot": "57476eba688531dec8555cb712835c7eda48a478431a2cfd3372aeee5298e711",
"CurBlockHeight": 6478,
"TargetHashes": [
"270cd10ea235cc18cba83a070fdf18ae576983b6b9a7bb9a3fec540b3786c85c",
"24e4697f9dd6cb944d0736bd3e11b64f64edec94fb599e25d4e5461d54174f0e",
"9a47ab04acf6bba7bb97b83eddeb0db20e11c0627b8079b40b60031d5bd63154",
"d1b513810b9b983014c9f8b7084b8ea8744eca8e7c942586c2b7c63f910363ca",
"54e88360efedcf5dbbc486ea0267724a98b027b3ba780617e32569bb3fbe56e8",
"e0c5ebca3ca191617d42e11db64778b047cd9a520538efd95d5a688cbba0c8d5",
"52bfb23b6456cac4e5e7143287e1518dd923c5b5d32d0bfe8d825dc8195ea62b",
"86d6be166ae1a53c052adc40b9b66c4f95f5e3b6ecc88afaea3750e1cbe98276",
"5588530cfc4d92e979717f8ae399ac4553a76e7537a981e8eaf078d60f1d39a6",
"3f15bec38bcf054e4f32efe475a09d3e80c2e90d3345a1428aaa262606f13267",
"f238ed8ceb1c10a08f7eaa390cdde44ed7d160abbde4702028407b55671e7aa8",
"b4813f1f27c0457726b58f8bf20bee70c100a4d5c5f1805e53dcd20f38479615",
"83893713ea8ace9214b28af854b75671c8aaa62bb74b0d43ad6fb83e3dee42db"
]
}
}
getgasprice
getgasprice
Fetch current gas price.
Sample request
{
"jsonrpc": "2.0",
"method": "getgasprice",
"params": [],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result":{
"gasprice": 0,
"height": 1
}
}
getallowance
getallowance
Fetch the amount of a given asset allocated as allowance to an address.
Sample request
{
"jsonrpc": "2.0",
"method": "getallowance",
"params": ["ont","from address","to address"],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result": "10"
}
getallowancev2
getallowancev2
return the allowance from transfer-from accout to transfer-to account, ont decimals is 9,ong decimals is 18
Sample request
{
"jsonrpc": "2.0",
"method": "getallowancev2",
"params": ["ont","from address","to address"],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result": "100000000000"
}
getgrantong
getgrantong
Fetch the amount of granted ONG.
Sample request
{
"jsonrpc": "2.0",
"method": "getgrantong",
"params": ["AKDFapcoUhewN9Kaj6XhHusurfHzUiZqUA"],
"id": 3
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 3,
"result": 4995625
}
getunboundong
getunboundong
Fetch the amount of unbound ONG that can be withdrawn for a particular address.
Sample request
{
"jsonrpc": "2.0",
"method": "getunboundong",
"params": ["address"],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result": "204957950400000"
}
getblocktxsbyheight
getblocktxsbyheight
Fetches transaction hashes of all the transactions in the block at a given height.
Sample request
{
"jsonrpc": "2.0",
"method": "getblocktxsbyheight",
"params": [100],
"id": 1
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result": {
"Hash": "ea5e5219d2f1591f4feef89885c3f38c83d3a3474a5622cf8cd3de1b93849603",
"Height": 100,
"Transactions": [
"37e017cb9de93aa93ef817e82c555812a0a6d5c3f7d6c521c7808a5a77fc93c7"
]
}
}
getnetworkid
getnetworkid
Fetch the network ID of the current network.
Sample request
{
"jsonrpc": "2.0",
"method": "getnetworkid",
"params": [],
"id": 3
}
Sample response
{
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 3,
"result": 1
}
Error codes
The error codes in the response message signify the following:
Field
Data type
Description
0
int64
Success
41001
int64
Session timeout or invalid
41002
int64
Service limit reached
41003
int64
Invalid data format
41004
int64
Invalid version number
42001
int64
Invalid function
42002
int64
Invalid parameter
43001
int64
Invalid transaction
43002
int64
Invalid resource
43003
int64
Invalid block
44001
int64
Unknown transaction
44002
int64
Unknown resource
44003
int64
Unknown block
45001
int64
Internal error
47001
int64
Smart contract execution error
Last updated
Was this helpful?