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:
Copy ontology --rpcport 1024
The following option can be used to stop the client side RPC
service:
Copy ontology --disable-rpc
Remote Procedure Call (RPC), also known as function call or subroutine call, are used on one machine on a network to request services from another machine without the need of detailed network information.
Interface definition
The JSON-RPC
interface definition is as follows:
Request parameters
The structure of the request message is as follows:
Method list
Response parameters
The structure of the response message after a request is sent is as follows:
getbestblockhash
Fetch block hash for the highest block for the current node.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getbestblockhash" ,
"params" : [] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"jsonrpc" : "2.0" ,
"id" : 1 ,
"result" : "773dd2dae4a9c9275290f89b56e67d7363ea4826dfd4fc13cc01cf73a44b0d0e"
}
getblock
Fetch block details using block hash or block height.
Sample request - using block hash
Copy {
"jsonrpc" : "2.0" ,
"method" : "getblock" ,
"params" : [ "773dd2dae4a9c9275290f89b56e67d7363ea4826dfd4fc13cc01cf73a44b0d0e" ] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"jsonrpc" : "2.0" ,
"id" : 1 ,
"result": "00000000ccc7612928aab25db55ab31c35c64929ce4d89f9a16d0753fddf9da63d0c339b77be0e825f3180b4d706045e42a101f5becea5d59a7d6aac58cdff0c0bd0b6a949c6405eae477bb053406c0a4f56a830289798e2d70dc77e0a1d927fa9fb93c47625f316f1bb594150e0f4c3b4c4c6394e0444f876c766b0130527ac46c766b0130c3648c00616c766b51c3c0519c009c6c766b0131527ac46c766b0131c3641000616c766b52c30052c461625400616c766b51c300c36c766b0132527ac46c766b0132c36165b3206c..."
}
Sample request - using block height
Copy {
"jsonrpc" : "2.0" ,
"method" : "getblock" ,
"params" : [ 100 ] ,
"id" : 1
}
Sample response
Copy {
"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
Fetch current block count.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getblockcount" ,
"params" : [] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"jsonrpc" : "2.0" ,
"id" : 1 ,
"result" : 2519
}
getblockhash
Fetch the block hash for the block at given block height.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getblockhash" ,
"params" : [ 10000 ] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"jsonrpc" : "2.0" ,
"id" : 1 ,
"result" : "4c1e879872344349067c3b1a30781eeb4f9040d3795db7922f513f6f9660b9b2"
}
getconnectioncount
The no. of nodes connected to the current network.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getconnectioncount" ,
"params" : [] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"jsonrpc" : "2.0" ,
"id" : 1 ,
"result" : 10
}
getrawtransaction
Fetch transaction details using transaction hash.
Sample request - non verbose
Copy {
"jsonrpc" : "2.0" ,
"method" : "getrawtransaction" ,
"params" : [ "f4250dab094c38d8265acc15c366dc508d2e14bf5699e12d9df26577ed74d657" ] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"jsonrpc" : "2.0" ,
"id" : 1 ,
"result": "80000001195876cb34364dc38b730077156c6bc3a7fc570044a66fbfeeea56f71327e8ab0000029b7cffdaa674beae0f930ebe6085af9093e5fe56b34a5c220ccdcf6efc336fc500c65eaf440000000f9a23e06f74cf86b8827a9108ec2e0f89ad956c9b7cffdaa674beae0f930ebe6085af9093e5fe56b34a5c220ccdcf6efc336fc50092e14b5e00000030aab52ad93f6ce17ca07fa88fc191828c58cb71014140915467ecd359684b2dc358024ca750609591aa731a0b309c7fb3cab5cd0836ad3992aa0a24da431f43b68883ea5651d548feb6bd3c8e16376e6e426f91f84c58232103322f35c7819267e721335948d385fae5be66e7ba8c748ac15467dcca0693692dac"
}
Sample response - verbose
Copy {
"jsonrpc" : "2.0" ,
"method" : "getrawtransaction" ,
"params" : [ "5623dbd283a99ff1cd78068cba474a22bed97fceba4a56a9d38ab0fbc178c4ab" , 1 ] ,
"id" : 1
}
Sample response
Copy {
"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
Transmit a transaction to the network.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "sendrawtransaction" ,
"params": ["80000001195876cb34364dc38b730077156c6bc3a7fc570044a66fbfeeea56f71327e8ab0000029b7cffdaa674beae0f930ebe6085af9093e5fe56b34a5c220ccdcf6efc336fc500c65eaf440000000f9a23e06f74cf86b8827a9108ec2e0f89ad956c9b7cffdaa674beae0f930ebe6085af9093e5fe56b34a5c220ccdcf6efc336fc50092e14b5e00000030aab52ad93f6ce17ca07fa88fc191828c58cb71014140915467ecd359684b2dc358024ca750609591aa731a0b309c7fb3cab5cd0836ad3992aa0a24da431f43b68883ea5651d548feb6bd3c8e16376e6e426f91f84c58232103322f35c7819267e721335948d385fae5be66e7ba8c748ac15467dcca0693692dac",0],
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"id" : 1 ,
"jsonrpc" : "2.0" ,
"result" : "498db60e96828581eff991c58fa46abbfd97d2f4a4f9915a11f85c54f2a2fedf"
}
The result
field contains the transaction hash.
getstorage
Fetched the stored value using contract hash and the storage key.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getstorage" ,
"params" : [ "03febccf81ac85e3d795bc5cbd4e84e907812aa3" , "5065746572" ] ,
"id" : 15
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"jsonrpc" : "2.0" ,
"id" : 15 ,
"result" : "4c696e"
}
The storage key is a hexadecimal string.
The result is also a serialized hex string. It can be deserialized using the SDK .
The contract address can be generated from the AVM code using SDK methods.
Python SDK
Copy 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
Copy 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
Copy 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
Fetch the version of the current node.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getversion" ,
"params" : [] ,
"id" : 3
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"jsonrpc" : "2.0" ,
"id" : 3 ,
"result" : "v0.9.2-1-g231e"
}
getcontractstate
Fetch contract details using contract address.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getcontractstate" ,
"params" : [ "0100000000000000000000000000000000000000" , 1 ] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"id" : 1 ,
"jsonrpc" : "2.0" ,
"result" : {
"Code" : "0000000000000000000000000000000000000001" ,
"NeedStorage" : true ,
"Name" : "ONT" ,
"CodeVersion" : "1.0" ,
"Author" : "Ontology Team" ,
"Email" : "contact@ont.io" ,
"Description" : "Ontology Network ONT Token"
}
}
getmempooltxcount
Fetch the no. of transactions in the node memory pool.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getmempooltxcount" ,
"params" : [] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"jsonrpc" : "2.0" ,
"id" : 1 ,
"result" : [ 100 , 50 ]
}
getmempooltxstate
Fetch state of transaction in the node memory pool using given transaction hash.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getmempooltxstate" ,
"params" : [ "773dd2dae4a9c9275290f89b56e67d7363ea4826dfd4fc13cc01cf73a44b0d0e" ] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"jsonrpc" : "2.0" ,
"id" : 1 ,
"result" : {
"State" : [{
"Type" : 1 ,
"Height" : 342 ,
"ErrCode" : 0
} , {
"Type" : 0 ,
"Height" : 0 ,
"ErrCode" : 0
}]
}
}
getsmartcodeevent
Fetch smart contract execution result using block height or transaction hash.
Sample request - using block height
Copy {
"jsonrpc" : "2.0" ,
"method" : "getsmartcodeevent" ,
"params" : [ 3 ] ,
"id" : 3
}
Sample response
Copy {
"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
Copy {
"jsonrpc" : "2.0" ,
"method" : "getsmartcodeevent" ,
"params" : [ "3ba4b4e463a717635614595378f2aac78feacc7d4dfda075bfcf9328cbbcdb7c" ] ,
"id" : 3
}
Sample response
Copy {
"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
The two fields within Notify
:
When the block height is passed as the parameter, the response contains the list of all the transactions that are the execution result.
When a transaction hash is passed as the parameter, the response contains the execution result of the particular transaction.
The States
field specified in the Notify
field is a hex string in for single transactions, and an array for multiple transactions.
getblockheightbytxhash
Fetch the block height for the block in which a particular transaction is recorded using transaction hash.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getblockheightbytxhash" ,
"params" : [ "c453557af780fe403db6e954ebc9adeafd5818c596c6c60e5cc42851c5b41884" ] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"id" : 1 ,
"jsonrpc" : "2.0" ,
"result" : 10
}
getbalance
Fetch the current balance of a Base58 address.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getbalance" ,
"params" : [ "TA5uYzLU2vBvvfCMxyV2sdzc9kPqJzGZWq" ] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"id" : 1 ,
"jsonrpc" : "2.0" ,
"result" :{
"ont" : "2500" ,
"ong" : "0"
}
}
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
Copy {
"jsonrpc" : "2.0" ,
"method" : "getbalancev2" ,
"params" : [ "TA5uYzLU2vBvvfCMxyV2sdzc9kPqJzGZWq" ] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"id" : 1 ,
"jsonrpc" : "2.0" ,
"result" :{
"ont" : "999999996000000000" ,
"ong" : "999999998000000000000000000" ,
"height" : "1455"
}
}
getmerkleproof
Fetches the merkle proof for a transaction using given transaction hash.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getmerkleproof" ,
"params" : [ "0087217323d87284d21c3539f216dd030bf9da480372456d1fa02eec74c3226d" ] ,
"id" : 1
}
Sample response
Copy {
"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
Fetch current gas price.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getgasprice" ,
"params" : [] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"id" : 1 ,
"jsonrpc" : "2.0" ,
"result" :{
"gasprice" : 0 ,
"height" : 1
}
}
getallowance
Fetch the amount of a given asset allocated as allowance to an address.
Sample request
Copy {
"jsonrpc" : "2.0" ,
"method" : "getallowance" ,
"params" : [ "ont" , "from address" , "to address" ] ,
"id" : 1
}
Sample response
Copy {
"desc" : "SUCCESS" ,
"error" : 0 ,
"id" : 1 ,
"jsonrpc" : "2.0" ,
"result" : "10"
}
getallowancev2
return the allowance from transfer-from accout to transfer-to account, ont decimals is 9,ong decimals is 18
Sample request
Copy {
"jsonrpc": "2.0",
"method": "getallowancev2",
"params": ["ont","from address","to address"],
"id": 1
}
Sample response
Copy {
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result": "100000000000"
}
getgrantong
Fetch the amount of granted ONG.
Sample request
Copy {
"jsonrpc": "2.0",
"method": "getgrantong",
"params": ["AKDFapcoUhewN9Kaj6XhHusurfHzUiZqUA"],
"id": 3
}
Sample response
Copy {
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 3,
"result": 4995625
}
getunboundong
Fetch the amount of unbound ONG that can be withdrawn for a particular address.
Sample request
Copy {
"jsonrpc": "2.0",
"method": "getunboundong",
"params": ["address"],
"id": 1
}
Sample response
Copy {
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result": "204957950400000"
}
getblocktxsbyheight
Fetches transaction hashes of all the transactions in the block at a given height.
Sample request
Copy {
"jsonrpc": "2.0",
"method": "getblocktxsbyheight",
"params": [100],
"id": 1
}
Sample response
Copy {
"desc":"SUCCESS",
"error":0,
"id":1,
"jsonrpc":"2.0",
"result": {
"Hash": "ea5e5219d2f1591f4feef89885c3f38c83d3a3474a5622cf8cd3de1b93849603",
"Height": 100,
"Transactions": [
"37e017cb9de93aa93ef817e82c555812a0a6d5c3f7d6c521c7808a5a77fc93c7"
]
}
}
getnetworkid
Fetch the network ID of the current network.
Sample request
Copy {
"jsonrpc": "2.0",
"method": "getnetworkid",
"params": [],
"id": 3
}
Sample response
Copy {
"desc":"SUCCESS",
"error":0,
"jsonrpc": "2.0",
"id": 3,
"result": 1
}
Error codes
The error codes in the response message signify the following: