Restful

Restful API Reference

By default, Restful API listens on 20334 port.

After a local node has been installed, Restful can be started on the client end using the following command:

ontology --rest

The following option can be used to change the port at which the Restful API listens:

ontology --rest --restport 1024

Interface definition

Response parameters

The structure of the response message after a request is sent is as follows:

Field

Data type

Description

Action

String

Response action name

Desc

String

Response result description

Error

Integer

Error code

Result

Object

Execution result

Version

String

Version number

Method list

The methods that the client side Restful interface supports are illustrated below.

Method

Description

get_conn_count

Fetch the current number of nodes in the network

get_blk_txs_by_height

Fetch all the transaction hashes for a block at a given height

get_blk_by_height

Fetch the block details for a block at a given height

get_blk_by_hash

Fetch the block details using the block hash

get_blk_height

Fetch the current block height of the blockchain

get_blk_hash

Fetch the block hash for a block at a given height

get_tx

Fetch the transaction details using a given transaction hash

get_storage

Fetch the corresponding value using the contract address hash or the key

get_balance

Fetch the balance of the account using an address

get_contract_state

Fetch the contract status using the contract address hash

get_sc_event_by_height

Fetch the contract execution result for a particular block using the block height

get_smtcode_evts

Fetch transaction execution result using a given transaction hash

get_blk_hgt_by_txhash

Fetch the block height at which a transaction was carried out using a given transaction hash

get_merkle_proof

Fetch the merkle proof for a transaction using a given transaction hash

get_gasprice

Fetch the GAS price

get_allowance

Returns the allowance from the from account to the to account

get_unboundong

Returns the unclaimed ONG for a particular account using a given account address

get_mempooltxcount

Fetch the number of transactions stored in the memory

get_mempooltxstate

Fetch the transaction status for a given transaction using the transaction hash

get_version

Fetch the version information

post_raw_tx

Send a transaction to the Ontology network

get_networkid

Fetch network id

get_grantong

Fetch the grant ONG

get
get_conn_count

http://server:port/api/v1/node/connectioncount
Fetch the current no. of nodes in the network
Request
Response
Request
Response
200: OK
Result field contains the no. of nodes
{
"Action": "getconnectioncount",
"Desc": "SUCCESS",
"Error": 0,
"Result": 0,
"Version": "1.0.0"
}

get
get_blk_txs_by_height

http://server:port/api/v1/block/transactions/height/{height}
Fetch all transaction hashes for a block at a given height
Request
Response
Request
Path Parameters
height
required
integer
Block height
Response
200: OK
{
"Action": "getblocktxsbyheight",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"Hash": "ea5e5219d2f1591f4feef89885c3f38c83d3a3474a5622cf8cd3de1b93849603",
"Height": 100,
"Transactions": [
"37e017cb9de93aa93ef817e82c555812a0a6d5c3f7d6c521c7808a5a77fc93c7"
]
},
"Version": "1.0.0"
}

get
get_blk_by_height

