DISCOVERCOMMUNITYSUPPORT

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

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

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

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

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

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

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

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

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

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

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

{
    "Action": "getcontract",
    "Desc": "SUCCESS",
    "Error": 0,
    "Version": "1.0.0",
    "Result": {
        "Code": "0100000000000000000000000000000000000000",
        "NeedStorage": true,
        "Name": "ONT",
        "CodeVersion": "1.0",
        "Author": "Ontology Team",
        "Email": "contact@ont.io",
        "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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PreviousHTTP APINextWebSocket

Last updated