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:
| Method | Description |
|---|---|
checkjournal | Checks for consistency between the TX memory pool and the block assembly journal. |
getbestblockhash | Returns 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. |
getblockchaininfo | Returns an object containing various state info regarding blockchain processing. |
getblockcount | Returns the number of blocks in the longest blockchain. |
getblockhash height | Returns 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. |
getchaintips | Return 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. |
getdifficulty | Returns 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 txid | Returns mempool data for a given transaction. |
getmempoolinfo | Returns 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. |
getrawnonfinalmempool | Returns 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. |
gettxoutsetinfo | Returns statistics about the unspent transaction output set. |
preciousblock "blockhash" | Treats a block as if it were received before others with the same work. |
pruneblockchain | Prunes blocks up to a height or a Unix timestamp. Needs -prune. |
rebuildjournal | Forces 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:
| Method | Description |
|---|---|
addnode "node" "add|remove|onetry" | Attempts to add or remove a node from the addnode list. |
clearbanned | Clear 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. |
getauthconninfo | Returns authconn data used by the node. |
getconnectioncount | Returns the number of connections to other nodes. |
getexcessiveblock | Return the excessive block size. |
getnettotals | Returns information about network traffic, including bytes in, bytes out and the current time. |
getnetworkinfo | Returns an object containing various state info regarding P2P networking. |
getpeerinfo | Returns data about each connected network node as a json array of objects. |
listbanned | List all banned IPs/Subnets. |
ping | Requests 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 blockSize | Sets maximum size of produced block. |
setexcessiveblock blockSize | Set the excessive block size. |
setnetworkactive true|false | Disable/enable all p2p network activity. |
settxnpropagationfreq freq | Set 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!”:
| Method | Description |
|---|---|
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. |
getmininginfo | Returns 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:
| Method | Description |
|---|---|
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:
| Method | Description |
|---|---|
activezmqnotifications | Gets the active zmq notifications and their addresses. |
dumpparameters | Dumps non-sensitive force set parameters and parameters set by switches and config file. |
getinfo | Deprecated. |
getmemoryinfo | Returns an object containing information about memory usage. |
getsettings | Returns 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. |
stop | Stop Bitcoin server. |
uptime | Returns the total uptime of the server. |
Utilities
These methods cover multisig addresses, message signing and script checks:
| Method | Description |
|---|---|
clearinvalidtransactions | Deletes 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.
| Method | Description |
|---|---|
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. |
getrawchangeaddress | Returns 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. |
getunconfirmedbalance | Returns the server’s total unconfirmed balance. |
getwalletinfo | Returns 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. |
importprunedfunds | Imports 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. |
listaddressgroupings | Lists groups of addresses that have had common ownership made public by common use as inputs or as the resulting change in past transactions. |
listlockunspent | Returns 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. |
listwallets | Returns 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 amount | Set the transaction fee per kB. |
signmessage "address" "message" | Signs a message with the private key of an address. |
walletlock | Removes the wallet encryption key from memory, locking the wallet. |
walletpassphrase "passphrase" timeout | Stores 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:
| Method | Description |
|---|---|
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:
| Method | Description |
|---|---|
createdatareftx "[scriptPubKey,...]" | Creates a transaction with dataref content. |
createminerinfotx "scriptPubKey" | Create a transaction with a miner info document and return its transaction ID. |
datarefindexdump | Returns details for all currently stored dataRef transactions. |
datareftxndelete "txid" | Delete the specified dataRef transaction from the dataRef index. |
dumpminerids | Returns details for all currently known miner IDs. |
getdatareftxid | Returns the datarefid for the current block being built. |
getmineridinfo "minerId" | Return miner ID information. |
getminerinfotxfundingaddress | Gets the address that will fund the miner info transaction. |
getminerinfotxid | Returns the minerinfotx for the current block being built. |
makeminerinfotxsigningkey | Creates 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:
| Method | Description |
|---|---|
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. |
clearConfiscationWhitelist | Remove all confiscation transactions from whitelist and move previously confiscated TXOs back to a consensus frozen state according to their consensus freeze intervals. |
queryBlacklist | Returns 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:
| Method | Description |
|---|---|
getsafemodeinfo | Returns 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 |
Related articles
To learn more about running SV Node on the BSV blockchain, review these articles: