RPC Interface

The BSV SV Node JSON-RPC API allows developers to interact with the BSV blockchain through a set of remote procedure calls. This document outlines the available commands and their usage.

It’s important to keep your RPC interface secure, it allows direct control over how your node operates. Use firewalls and the rpcallowip setting to limit access to the RPC interface.

Overview

The JSON-RPC API provides a way to communicate with the BSV SV Node to perform various operations such as querying blockchain data, managing transactions, and retrieving network information.

JSON-RPC is a remote procedure call (RPC) protocol encoded in JSON. It allows for calling methods on a server from a client and receiving responses in a structured manner.

More information and example apps can be found in the SV Node RPC documentation.

Getting Started

To use the JSON-RPC API, you need to configure your BSV SV Node to accept JSON-RPC commands. This involves setting up the node with the appropriate RPC credentials and network settings.

Configuration

1. Enable RPC: Ensure that the bitcoin.conf file has the following settings:

   server=1
   rpcuser=yourusername
   rpcpassword=yourpassword
   rpcport=8332

2. Restart Node: Restart your BSV SV Node to apply the changes.

Making Requests

Requests to the JSON-RPC API are typically made via HTTP POST. Below is an example of how to structure a request:

POST / HTTP/1.1
Host: 127.0.0.1:8332
Authorization: Basic base64encoded(username:password)
Content-Type: application/json

{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "getinfo",
    "params": []
}

Examples

Here is an example of a curl command to get blockchain info:

curl --user yourusername:yourpassword --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockchaininfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/

{
    "result": {
        "chain": "main",
        "blocks": 680000,
        "headers": 680000,
        ...
    },
    "error": null,
    "id": "curltest"
}

You can also use the installed bitcoin-cli to run these commands from the node's command line

~/bitcoin/bin/bitcoin-cli -rpcclienttimeout=30 -datadir="/home/ubuntu/bitcoin-data" getinfo

{
  "version": 101010000,
  "protocolversion": 70016,
  ...
}

Available Methods

The full list of available commands can be generated with the help command

~/bitcoin/bin/bitcoin-cli -datadir="/home/ubuntu/bitcoin-data" help

== Blockchain ==
checkjournal
getbestblockhash
getblock "blockhash" ( verbosity )
...

And you can get more information about a specific method using the help <command> call.

~/bitcoin/bin/bitcoin-cli -datadir="/home/ubuntu/bitcoin-data" help submitminingsolution

submitminingsolution "<json string>"

Attempts to submit a new block to the network.

Json Object should comprise of the following and must be escaped
    {
        "id": n,         (string) ID from getminingcandidate RPC
        "nonce": n,      (integer) Miner generated nonce
        "coinbase": "",  (hex string, optional) Modified Coinbase transaction
        "time": n,       (integer, optional) Block time
        "version": n     (integer, optional) Block version
    }

Result:

Nothing on success, error string if block was rejected.
Identical to "submitblock".

A full list of methods is also available in RPC Methods. The most commonly used methods are:

General Commands

• getinfo: Returns an object containing various state info.

• help: Lists all commands, or provides help for a specified command.

Blockchain Queries

• getblockchaininfo: Provides information about the current state of the blockchain.

• getblockhash: Returns the hash of the block at a specified height.

• getblock: Returns the block details for a specified hash.

Transaction Management

• getrawtransaction: Returns raw transaction data for a given transaction ID.

• sendrawtransaction: Submits a raw transaction to the network.

Mining Commands

• getmininginfo: Provides information about the current state of mining, including network hash rate, difficulty, and mining configuration.

• getminingcandidate: Retrieves a candidate block for mining, including transactions and other necessary information to start mining.

• submitminingsolution: Submits a solution for a mined block to the network, attempting to add it to the blockchain.

Error Handling

Errors in the JSON-RPC API are returned with an error object. This object contains a code and a message indicating the nature of the error.

Common Error Codes

• -32600: Invalid Request

• -32601: Method Not Found

• -32602: Invalid Params

• -32603: Internal Error

• -32700: Parse Error