Show / Hide Table of Contents
Last modified: 2024-10-25

API Reference

Each NEO-CLI node provides an API interface for obtaining blockchain data from it, making it easy to develop blockchain applications. The interface is provided via JSON-RPC , and the underlying protocol uses HTTP/HTTPS for communication.

To start a node that provides an RPC service, you must install the plugin RpcServer . Refer to Installing plugins for instructions. No need to add an argument when starting Neo-CLI.

If the desired version of file is not found during installation, it is because the corresponding version of RpcServer plug-in has not been released yet. In that case, you can compile the project neo-modules by yourself:

  1. Create the folder Plugins under the directory where neo-cli.dll locates.

  2. Put the RpcServer file you has complied in the Plugins folder and then restart Neo-CLI.

Listening ports

After the JSON-RPC server is started, it will listen to the TCP port. By default it is the port 10332 of the local address (127.0.0.1), which is

http://127.0.0.1:10332/

You can modify the port in config.json in the RpcServer folder.

Command Lists

Blockchain

MethodParameterDescription
getbestblockhash Gets the hash of the latest block in the blockchain.
getblock <hash | index> [verbose=0]Returns the block information with the specified hash value or index.
getblockcount Gets the block count of the blockchain.
getblockhash <index>Returns the block hash with the specified index.
getblockheader <hash | index> [verbose=0]Returns the information of the block header with the specified script hash or index.
getcommittee Gets the public key list of current Neo committee members.
getnativecontracts Gets the list of native contracts.
getnextblockvalidators Gets the validators list of the next block.
getcontractstate <script_hash>Returns information of the contract with the specified script hash.
getrawmempool [shouldGetUnverified=0]Gets a list of confirmed transactions in memory. If the value is 1 it gets all the transactions including both confirmed and unconfirmed transactions.
getrawtransaction <txid> [verbose=0]Returns the transaction information with the specified hash value.
getstorage <script_hash> <key>Returns the value with the contract script hash and the key.
gettransactionheight <txid>Returns the transaction height with the specified transaction hash.
findStorage <scripthash / contractid> <storage key prefix>Finds storage items by contract ID or script hash and prefix.

Node

MethodParameterDescription
getconnectioncount Gets the current connection count of the node.
getpeers Gets a list of nodes that are currently connected/disconnected by this node.
getversion Gets the version information of the node.
sendrawtransaction <hex>Broadcasts a transaction over the network.
submitblock <hex>Submits a new block to the network.
Note : Need to be a validator

Smart Contract

MethodParameterDescription
getunclaimedgas <address>Get unclaimed gas of the specified address.
invokefunction <script_hash> <operation> [params] [sender] [signers]Invokes a smart contract with the specified script hash, passing in the method name and its params.
invokescript <script> [sender] [signers]Runs a script through the virtual machine and returns the results.
traverseiterator <session> <iterator id> <count> Gets the Iterator type data.

Tool

MethodParameterDescription
listplugins Returns a list of plugins loaded by the node.
validateaddress <address>Verifies whether the address is a valid NEO address.

Wallet

MethodParameterDescription
calculatenetworkfee <tx>Calculates network fee for the specified transaction.
closewallet Closes the current wallet.
dumpprivkey <address>Exports the private key of the specified address.
getnewaddress Creates a new address.
getwalletbalance <asset_id>Returns the balance of the corresponding asset in the wallet.
getwalletunclaimedgas Gets the amount of unclaimed GAS in the wallet.
importprivkey <key>Imports the private key to the wallet.
invokecontractverify <script_hash> [params] [signers]Invokes the verification method of contract.
listaddress Lists all the addresses in the current wallet.
openwallet <path> <password>Opens the specified wallet.
sendfrom <asset_id><from><to><value>Transfers from the specified address to the destination address.
sendmany <outputs_array> [signers]Initiates multiple transfers to multiple addresses in a transaction.
sendtoaddress <asset_id><address><value> [signers]Transfers to the specified address.

ApplicationLogs plugin

MethodParameterDescription
getapplicationlog <txid>Returns the contract event information based on the specified txid.

TokensTracker plugin