http://server:port/api/v1/block/details/height/{height}
Fetches block details using block height
Request
Response
Request
Path Parameters
height
required
integer
Block height
Query Parameters
raw
optional
integer
0 returns raw data, 1 returns serialized data. 0 by default
Response
200: OK
{
"Action": "getblockbyheight",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"Hash": "ea5e5219d2f1591f4feef89885c3f38c83d3a3474a5622cf8cd3de1b93849603",
"Header": {
"Version": 0,
"PrevBlockHash": "fc3066adb581c5aee8edaa47eecda2b7cc039c8662757f8b1e3c3aed60314353",
"TransactionsRoot": "37e017cb9de93aa93ef817e82c555812a0a6d5c3f7d6c521c7808a5a77fc93c7",
"BlockRoot": "7154a6dcb3c23254334bc1f5d8f054c143a39ff28f46fdeb8a9c7488147ccec6",
"Timestamp": 1522313652,
"Height": 100,
"ConsensusData": 18012644264110396442,
"NextBookkeeper": "TABrSU6ABhj6Rdw5KozV53wvZNSUATgKHW",
"Bookkeepers": [
"120203fe4f9ba2022b68595dd163f4a92ac80f918919674de2d6e2a7e04a10c59d0066"
],
"SigData": [
"01a2369280b0ff75bed85f351d3ef0dd58add118328c1ed2f7d3320df32cb4bd55541f1bb8e11ad093bd24da3de4cd12464800310bfdb49dc62d42d97ca0549762"
],
"Hash": "ea5e5219d2f1591f4feef89885c3f38c83d3a3474a5622cf8cd3de1b93849603"
},
"Transactions": [
{
"Version": 0,
"Nonce": 0,
"TxType": 0,
"Payload": {
"Nonce": 1522313652068190000
},
"Attributes": [],
"Fee": [],
"NetworkFee": 0,
"Sigs": [
{
"PubKeys": [
"120203fe4f9ba2022b68595dd163f4a92ac80f918919674de2d6e2a7e04a10c59d0066"
],
"M": 1,
"SigData": [
"017d3641607c894dd85f455c71a94afaea2661acbe372ff8f3f4c7921b0c768756e3a6e9308a4c4c8b1b58e717f1486a2f10f5bc809b803a27c10a2cd579778a54"
]
}
],
"Hash": "37e017cb9de93aa93ef817e82c555812a0a6d5c3f7d6c521c7808a5a77fc93c7"
}
]
},
"Version": "1.0.0"
}

get
get_blk_by_hash

http://server:port/api/v1/block/details/hash/{hash}
Fetch block details by block hash
Request
Response
Request
Path Parameters
hash
required
string
Block hash
Query Parameters
raw
optional
integer
0 returns raw data, 1 returns serialized data. 0 by default
Response
200: OK
{
"Action": "getblockbyhash",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"Hash": "ea5e5219d2f1591f4feef89885c3f38c83d3a3474a5622cf8cd3de1b93849603",
"Header": {
"Version": 0,
"PrevBlockHash": "fc3066adb581c5aee8edaa47eecda2b7cc039c8662757f8b1e3c3aed60314353",
"TransactionsRoot": "37e017cb9de93aa93ef817e82c555812a0a6d5c3f7d6c521c7808a5a77fc93c7",
"BlockRoot": "7154a6dcb3c23254334bc1f5d8f054c143a39ff28f46fdeb8a9c7488147ccec6",
"Timestamp": 1522313652,
"Height": 100,
"ConsensusData": 18012644264110396442,
"NextBookkeeper": "TABrSU6ABhj6Rdw5KozV53wvZNSUATgKHW",
"Bookkeepers": [
"120203fe4f9ba2022b68595dd163f4a92ac80f918919674de2d6e2a7e04a10c59d0066"
],
"SigData": [
"01a2369280b0ff75bed85f351d3ef0dd58add118328c1ed2f7d3320df32cb4bd55541f1bb8e11ad093bd24da3de4cd12464800310bfdb49dc62d42d97ca0549762"
],
"Hash": "ea5e5219d2f1591f4feef89885c3f38c83d3a3474a5622cf8cd3de1b93849603"
},
"Transactions": [
{
"Version": 0,
"Nonce": 0,
"TxType": 0,
"Payload": {
"Nonce": 1522313652068190000
},
"Attributes": [],
"Fee": [],
"NetworkFee": 0,
"Sigs": [
{
"PubKeys": [
"120203fe4f9ba2022b68595dd163f4a92ac80f918919674de2d6e2a7e04a10c59d0066"
],
"M": 1,
"SigData": [
"017d3641607c894dd85f455c71a94afaea2661acbe372ff8f3f4c7921b0c768756e3a6e9308a4c4c8b1b58e717f1486a2f10f5bc809b803a27c10a2cd579778a54"
]
}
],
"Hash": "37e017cb9de93aa93ef817e82c555812a0a6d5c3f7d6c521c7808a5a77fc93c7"
}
]
},
"Version": "1.0.0"
}

get
get_blk_height

http://server:port/api/v1/block/height
Fetch the current block height
Request
Response
Request
Response
200: OK
{
"Action": "getblockheight",
"Desc": "SUCCESS",
"Error": 0,
"Result": 327,
"Version": "1.0.0"
}

