WebSocket

Websocket API Reference

By default, Websocket API listens on 20335 port.

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

ontology --ws

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

ontology --wsport 1024

Interface definition

Ontology's client side Websocket interface has been standardized as follows:

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

Id

int64

Request ID

Method list

The methods available as a part of the Websocket API to query the chain:

Method

Description

heartbeat

Send the heartbeat information

subscribe

Subscribe to a particular service

getconnectioncount

Fetch the number of nodes in the network

getblocktxsbyheight

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

getblockbyheight

Fetch the block details for a block at a given height

getblockbyhash

Fetch the block details using the block hash

getblockheight

Fetch the current block height of the blockchain

getblockhash

Fetch the block hash for a block at a given height

gettransaction

Fetch the transaction details using a given transaction hash

sendrawtransaction

Send a transaction to the Ontology network, if preExec=1, the transaction is pre-executed

getstorage

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

getbalance

Fetch the balance of the account using an address

getcontract

Fetch the contract status using the contract address hash

getsmartcodeeventbyheight

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

getsmartcodeeventbyhash

Fetch transaction execution result using a given transaction hash

getblockheightbytxhash

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

getmerkleproof

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

getsessioncount

Fetch current session count on the server side

getgasprice

Fetch the gas price

getallowance

Returns the allowance from the from account to the to account

getunboundong

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

getmempooltxstate

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

getmempooltxcount

Fetch the number of transactions stored in the memory

getversion

Fetch the version information

getnetworkid

Fetch the network id

getgrantong

Fetch the grant ong

heartbeat

Sends heartbeat information. If heartbeat information is not received by the client the sessin expires in 5 minutes.

Sample request

{
"Action": "heartbeat",
"Id":12345, //optional
"Version": "1.0.0"
}

Sample response

{
"Action": "heartbeat",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"SubscribeEvent":false,
"SubscribeJsonBlock":false,
"SubscribeRawBlock":false,
"SubscribeBlockTxHashs":false
}
"Version": "1.0.0"
}

subscribe

Used to subscribe to a particular service.

Sample request

{
"Action": "subscribe",
"Version": "1.0.0",
"Id":12345, //optional
"ConstractsFilter":["constractAddress"], //optional
"SubscribeEvent":false, //optional
"SubscribeJsonBlock":true, //optional
"SubscribeRawBlock":false, //optional
"SubscribeBlockTxHashs":false //optional
}

Sample response

{
"Action": "subscribe",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"ConstractsFilter":["contractAddress"],
"SubscribeEvent":false,
"SubscribeJsonBlock":true,
"SubscribeRawBlock":false,
"SubscribeBlockTxHashs":false
}
"Version": "1.0.0"
}

getconnectioncount

Fetches the number of connections to the node.

Sample request

{
"Action": "getconnectioncount",
"Id":12345, //optional
"Version": "1.0.0"
}

Sample response

{
"Action": "getconnectioncount",
"Desc": "SUCCESS",
"Error": 0,
"Result": 4,
"Version": "1.0.0"
}

getblocktxsbyheight

Fetch transaction hashes for a block at given height.

Sample request

{
"Action": "getblocktxsbyheight",
"Version": "1.0.0",
"Id":12345, //optional
"Height": 100
}

Sample response

{
"Action": "getblocktxsbyheight",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"Hash": "ea5e5219d2f1591f4feef89885c3f38c83d3a3474a5622cf8cd3de1b93849603",
"Height": 100,
"Transactions": [
"37e017cb9de93aa93ef817e82c555812a0a6d5c3f7d6c521c7808a5a77fc93c7"
]
},
"Version": "1.0.0"
}

getblockbyheight

Fetch block details for block at given height.

Sample request

{
"Action": "getblockbyheight",
"Version": "1.0.0",
"Id":12345, //optional
"Raw": "0",
"Height": 100
}

Sample response

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

getblockbyhash

Fetch block details for block using given block hash.

When the value of the raw field in the request is set to 1, the API returns serialized block information in the form of a hex string. For 0, it returns raw information in the form of a JSON string. The default value is 0.

Sample request

{
"Action": "getblockbyhash",
"Version": "1.0.0",
"Id":12345, //optional
"Raw": "0",
"Hash": "7c3e38afb62db28c7360af7ef3c1baa66aeec27d7d2f60cd22c13ca85b2fd4f3"
}

Sample response

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

getblockheight

Fetch the current block height.

Sample request

{
"Action": "getblockheight",
"Id":12345, //optional
"Version": "1.0.0"
}

