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_balancev2	Fetch the balance of the account using an address, with ONT's decimals being 9, and ONG's decimals being 18
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	Return the allowance from the from account to the to account
get_allowancev2	Return the allowance from the from account to the to account, with ONT's decimals being 9, and ONG's decimals being 18
get_unboundong	Return 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_syncstatus	Fetch the synchronization status of the node

get_conn_count

GET http://server:port/api/v1/node/connectioncount

Fetch the current no. of nodes in the network

200 Result field contains the no. of nodes

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

get_blk_txs_by_height

GET http://server:port/api/v1/block/transactions/height/{height}

Fetch all transaction hashes for a block at a given height

Path Parameters

Name	Type	Description
height	integer	Block height

200

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

get_blk_by_height

GET http://server:port/api/v1/block/details/height/{height}

Fetches block details using block height

Path Parameters

Name	Type	Description
height	integer	Block height

Query Parameters

Name	Type	Description
raw	integer	0 returns raw data, 1 returns serialized data. 0 by default

200

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

GET http://server:port/api/v1/block/details/hash/{hash}

Fetch block details by block hash

Path Parameters

Name	Type	Description
hash	string	Block hash

Query Parameters

Name	Type	Description
raw	integer	0 returns raw data, 1 returns serialized data. 0 by default

200

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

GET http://server:port/api/v1/block/height

Fetch the current block height

200

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

get_blk_hash

GET http://server:port/api/v1/block/hash/{height}

Fetch block hash for block at a given height

Path Parameters

Name	Type	Description
height	integer	Block height

200

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

get_tx

GET http://server:port/api/v1/transaction/{hash}

Fetch transaction details using transaction hash

Path Parameters

Name	Type	Description
hash	string	Transaction hash

Query Parameters

Name	Type	Description
raw	integer	0 returns raw data, 1 returns serialized data. 0 by default

200

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

GET http://server:port/api/v1/storage/{hash}/{key}

Fetch value using contract address hash and key

Path Parameters

Name	Type	Description
hash	string	Contract hash
key	string	Resource key

200

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

get_balance

GET http://server:port/api/v1/balance/{addr}

Fetches balance of a Base58 address

Path Parameters

Name	Type	Description
addr	string	Base58 encoded account address

200

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

get_balancev2

GET http://server:port/api/v1/balancev2/{addr}

Fetch the balance of the account using an address, with ONT decimals being 9, and ONG decimals being 18

Path Parameters

Name	Type	Description
addr*	String	Base58 encoded account address

200: OK

{
    "Action": "getbalancev2",
    "Desc": "SUCCESS",
    "Error": 0,
    "Result": {
        "ont": "999999996000000000",
        "ong": "999999998000000000000000000",
        "height":"1455"
    },
    "Version": "1.0.0"
}

get_contract_state

GET http://server:port/api/v1/contract/{hash}

Fetches contract details using contract hash

Path Parameters

Name	Type	Description
hash	string	Contract hash

200

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

GET http://server:port/api/v1/smartcode/event/transactions/{height}

Fetch contract execution result using block height

Path Parameters

Name	Type	Description
height	integer	Block height

200

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

GET http://server:port/api/v1/smartcode/event/txhash/{hash}

Fetches contract events using transaction hash

Path Parameters

Name	Type	Description
hash	string	Transaction hash

200

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

get_blk_hgt_by_txhash

GET http://server:port/api/v1/block/height/txhash/{hash}

Fetch block height using transaction hash

Path Parameters

Name	Type	Description
hash	string	Transaction hash

200

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

get_merkle_proof

GET http://server:port/api/v1/merkleproof/{hash}

Fetch merkle proof using transaction hash

Path Parameters

Name	Type	Description
hash	string	Transaction hash

200

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

GET http://localhost:20334/api/v1/gasprice

Fetch gas price

Path Parameters

Name	Type	Description
hash	string	Transaction hash

200

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

get_allowance

GET http://server:port/api/v1/allowance/{asset}/{from}/{to}

Fetches amount of allowance of an asset from one account to another

Path Parameters

Name	Type	Description
asset	string	Asset contract hash
from	string	Source account address
to	string	Recipient account address

200

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

get_allowancev2

GET http://server:port/api/v1/allowancev2

Return the allowance from the from account to the to account, with ONT decimals being 9, and ONG decimals being 18

Path Parameters

Name	Type	Description
asset	String	Asset contract hash
from	String	Source account address
to	String	Recipient account address

200: OK

{
    "Action": "getallowancev2",
    "Desc": "SUCCESS",
    "Error": 0,
    "Result": "10000000000",
    "Version": "1.0.0"
}

get_unboundong

GET http://server:port/api/v1/unboundong/{addr}

Fetch unbound ONG for an account

Path Parameters

Name	Type	Description
addr	string	Account address

200

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

get_mempooltxcount

GET http://server:port/api/v1/mempool/txcount

Fetch current transaction count in the memory pool

200

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

get_mempooltxstate

GET http://server:port/api/v1/mempool/txstate/{hash}

Fetch transaction state in the memory pool

Path Parameters

Name	Type	Description
hash	string	Transaction hash

200

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

GET http://server:port/api/v1/version

Fetch node version information

200

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

get_networkid

GET http://server:port/api/v1/networkid

Fetches network ID

200

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

get_grantong

GET http://server:port/api/v1/grantong/{addr}

Fetch amount of ONG granted to an account

Path Parameters

Name	Type	Description
addr	string	Account address

200

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

get_syncstatus

GET http://server:port/api/v1/api/v1/node/syncstatus

Fetch the synchronization status of the node

Path Parameters

Name	Type	Description
	String

200: OK

{
    "Action":"getsyncstatus",
    "Desc":"SUCCESS",
    "Error":0,
    "Result":{
        "CurrentBlockHeight":16224658,
        "ConnectCount":18,
        "MaxPeerBlockHeight":16224658
    },
    "Version":"1.0.0"
}

post_raw_tx

POST http://server:port/api/v1/transaction

Send a raw transaction

Query Parameters

Name	Type	Description
preExec	integer	Set 0 if contract needs to be pre-executed, else 1

Headers

Name	Type	Description
Content-Type	string	Set to "application/json"

Request Body

Name	Type	Description
Action	string	Specifies action, set to "sendrawtransaction"
Version	string	Set to "1.0.0"
Data	string	Data hex code

200 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