get
get_blk_hash

http://server:port/api/v1/block/hash/{height}
Fetch block hash for block at a given height
Request
Response
Request
Path Parameters
height
required
integer
Block height
Response
200: OK
{
"Action": "getblockhash",
"Desc": "SUCCESS",
"Error": 0,
"Result": "3b90ddc4d33c4954c3d87736120e94915f963546861987757f358c9376422255",
"Version": "1.0.0"
}

get
get_tx

http://server:port/api/v1/transaction/{hash}
Fetch transaction details using transaction hash
Request
Response
Request
Path Parameters
hash
required
string
Transaction hash
Query Parameters
raw
optional
integer
0 returns raw data, 1 returns serialized data. 0 by default
Response
200: OK
{
"Action": "gettransaction",
"Desc": "SUCCESS",
"Error": 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
},
"Version": "1.0.0"
}

get
get_storage

http://server:port/api/v1/storage/{hash}/{key}
Fetch value using contract address hash and key
Request
Response
Request
Path Parameters
hash
required
string
Contract hash
key
required
string
Resource key
Response
200: OK
{
"Action": "getstorage",
"Desc": "SUCCESS",
"Error": 0,
"Result": "58d15e17628000",
"Version": "1.0.0"
}

get
get_balance

http://server:port/api/v1/balance/{addr}
Fetches balance of a Base58 address
Request
Response
Request
Path Parameters
addr
required
string
Base58 encoded account address
Response
200: OK
{
"Action": "getbalance",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"ont": "2500",
"ong": "0"
},
"Version": "1.0.0"
}

get
get_contract_state

http://server:port/api/v1/contract/{hash}
Fetches contract details using contract hash
Request
Response
Request
Path Parameters
hash
required
string
Contract hash
Response
200: OK
{
"Action": "getcontract",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": {
"Code": "0100000000000000000000000000000000000000",
"NeedStorage": true,
"Name": "ONT",
"CodeVersion": "1.0",
"Author": "Ontology Team",
"Email": "[email protected]",
"Description": "Ontology Network ONT Token"
}
}

get
get_sc_event_by_height

http://server:port/api/v1/smartcode/event/transactions/{height}
Fetch contract execution result using block height
Request
Response
Request
Path Parameters
height
required
integer
Block height
Response
200: OK
{
"Action": "getsmartcodeeventbyheight",
"Desc": "SUCCESS",
"Error": 0,
"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
]
}
]
}
],
"Version": "1.0.0"
}

get
get_smtcode_evts

http://server:port/api/v1/smartcode/event/txhash/{hash}
Fetches contract events using transaction hash
Request
Response
Request
Path Parameters
hash
required
string
Transaction hash
Response
200: OK
Response
OEP-4 Transfer Event Example
Response
{
"Action": "getsmartcodeeventbyhash",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": {
"TxHash": "20046da68ef6a91f6959caa798a5ac7660cc80cf4098921bc63604d93208a8ac",
"State": 1,
"GasConsumed": 0,
"Notify": [
{
"ContractAddress": "0100000000000000000000000000000000000000",
"States": [
"transfer",
"T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
"TA4WVfUB1ipHL8s3PRSYgeV1HhAU3KcKTq",
1000000000
]
}
]
}
}
OEP-4 Transfer Event Example
{
TxHash: "a948ab394c6fd6296b93755b42fd4133a6ec82951a8931490a2c544a6eeaa21c",
State: 1,
GasConsumed: 10000000,
Notify: [{
ContractAddress: "a0fcb515a1d42b4aaf9734aabf40411fa93f6849", //oep4
States: [
"7472616e73666572", //transfer
"f54855d4e025d8f5b9f0ac1b2ae3c8171bb7fc17", //from
"b264bd0a306fd3b815601a1ba968f8bd7b17c515", //to
"666c9802" //amount
]
},
{
ContractAddress: "0200000000000000000000000000000000000000", //pay network fee by ong
States: [
"transfer",
"Ae8orSUnAtH9yRiepRvLUE3t9R2NbCTZPG",
"AFmseVrdL9f9oyCzZefL9tG6UbviEH9ugK",
10000000
]
}
]
}