Sample response

{
"Action": "getblockheight",
"Desc": "SUCCESS",
"Error": 0,
"Result": 327,
"Version": "1.0.0"
}

getblockhash

Fetch block hash for the block at given height.

Sample request

{
"Action": "getblockhash",
"Version": "1.0.0",
"Id":12345, //optional
"Height": 100
}

Sample response

{
"Action": "getblockhash",
"Desc": "SUCCESS",
"Error": 0,
"Result": "3b90ddc4d33c4954c3d87736120e94915f963546861987757f358c9376422255",
"Version": "1.0.0"
}

gettransaction

Fetch transaction details for a transaction using given hash.

When the value of the raw field in the request is set to 1, the API returns serialized transaction information in the form of a hex string. For 0, it returns raw information in the form of a JSON string. The default value is 0.

Sample request

{
"Action": "gettransaction",
"Version": "1.0.0",
"Id":12345, //optional
"Hash": "3b90ddc4d33c4954c3d87736120e94915f963546861987757f358c9376422255",
"Raw": "0"
}

Sample response

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

sendrawtransaction

Send a raw transaction to be recorded on the chain.

The PreExec field in the request object is used to specify whether the contract needs to be pre-run. If the contract is to be pre-run, set the value to 1, else 0.

Sample request

{
"Action":"sendrawtransaction",
"Version":"1.0.0",
"Id":12345, //optional
"PreExec": 0,
"Data":"80000001195876cb34364dc38b730077156c6bc3a7fc570044a66fbfeeea56f71327e8ab0000029b7cffdaa674beae0f930ebe6085af9093e5fe56b34a5c220ccdcf6efc336fc500c65eaf440000000f9a23e06f74cf86b8827a9108ec2e0f89ad956c9b7cffdaa674beae0f930ebe6085af9093e5fe56b34a5c220ccdcf6efc336fc50092e14b5e00000030aab52ad93f6ce17ca07fa88fc191828c58cb71014140915467ecd359684b2dc358024ca750609591aa731a0b309c7fb3cab5cd0836ad3992aa0a24da431f43b68883ea5651d548feb6bd3c8e16376e6e426f91f84c58232103322f35c7819267e721335948d385fae5be66e7ba8c748ac15467dcca0693692dac"
}

Sample response

{
"Action": "sendrawtransaction",
"Desc": "SUCCESS",
"Error": 0,
"Result": "22471ab3f4b4307a99f00c9a717dbf8b26f5bf63bf47f9c560477da8181de777",
"Version": "1.0.0"
}

The result obtained is the transaction hash of the raw transaction.

getstorage

Fetches the value stored in a contract using the contract hash and the storage key.

The contract hash passed to the method can be generated in the following manner:

addr := types.AddressFromVmCode([]byte{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x04})
fmt.Println(addr.ToHexString())

Sample request

{
"Action": "getstorage",
"Version": "1.0.0",
"Id":12345, //optional
"Hash": "0144587c1094f6929ed7362d6328cffff4fb4da2",
"Key" : "4587c1094f6"
}

Sample response

{
"Action": "getstorage",
"Desc": "SUCCESS",
"Error": 0,
"Result": "58d15e17628000",
"Version": "1.0.0"
}

The result in the response object and the key in the request are hex strings

getbalance

Fetches the balance of a Base58 address.

Sample request

{
"Action": "getbalance",
"Version": "1.0.0",
"Id":12345, //optional
"Addr": "TA63xZXqdPLtDeznWQ6Ns4UsbqprLrrLJk"
}

Sample response

{
"Action": "getbalance",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"ont": "2500",
"ong": "0"
},
"Version": "1.0.0"
}

getcontract

Fetches the contract details for the contract using given contract hash.

Sample request

{
"Action": "getcontract",
"Version": "1.0.0",
"Id":12345, //optional
"Hash": "0100000000000000000000000000000000000000"
}

Sample response

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

getsmartcodeeventbyheight

Fetches event details for a smart contract event that occurred at given block height and fetches the transaction list.

Sample request

{
"Action": "getsmartcodeeventbyheight",
"Version": "1.0.0",
"Id":12345, //optional
"Height": 100
}

Sample response

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

The result in the response object is a list that contains transaction hashes

getsmartcodeeventbyhash

Fetch contract event details using given transaction hash.

Sample request

{
"Action": "getsmartcodeeventbyhash",
"Version": "1.0.0",
"Id":12345, //optional
"Hash": "20046da68ef6a91f6959caa798a5ac7660cc80cf4098921bc63604d93208a8ac"
}

