BSV blockchainBSV blockchain

SV Node RPC methods

SV Node exposes a JSON-RPC API for reading the chain, relaying transactions, mining and managing its wallet. The tables below list the methods that bitcoin-cli help shows in SV Node 1.2.3, grouped as the node groups them, with the first line of each method’s help text. Run bitcoin-cli help METHOD_NAME for the arguments and the result of one method, replacing METHOD_NAME with a method from the tables.

RPC gives full control of the node and its wallet. It can stop the node, dump private keys and spend funds. Keep the port on 127.0.0.1 or a private network and never publish it.

Call the API

Enable the server with server=1 and credentials in bitcoin.conf, as described in Configure SV Node. The default RPC port is 8332 on Mainnet and 18332 on testnet and regtest. Send a JSON-RPC POST with HTTP basic authentication. The example below runs against a node on testnet, and the same request works on regtest at the same port.

curl --user RPC_USERNAME:RPC_PASSWORD -H "content-type: application/json" -d '{"jsonrpc":"1.0","id":"1","method":"getblockcount","params":[]}' http://127.0.0.1:18332/

Replace RPC_USERNAME and RPC_PASSWORD with the rpcuser and rpcpassword values of your bitcoin.conf. On testnet the node answers {"result":2192,"error":null,"id":"1"}, where the result is the number of blocks it has synced so far, so yours differs while the node catches up. On a new regtest chain the result is 0. Wrong credentials return HTTP 401. bitcoin-cli takes the same method names and positional arguments, for example bitcoin-cli -testnet getblockcount.

getinfo still works in 1.2.3 but its help text marks it deprecated. Use getblockchaininfo, getnetworkinfo and getmininginfo instead.

Look up a method

The tables list 151 methods in 11 groups. Pick a group to jump to its table, which lists each signature with the first line of the node’s help text.

Blockchain

These methods read blocks, headers, the mempool and proofs, and verify or prune the chain:

MethodDescription
checkjournalChecks for consistency between the TX memory pool and the block assembly journal.
getbestblockhashReturns the hash of the best (tip) block in the longest blockchain.
getblock "blockhash" ( verbosity )Returns a block by hash. The verbosity sets raw hex, header fields or decoded transactions.
getblockbyheight height ( verbosity )Returns a block by height. The verbosity works as in getblock.
getblockchaininfoReturns an object containing various state info regarding blockchain processing.
getblockcountReturns the number of blocks in the longest blockchain.
getblockhash heightReturns hash of block in best-block-chain at height provided.
getblockheader "hash" ( verbosity )If verbosity is 0, false or RAW_HEADER, returns a string that is serialized, hex-encoded data for blockheader ‘hash’.
getblockstats blockhash ( stats )Compute per block statistics for a given window.
getblockstatsbyheight height ( stats )Compute per block statistics for a given window.
getchaintipsReturn information about all known tips in the block tree, including the main chain as well as orphaned branches.
getchaintxstats ( nblocks blockhash )Compute statistics about the total number and rate of transactions in the chain.
getdifficultyReturns the proof-of-work difficulty as a multiple of the minimum difficulty.
getmempoolancestors txid (verbose)Returns all in-mempool ancestors of a transaction that is in the mempool.
getmempooldescendants txid (verbose)Returns all in-mempool descendants of a transaction that is in the mempool.
getmempoolentry txidReturns mempool data for a given transaction.
getmempoolinfoReturns details on the active state of the TX memory pool.
getmerkleproof "txid" ( blockhash )Deprecated, use getmerkleproof2. Returns a Merkle proof for a transaction.
getmerkleproof2 "blockhash" "txid" ( includeFullTx targetType format )Returns a Merkle proof for a transaction by transaction ID, as a list of Merkle tree hashes.
getrawmempool ( verbose )Returns all transaction ids in memory pool as a json array of string transaction ids.
getrawnonfinalmempoolReturns all transaction ids in the non-final memory pool as a json array of string transaction ids.
gettxout "txid" n ( include_mempool )Returns details about an unspent transaction output.
gettxoutproof ["txid",...] ( blockhash )Returns a hex-encoded proof that a transaction was included in a block.
gettxouts txidVoutList returnFields ( include_mempool )Returns details about an unspent transaction output.
gettxoutsetinfoReturns statistics about the unspent transaction output set.
preciousblock "blockhash"Treats a block as if it were received before others with the same work.
pruneblockchainPrunes blocks up to a height or a Unix timestamp. Needs -prune.
rebuildjournalForces the block assembly journal and the TX mempool to be rebuilt to make them consistent with each other.
verifychain ( checklevel nblocks )Verifies blockchain database.
verifymerkleproof "proof"Verifies a given Merkle proof in JSON format and returns true if verification succeeded.
verifytxoutproof "proof"Verifies that a proof points to a transaction in a block, returning the transaction it commits to.