get
get_blk_hgt_by_txhash

http://server:port/api/v1/block/height/txhash/{hash}
Fetch block height using transaction hash
Request
Response
Request
Path Parameters
hash
required
string
Transaction hash
Response
200: OK
{
"Action": "getblockheightbytxhash",
"Desc": "SUCCESS",
"Error": 0,
"Result": 0,
"Version": "1.0.0"
}

get
get_merkle_proof

http://server:port/api/v1/merkleproof/{hash}
Fetch merkle proof using transaction hash
Request
Response
Request
Path Parameters
hash
required
string
Transaction hash
Response
200: OK
{
"Action": "getmerkleproof",
"Desc": "SUCCESS",
"Error": 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"
]
},
"Version": "1.0.0"
}

get
get_gasprice

http://server:port/api/v1/block/height/txhash/{hash}
Fetch gas price
Request
Response
Request
Path Parameters
hash
optional
string
Transaction hash
Response
200: OK
{
"Action": "getgasprice",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"gasprice": 0,
"height": 1
},
"Version": "1.0.0"
}

get
get_allowance

http://server:port/api/v1/allowance/{asset}/{from}/{to}
Fetches amount of allowance of an asset from one account to another
Request
Response
Request
Path Parameters
asset
required
string
Asset contract hash
from
required
string
Source account address
to
required
string
Recipient account address
Response
200: OK
{
"Action": "getallowance",
"Desc": "SUCCESS",
"Error": 0,
"Result": "10",
"Version": "1.0.0"
}

get
get_unboundong

http://server:port/api/v1/unboundong/{addr}
Fetch unbound ONG for an account
Request
Response
Request
Path Parameters
addr
required
string
Account address
Response
200: OK
{
"Action": "getunboundong",
"Desc": "SUCCESS",
"Error": 0,
"Result": "204957950400000",
"Version": "1.0.0"
}

get
get_mempooltxcount

http://server:port/api/v1/mempool/txcount
Fetch current transaction count in the memory pool
Request
Response
Request
Response
200: OK
{
"Action": "getmempooltxcount",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": [100,50]
}

get
get_mempooltxstate

http://server:port/api/v1/mempool/txstate/{hash}
Fetch transaction state in the memory pool
Request
Response
Request
Path Parameters
hash
required
string
Transaction hash
Response
200: OK
{
"Action": "getmempooltxstate",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": {
"State": [{
"Type": 1,
"Height": 342,
"ErrCode": 0
}, {
"Type": 0,
"Height": 0,
"ErrCode": 0
}]
}
}

get
get_version

http://server:port/api/v1/version
Fetch node version information
Request
Response
Request
Response
200: OK
{
"Action": "getversion",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": "0.9"
}

get
get_networkid

http://server:port/api/v1/networkid
Fetches network ID
Request
Response
Request
Response
200: OK
{
"Action": "getnetworkid",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": 1
}

get
get_grantong

http://server:port/api/v1/grantong/{addr}
Fetch amount of ONG granted to an account
Request
Response
Request
Path Parameters
addr
required
string
Account address
Response
200: OK
{
"Action": "getgrantong",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": 4995625
}

post
post_raw_tx

http://server:port/api/v1/transaction
Send a raw transaction
Request
Response
Request
Headers
Content-Type
optional
string
Set to "application/json"
Query Parameters
preExec
optional
integer
Set 0 if contract needs to be pre-executed, else 1
Body Parameters
Action
required
string
Specifies action, set to "sendrawtransaction"
Version
required
string
Set to "1.0.0"
Data
required
string
Data hex code
Response
200: OK
Returns transaction hash
{
"Action": "sendrawtransaction",
"Desc": "SUCCESS",
"Error": 0,
"Result": "22471ab3f4b4307a99f00c9a717dbf8b26f5bf63bf47f9c560477da8181de777",
"Version": "1.0.0"
}

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