Sample response

{
"Action": "getsmartcodeeventbyhash",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": {
"TxHash": "20046da68ef6a91f6959caa798a5ac7660cc80cf4098921bc63604d93208a8ac",
"State": 1,
"GasConsumed": 0,
"Notify": [
{
"ContractAddress": "0100000000000000000000000000000000000000",
"States": [
"transfer",
"A9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
"AA4WVfUB1ipHL8s3PRSYgeV1HhAU3KcKTq",
1000000000
]
}
]
}
}

getblockheightbytxhash

Fetch block height using given transaction hash.

Sample request

{
"Action": "getblockheightbytxhash",
"Version": "1.0.0",
"Id":12345, //optional
"Hash": "3e23cf222a47739d4141255da617cd42925a12638ac19cadcc85501f907972c8"
}

Sample response

{
"Action": "getblockheightbytxhash",
"Desc": "SUCCESS",
"Error": 0,
"Result": 100,
"Version": "1.0.0"
}

getmerkleproof

Fetch merkle proof for given block hash.

Sample request

{
"Action": "getmerkleproof",
"Version": "1.0.0",
"Id":12345, //optional
"Hash": "0087217323d87284d21c3539f216dd030bf9da480372456d1fa02eec74c3226d"
}

Sample response

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

getsessioncount

Fetch session count.

Sample request

{
"Action": "getsessioncount",
"Id":12345, //optional
"Version": "1.0.0"
}

Sample response

{
"Action": "getsessioncount",
"Desc": "SUCCESS",
"Error": 0,
"Result": 10,
"Version": "1.0.0"
}

getgasprice

Fetch gas price.

Sample request

{
"Action": "getgasprice",
"Id": 12345, //optional
"Version": "1.0.0"
}

Sample response

{
"Action": "getgasprice",
"Desc": "SUCCESS",
"Error": 0,
"Result": {
"gasprice": 0,
"height": 1
},
"Version": "1.0.0"
}

getallowance

Fetch the amount of allowance of a certain asset granted by one address to another address.

Sample request

{
"Action": "getallowance",
"Id":12345, //optional
"Asset": "ont",
"From" : "A9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
"To" : "AA4WVfUB1ipHL8s3PRSYgeV1HhAU3KcKTq",
"Version": "1.0.0"
}

Sample response

{
"Action": "getallowance",
"Desc": "SUCCESS",
"Error": 0,
"Result": "10",
"Version": "1.0.0"
}

getunboundong

Fetch amount of unbound ONG for an address.

Sample request

{
"Action": "getunboundong",
"Id":12345, //optional
"Addr": "ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6",
"Version": "1.0.0"
}

Sample response

{
"Action": "getunboundong",
"Desc": "SUCCESS",
"Error": 0,
"Result": "204957950400000",
"Version": "1.0.0"
}

getmempooltxstate

Fetches state of transactions in the memory pool.

Sample request

{
"Action": "getmempooltxstate",
"Id":12345, //optional
"Hash": "0b437771a42d18d292741c5d4f1300a135fa6e65b0594e39dc299e7f8279221a",
"Version": "1.0.0"
}

Sample response

{
"Action": "getmempooltxstate",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": {
"State": [{
"Type": 1,
"Height": 342,
"ErrCode": 0
}, {
"Type": 0,
"Height": 0,
"ErrCode": 0
}]
}
}

getmempooltxcount

Fetch the transaction count in the memory pool.

Sample request

{
"Action": "getmempooltxcount",
"Id":12345, //optional
"Version": "1.0.0"
}

Sample response

{
"Action": "getmempooltxcount",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": [100,50]
}

getversion

Fetch version details for a node.

Sample request

{
"Action": "getversion",
"Id":12345, //optional
"Version": "1.0.0"
}

Sample response

{
"Action": "getversion",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": "0.9"
}

getnetworkid

Fetch the network ID.

Sample request

{
"Action": "getnetworkid",
"Id":12345, //optional
"Version": "1.0.0"
}

Sample response

{
"Action": "getnetworkid",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": 1
}

getgrantong

Fetch the granted ONG for an address.

Sample request

{
"Action": "getgrantong",
"Id":12345, //optional
"Addr":"AKDFapcoUhewN9Kaj6XhHusurfHzUiZqUA",
"Version": "1.0.0"
}

Sample response

{
"Action": "getgrantong",
"Desc": "SUCCESS",
"Error": 0,
"Version": "1.0.0",
"Result": 4995625
}

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