Network

These methods manage and inspect peers, bans and network traffic:

MethodDescription
addnode "node" "add|remove|onetry"Attempts to add or remove a node from the addnode list.
clearbannedClear all banned IPs.
disconnectnode "[address]" [nodeid]Immediately disconnects from the specified peer node.
getaddednodeinfo ( "node" )Returns information about the given added node, or all added nodes.
getauthconninfoReturns authconn data used by the node.
getconnectioncountReturns the number of connections to other nodes.
getexcessiveblockReturn the excessive block size.
getnettotalsReturns information about network traffic, including bytes in, bytes out and the current time.
getnetworkinfoReturns an object containing various state info regarding P2P networking.
getpeerinfoReturns data about each connected network node as a json array of objects.
listbannedList all banned IPs/Subnets.
pingRequests that a ping be sent to all other nodes, to measure ping time.
setban "subnet" "add|remove" (bantime) (absolute)Attempts to add or remove an IP or subnet from the banned list.
setblockmaxsize blockSizeSets maximum size of produced block.
setexcessiveblock blockSizeSet the excessive block size.
setnetworkactive true|falseDisable/enable all p2p network activity.
settxnpropagationfreq freqSet the frequency (in milli-seconds) the transaction propagator runs at.

Mining

These methods build block templates and candidates and submit solutions. getminingcandidate needs a connected peer: on a node with no connections it returns error -9, “Bitcoin is not connected!”:

MethodDescription
getblocktemplate ( TemplateRequest )Returns data to construct a block to work on, by the BIP 22 request format.
getminingcandidate coinbase (optional, default false)Returns Mining-Candidate protocol data.
getmininginfoReturns a json object containing mining-related information.
getnetworkhashps ( nblocks height )Returns the estimated network hashes per second based on the last n blocks.
prioritisetransaction <txid> <priority delta> <fee delta>Accepts the transaction into mined blocks at a higher or lower priority.
submitblock "hexdata" ( "jsonparametersobject" )Attempts to submit new block to network.
submitminingsolution "<json string>"Attempts to submit a new block to the network.
verifyblockcandidate "hexdata" ( "jsonparametersobject" )Tests a block template for validity without a valid PoW.

Raw transactions

These methods create, decode, fund, sign and send transactions you build yourself:

MethodDescription
createrawtransaction [{"txid":"id","vout":n},...] {"address":amount,"data":"hex",...} ( locktime )Creates a transaction spending the given inputs and creating new outputs.
decoderawtransaction "hexstring"Return a JSON object representing the serialized, hex-encoded transaction.
decodescript "hexstring"Decode a hex-encoded script.
fundrawtransaction "hexstring" ( options )Add inputs to a transaction until it has enough in value to meet its out value.
getrawtransaction "txid" ( verbose )By default this function only works for mempool transactions.
sendrawtransaction "hexstring" ( allowhighfees dontcheckfee )Submits raw transaction (serialized, hex-encoded) to local node and network.
sendrawtransactions [{"hex": "hexstring", "allowhighfees": true|false, "dontcheckfee": true|false, "listunconfirmedancestors": true|false, "config: " <json string> }, ...]Submits raw transactions (serialized, hex-encoded) to local node and network.
signrawtransaction "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] ["privatekey1",...] sighashtype )Sign inputs for raw transaction (serialized, hex-encoded).

Control

These methods report the node status and settings, and stop the node:

MethodDescription
activezmqnotificationsGets the active zmq notifications and their addresses.
dumpparametersDumps non-sensitive force set parameters and parameters set by switches and config file.
getinfoDeprecated.
getmemoryinfoReturns an object containing information about memory usage.
getsettingsReturns node policy and consensus settings that are used when constructing a block or transaction.
help ( "command" )List all commands, or get help for a specified command.
stopStop Bitcoin server.
uptimeReturns the total uptime of the server.