MethodParameterDescription
getnep11balances <address>Returns the balance of all NEP11 assets in the specified address.
getnep11properties <contract_hash><tokenId>Returns the customized properties of NEP-11 assets.
getnep11transfers <address>[timestamp]Returns all the NEP11 transaction information occurred in the specified address.
getnep17balances <address>Returns the balance of all NEP17 assets in the specified address.
getnep17transfers <address>[timestamp]Returns all the NEP17 transaction information occurred in the specified address.

StateService plugin

MethodParameterDescription
getstateroot <index>Queries the state root by the block height.
getproof <roothash><scripthash><key>Gets proof by querying root hash, contract hash, and storage key.
verifyproof <roothash><proof>Verifies using the root hash and proof, and gets the value of the storage corresponding to the key.
getstateheight Queries the stateroot height.
getstate <roothash><scripthash><key>Queries state with the root hash , contract hash and storage key .
findstates <roothash><scripthash><prefix> [key] [count]Queries state with the prefix of root hash , contract hash and storage key .

For RPC API, all the return values related to the amount such as fees, NEP-17 asset balance, wallet balance, transfer amount, etc. are unsigned integer, which are automatically converted according to the asset decimal when requested by RpcClient (C# light node SDK). If you write the request by yourselves, you need to convert the amount manually. For example, if the return value is 1234560 and the asset decimal is 8, the actual amount is 0.0123456.

GET request example

The format of a typical JSON-RPC GET request is as follows:

Here is an example of how to get the number of blocks in the block chain.

Request URL:

http://127.0.0.1:10332?jsonrpc=2.0&method=getblockcount&params=[]&id=1

After sending the request, you will get the following response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 909129
}

POST request example

The format of a typical JSON-RPC Post request is as follows:

Here is an example of how to get the number of blocks in the block chain.

Request URL:

http://127.0.0.1:10332

Request Body:

{
  "jsonrpc": "2.0",
  "method": "getblockcount",
  "params":[],
  "id": 1
}

After sending the request, you will get the following response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 909122
}

To make sure you get the latest result synchronize your client to the latest block height before you use the API.

Use Postman and Import data

We recommend that you use Postman to use the API

image

After sign in or sign up a Posmtan account, you can directly import the Postman file we created https://docs.neo.org/RpcServer.postman_collection.json

Reference: Import data into Postman .

Exception

During RpcServer execution, when errors occur in request handling, contract execution, transaction validation, or other processes, exception codes and corresponding messages are thrown. These exceptions help developers quickly diagnose issues and take appropriate action. The exception codes and messages are as follows:

  • Error codes prefixed with -32xxx typically relate to the RPC protocol itself, such as parsing errors, invalid requests, or methods not found. See specification .

  • Error codes prefixed with -1xx generally involve unknown entities, such as unknown blocks, contracts, transactions, or state roots.

  • Error codes prefixed with -3xx pertain to wallet operations, mainly indicating issues like insufficient funds or incorrect wallet states.

  • Error codes prefixed with -5xx are related to transactions and memory pool operations, indicating issues like transaction validation failures, duplicate transactions, or insufficient network fees.

  • Error codes prefixed with -6xx are mostly associated with access control, state management, and Oracle services, indicating denied operations or disabled services.

The following table lists all error codes and corresponding messages. For more information, refer to Error Codes in NEP-23 .

codemessage
-32700Parse error
-32600Invalid Request
-32601Method not found
-32602Invalid params
-32603Internal error
-101Unknown block
-102Unknown contract
-103Unknown transaction
-104Unknown storage item
-105Unknown script container
-106Unknown state root
-107Unknown session
-108Unknown iterator
-109Unknown height
-300Insufficient funds in wallet
-301Wallet fee limit exceeded
-302No opened wallet
-303Wallet not found
-304Wallet not supported
-500Inventory verification failed
-501Inventory already exists
-502Memory pool capacity reached
-503Already in pool
-504Insufficient network fee
-505Policy check failed
-509Invalid transaction script
-507Invalid transaction attribute
-508Invalid signature
-509Invalid inventory size
-510Expired transaction
-511Insufficient funds for fee
-512Invalid contract verification function
-600Access denied
-601State iterator sessions disabled
-602Oracle service disabled
-603Oracle request already finished
-604Oracle request not found
-605Not a designated oracle node
-606Old state not supported
-607Invalid state proof
-608Contract execution failed