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.
note
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:
- Create the folder Plugins under the directory where neo-cli.dll locates.
- 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#
| Method | Parameter | Description |
|---|---|---|
| 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 | <script_hash / contract_id> \<storage key prefix> | Finds storage items by contract ID or script hash and prefix. |
Node#
| Method | Parameter | Description |
|---|---|---|
| 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.<br/>Note: Need to be a validator |
Smart Contract#
| Method | Parameter | Description |
|---|---|---|
| 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#
| Method | Parameter | Description |
|---|---|---|
| listplugins | Returns a list of plugins loaded by the node. | |
| validateaddress | <address> | Verifies whether the address is a valid NEO address. |
Wallet#
| Method | Parameter | Description |
|---|---|---|
| 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#
| Method | Parameter | Description |
|---|---|---|
| getapplicationlog | <txid> | Returns the contract event information based on the specified txid. |
TokensTracker plugin#
| Method | Parameter | Description |
|---|---|---|
| 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#
| Method | Parameter | Description |
|---|---|---|
| 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. |
note
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¶ms=[]&id=1After 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:10332Request 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}note
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
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
-32xxxtypically relate to the RPC protocol itself, such as parsing errors, invalid requests, or methods not found. See specification. - Error codes prefixed with
-1xxgenerally involve unknown entities, such as unknown blocks, contracts, transactions, or state roots. - Error codes prefixed with
-3xxpertain to wallet operations, mainly indicating issues like insufficient funds or incorrect wallet states. - Error codes prefixed with
-5xxare related to transactions and memory pool operations, indicating issues like transaction validation failures, duplicate transactions, or insufficient network fees. - Error codes prefixed with
-6xxare 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.
| code | message |
|---|---|
| -32700 | Parse error |
| -32600 | Invalid Request |
| -32601 | Method not found |
| -32602 | Invalid params |
| -32603 | Internal error |
| -101 | Unknown block |
| -102 | Unknown contract |
| -103 | Unknown transaction |
| -104 | Unknown storage item |
| -105 | Unknown script container |
| -106 | Unknown state root |
| -107 | Unknown session |
| -108 | Unknown iterator |
| -109 | Unknown height |
| -300 | Insufficient funds in wallet |
| -301 | Wallet fee limit exceeded |
| -302 | No opened wallet |
| -303 | Wallet not found |
| -304 | Wallet not supported |
| -500 | Inventory verification failed |
| -501 | Inventory already exists |
| -502 | Memory pool capacity reached |
| -503 | Already in pool |
| -504 | Insufficient network fee |
| -505 | Policy check failed |
| -509 | Invalid transaction script |
| -507 | Invalid transaction attribute |
| -508 | Invalid signature |
| -509 | Invalid inventory size |
| -510 | Expired transaction |
| -511 | Insufficient funds for fee |
| -512 | Invalid contract verification function |
| -600 | Access denied |
| -601 | State iterator sessions disabled |
| -602 | Oracle service disabled |
| -603 | Oracle request already finished |
| -604 | Oracle request not found |
| -605 | Not a designated oracle node |
| -606 | Old state not supported |
| -607 | Invalid state proof |
| -608 | Contract execution failed |