Utilities

These methods cover multisig addresses, message signing and script checks:

MethodDescription
clearinvalidtransactionsDeletes stored invalid transactions.
createmultisig nrequired ["key",...]Creates a multi-signature address with n signature of m keys required.
signmessagewithprivkey "privkey" "message"Signs a message with the private key of an address.
validateaddress "address"Return information about the given bitcoin address.
verifymessage "address" "signature" "message"Verifies a signed message.
verifyscript <scripts> [<stopOnFirstInvalid> [<totalTimeout>]]Verify a script in given transactions.

Wallet

These methods work on the wallet that the node loads. Several account methods are marked DEPRECATED in the node’s help text. walletlock, walletpassphrase and walletpassphrasechange show in help only when the loaded wallet is encrypted, and encryptwallet only when it is not. The tables list all 151: bitcoin-cli help shows 148 on an unencrypted wallet and 150 on an encrypted one.

MethodDescription
abandontransaction "txid"Marks an in-wallet transaction as abandoned.
addmultisigaddress nrequired ["key",...] ( "account" )Add a nrequired-to-sign multisignature address to the wallet.
backupwallet "destination"Safely copies current wallet file to destination, which can be a directory or a path with filename.
dumpprivkey "address"Reveals the private key corresponding to ‘address’.
dumpwallet "filename"Dumps all wallet keys in a human-readable format to a server-side file.
encryptwallet "passphrase"Encrypts the wallet with ‘passphrase’.
getaccount "address"DEPRECATED.
getaccountaddress "account"DEPRECATED.
getaddressesbyaccount "account"DEPRECATED.
getbalance ( "account" minconf include_watchonly )Returns the wallet balance. The account argument is deprecated.
getnewaddress ( "account" )Returns a new Bitcoin address for receiving payments.
getrawchangeaddressReturns a new Bitcoin address, for receiving change.
getreceivedbyaccount "account" ( minconf )DEPRECATED.
getreceivedbyaddress "address" ( minconf )Returns the total amount received by the given address in transactions with at least minconf confirmations.
gettransaction "txid" ( include_watchonly )Gets detailed information about an in-wallet transaction.
getunconfirmedbalanceReturns the server’s total unconfirmed balance.
getwalletinfoReturns an object containing various wallet state info.
importaddress "address" ( "label" rescan p2sh )Adds a script (in hex) or address that can be watched as if it were in your wallet but cannot be used to spend.
importmulti "requests" "options"Import addresses/scripts (with private or public keys, redeem script (P2SH)), rescanning all addresses in one-shot-only (rescan can be disabled via options).
importprivkey "bitcoinprivkey" ( "label" ) ( rescan )Adds a private key (as returned by dumpprivkey) to your wallet.
importprunedfundsImports funds without rescan.
importpubkey "pubkey" ( "label" rescan )Adds a public key (in hex) that can be watched as if it were in your wallet but cannot be used to spend.
importwallet "filename"Imports keys from a wallet dump file (see dumpwallet).
keypoolrefill ( newsize )Fills the keypool.
listaccounts ( minconf include_watchonly)DEPRECATED.
listaddressgroupingsLists groups of addresses that have had common ownership made public by common use as inputs or as the resulting change in past transactions.
listlockunspentReturns list of temporarily unspendable outputs.
listreceivedbyaccount ( minconf include_empty include_watchonly)DEPRECATED.
listreceivedbyaddress ( minconf include_empty include_watchonly)List balances by receiving address.
listsinceblock ( "blockhash" target_confirmations include_watchonly)Gets all transactions in blocks since block [blockhash], or all transactions if omitted.
listtransactions ( "account" count skip include_watchonly)Returns up to ‘count’ most recent transactions skipping the first ‘from’ transactions for account ‘account’.
listunspent ( minconf maxconf ["addresses",...] [include_unsafe] )Returns an array of unspent transaction outputs.
listwalletsReturns a list of currently loaded wallets.
lockunspent unlock ([{"txid":"txid","vout":n},...])Updates list of temporarily unspendable outputs.
move "fromaccount" "toaccount" amount ( minconf "comment" )DEPRECATED.
removeprunedfunds "txid"Deletes the specified transaction from the wallet.
rescanblockchain ("start_height") ("stop_height")Rescan the local blockchain for wallet related transactions.
sendfrom "fromaccount" "toaddress" amount ( minconf "comment" "comment_to" )DEPRECATED (use sendtoaddress).
sendmany "fromaccount" {"address":amount,...} ( minconf "comment" ["address",...] )Send multiple times.
sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount )Send an amount to a given address.
setaccount "address" "account"DEPRECATED.
settxfee amountSet the transaction fee per kB.
signmessage "address" "message"Signs a message with the private key of an address.
walletlockRemoves the wallet encryption key from memory, locking the wallet.
walletpassphrase "passphrase" timeoutStores the wallet decryption key in memory for ‘timeout’ seconds.
walletpassphrasechange "oldpassphrase" "newpassphrase"Changes the wallet passphrase from ‘oldpassphrase’ to ‘newpassphrase’.

Generating blocks

These methods mine blocks immediately, before the RPC call returns:

MethodDescription
generate nblocks ( maxtries )Mines up to nblocks blocks immediately (before the RPC call returns) to an address in the wallet.
generatetoaddress nblocks address (maxtries)Mines blocks immediately to a specified address (before the RPC call returns).

Miner ID

These methods work with miner IDs and miner info transactions:

MethodDescription
createdatareftx "[scriptPubKey,...]"Creates a transaction with dataref content.
createminerinfotx "scriptPubKey"Create a transaction with a miner info document and return its transaction ID.
datarefindexdumpReturns details for all currently stored dataRef transactions.
datareftxndelete "txid"Delete the specified dataRef transaction from the dataRef index.
dumpmineridsReturns details for all currently known miner IDs.
getdatareftxidReturns the datarefid for the current block being built.
getmineridinfo "minerId"Return miner ID information.
getminerinfotxfundingaddressGets the address that will fund the miner info transaction.
getminerinfotxidReturns the minerinfotx for the current block being built.
makeminerinfotxsigningkeyCreates a private BIP32 key and stores it in ./miner_id/Funding/.minerinfotxsigningkey.dat
rebuildminerids ( fullrebuild )Force a rebuild (in the background) of the miner ID database and synchronise it to the blockchain.
replaceminerinfotx "scriptPubKey"Creates or replaces a transaction with a miner info document and returns its transaction ID.
revokeminerid "input"Revoke minerId public key specified in the request and send out the P2P revokemid message to its peers.
setminerinfotxfundingoutpoint "txid" "n"Configures the node to use the miner-info funding outpoint.

Frozen transactions

These methods manage the confiscation and blacklist lists of frozen transaction outputs:

MethodDescription
addToConfiscationTxidWhitelist (txs)Add confiscation transactions to the whitelist.
addToConsensusBlacklist (funds)Adds or updates transaction outputs on consensus blacklist.
addToPolicyBlacklist (funds)Adds transaction outputs to policy-only blacklist.
clearBlacklists (removeAllEntries)Clears all blacklists and returns number of entries for frozen transaction outputs that were removed from database.
clearConfiscationWhitelistRemove all confiscation transactions from whitelist and move previously confiscated TXOs back to a consensus frozen state according to their consensus freeze intervals.
queryBlacklistReturns an array of currently frozen transaction outputs and blacklist membership.
queryConfiscationTxidWhitelist (verbose)Returns an array with ids of currently whitelisted confiscation transactions.
removeFromPolicyBlacklist (funds)Removes transaction outputs from policy blacklist.

Safe mode

These methods read the safe mode status and override it for a block:

MethodDescription
getsafemodeinfoReturns safe mode status.
ignoresafemodeforblock "blockhash"Specified block, and all its descendants, will be ignored for safe mode activation.
reconsidersafemodeforblock "blockhash"Specified block, and all its ancestors, will be considered for safe mode activation.

Methods not in the default list

These answer bitcoin-cli help METHOD_NAME in 1.2.3 but are not in the default list. Run that command for their arguments:

Method
getblockchainactivity
getcurrentlyvalidatingblocks
getorphaninfo
getsoftrejectedblocks onlymarked
getwaitingblocks
setmocktime timestamp

To learn more about running SV Node on the BSV blockchain, review these articles: