Page cover

btc (Standard Bitcoin RPC)

SANDSHREW hosts a fully hosted Bitcoin node, for each supported network, and passes through JSON-RPC requests that are either namespaced with the btc_ prefix, or otherwise have no namespace, directly to the Bitcoin core JSON-RPC which will be familiar to anyone who has developed against a Bitcoin node. The Bitcoin node hosted by SANDSHREW runs with the -txindex flag set, so full indexing service is provided and data surfaced as-is.

The Bitcoin RPC is documented on the Bitcoin developer documentation, specifically here:

LogoRPC API Reference — Bitcoindeveloper.bitcoin.org

Descriptions of these JSON-RPC methods are reproduced below.

Bitcoin RPC

getblock

Returns block information.

Params

blockhash: string (required)

verbosity: number (optional)

  • 0 for hex-encoded data

  • 1 for a json object (default)

  • 2 for json object with transaction data

Response

getbestblockhash

Returns the hash of the best (tip) block in the most-work fully-validated chain.

Params

None

Response

getblockchaininfo

Returns an object containing various state info regarding blockchain processing.

Params

None

Response

getblockcount

Returns the height of the most-work fully-validated chain.

Params

None

Response

getblockhash

Returns hash of block in best-block-chain at height provided.

Params

blockheight: string (required) - The height index

Response

getblockheader

If verbose is false, returns a string that is serialized, hex-encoded data for blockheader ‘hash’.

If verbose is true, returns an Object with information about blockheader ‘hash’.

Params

blockhash: string (required)

verbosity: boolean (optional, default = true)

Response

getblockstats

Returns block information.

Params

blockhash | blockheight: string (required) - The block hash or height of the target block

stats: json array (optional, default=all values) - Values to return

Response

getchaintips

Return information about all known tips in the block tree, including the main chain as well as orphaned branches.

Params

None

Response

height: (numeric) - Height of the chain tip

hash: (string) block hash of the tip

branchlen: (numeric) zero for main chain, otherwise length of branch connecting the tip to the main chain

status: (string) status of the chain, "active" for the main chain

Possible values for status:

invalid - This branch contains at least one invalid block

headers-only - Not all blocks for this branch are available, but the headers are valid

valid-headers - All blocks are available for this branch, but they weren't fully validated

valid-fork - This branch is not part of the active chain, but is fully validated

active - This is the tip of the active main chain, which is certainly valid

getchaintxstats

Compute statistics about the total number and rate of transactions in the chain

Params

nblocks: number (optional, default = one month) - Size of the window in number of blocks

blockhash: string (optional, default = chain tip) - The hash of the block that ends the window.

Response

getdifficulty

Returns the proof-of-work difficulty as a multiple of the minimum difficulty.

Params

None

Response

getmempoolancestors

If txid is in the mempool, returns all in-mempool ancestors.

Params

txid: string (required) - The transaction id (must be in mempool)

verbosity: boolean (optional, default = false) - True for a json object, false for array of transaction ids

Response

getmempooldescendants

If txid is in the mempool, returns all in-mempool descendants.

Params

txid: string (required) - The transaction id (must be in mempool)

verbosity: boolean (optional, default = false) - True for a json object, false for array of transaction ids

Response

getmempoolentry

Returns mempool data for given transaction

Params

txid: string (required) - The transaction id (must be in mempool)

Response

getmempoolinfo

Returns details on the active state of the TX memory pool.

Params

None

Response

getrawmempool

Returns all transaction ids in memory pool as a json array of string transaction ids.

Hint: use getmempoolentry to fetch a specific transaction from the mempool.

Params

verbosity: boolean (optional, default = false) - True for a json object, false for array of transaction ids

mempool_sequence: boolean (optional, default = false) - If verbose=false, returns a json object with transaction list and mempool sequence number attached.

Response

gettxout

Returns details about an unspent transaction output.

Params

txid: string (required) - The transaction id

n: number (required) - vout number

include_mempool: boolean (optional) - Whether to include the mempool. Note that an unspent output that is spent in the mempool won’t appear.

Response

gettxoutproof

Returns a hex-encoded proof that “txid” was included in a block.

NOTE: By default this function only works sometimes. This is when there is an unspent output in the utxo for this transaction. To make it always work, you need to maintain a transaction index, using the -txindex command line option or specify the block in which the transaction is included manually (by blockhash).

Params

txids: string[] (required) - The txids to filter

blockhash: string (optional) - If specified, looks for txid in the block with this hash

Response

gettxoutsetinfo

Returns statistics about the unspent transaction output set.

Note this call may take some time.

Params

hash_type: string (optional, default = hash_serialized_2) - Which UTXO set hash should be calculated. Options: ‘hash_serialized_2’ (the legacy algorithm), ‘none’.

Response

verifytxoutproof

Verifies that a proof points to a transaction in a block, returning the transaction it commits to and throwing an RPC error if the block is not in our best chain

Params

proof: string (required) - The hex-encoded proof generated by gettxoutproof

Response

Rawtransactions RPCs

analyzepsbt

btc_analyzepsbt analyzes and provides information about the current status of a PSBT and its inputs.

Params

psbt: string (required) - A base64 string of a PSBT.

Response

combinepsbt

btc_combinepsbt combines multiple partially signed PSBTs into a single PSBT. It takes partially signed transactions from various sources and consolidates them. This is important in multi-signature or complex transaction processes where each party contributes part of the transaction's data or signatures.

Params

psbts: [string] (required) - An array of base64-encoded PSBTs. These are the PSBTs that are to be combined. It's assumed that each PSBT in the array contains some of the necessary data or signatures needed for the final transaction.

Response

combinerawtransaction

btc_combinerawtransaction combines multiple partially signed raw transactions, in hexidecimal format, into one transaction. The combined transaction may be another partially signed transaction or a fully signed transaction. Each input transaction must have the same output structure to be successfully combined.

Useful for multi-signature transactions where each party signs the transaction separately. btc_combinerawtransaction collects these partial signatures and combines them into one transaction.

Params

txs: [string] (required) - An array of raw transaction strings (in hexadecimal format). These are the partially signed or unsigned transactions that you want to combine.

Response

converttopsbt

btc_converttopsbt converts a standard Bitcoin raw transaction into a PSBT. This functionality is particularly useful when starting with a non-PSBT transaction format and needing to transition to a PSBT for multi-signature or advanced signing workflows. The conversion process ensures that the resulting PSBT remains unsigned, making it suitable for passing around to various parties for signatures.

Params

raw_txn: string (required) - The hexadecimal string of the raw transaction that you wish to convert into a PSBT. This is the serialized, hex-encoded form of a standard Bitcoin transaction.

permitsigdata: boolean (optional) - A boolean parameter. If set to true, it allows the inclusion of signature scripts and witness data in the PSBT if they are present in the input transaction. This can be useful if the raw transaction already contains some signatures, but generally, this should be false to keep the PSBT unsigned.

iswitness: boolean (optional) - A boolean parameter indicating whether the transaction is a witness transaction. Setting this to true is necessary for Segregated Witness (SegWit) transactions to ensure the correct construction of the PSBT.

Response

createpsbt

btc_createpsbt creates a PSBT. It can be used for creating transactions that require multiple signatures or specific signing arrangements.

Params

inputs: string array (required) - An array of JSON objects, each representing an input to the transaction. Each object typically contains the following fields:

  • txid: The transaction ID from which you're spending an output.

  • vout: The index of the output in the previous transaction (starting from 0).

  • sequence (optional): The sequence number of the input. It can be used for more advanced features like Replace-By-Fee (RBF).

outputs: string (required) - This can be either a JSON object or an array of JSON objects specifying the transaction's outputs. There are two formats to provide this information:

  • Object format: Where the object's keys are Bitcoin addresses or a scriptPubKey, and values are amounts of bitcoin to send.

  • Array format: Each element of the array is an object with address or scriptPubKey and amount.

locktime: string (optional) - A Unix timestamp or block number that determines when the transaction may be added to a block. A transaction with a locktime set won't be included in a block before the specified time or block number.

replaceable: boolean (optional) - A boolean flag indicating whether the transaction should be marked as BIP125 replaceable, allowing it to be replaced by a transaction with a higher fee (if it's not yet confirmed).

options: string (optional) - A JSON object where you can specify additional options such as add_inputs (to automatically add inputs to meet the output value requirements) and change_address (to set a specific change address).

Response

createrawtransaction

btc_createrawtransaction creates a new, raw, and unsigned Bitcoin transaction.

Params

inputs: string array (required) - An array of JSON objects, each representing an input to the transaction. Each object typically contains the following fields:

  • txid: The transaction ID from which you're spending an output.

  • vout: The index of the output in the previous transaction (starting from 0).

  • sequence (optional): The sequence number of the input. It can be used for more advanced features like Replace-By-Fee (RBF).

outputs: string (required) - Either an array of JSON objects or a single JSON object. Each output specifies an address and the amount of bitcoin to send to that address. There are two formats:

  • Object format: Keys are Bitcoin addresses and values are amounts to send to those addresses.

  • Array format: Each element is an object with address and amount fields.

locktime: string (optional) - A Unix timestamp or block number until which the transaction will be locked and not included in a block. If omitted, defaults to 0, meaning no locktime.

replaceable: boolean (optional) - A boolean flag indicating whether the transaction should be marked as BIP125 replaceable, allowing it to be replaced by a transaction with a higher fee (if it's not yet confirmed).

Response

decodepsbt

btc_decodepsbt decodes a base64-encoded PSBT into a structured, readable format. The decoded output provides comprehensive information about the PSBT, including its inputs, outputs, any signatures it contains, and additional metadata.

Params

psbt: string (required) - The base64-encoded PSBT that you want to decode.

Response

decoderawtransaction

btc_decoderawtransaction decodes a serialized, hex-encoded transaction into a human-readable format.

Params

hexstring: string (required) - The hex-encoded transaction data that you want to decode.

iswitness: boolean (optional, default = false) - Indicates whether the transaction includes SegWit data. If set to true, the decoder will expect and properly handle a Segregated Witness (SegWit) transaction format. If omitted or set to false, the decoder treats the transaction as a non-SegWit transaction.

Response

decodescript

btc_decodescript is used to decode a hex-encoded script and provide human-readable details about it. The decoded information includes details such as the type of script (e.g., P2PKH, P2SH), required signatures, and any embedded addresses.

Params

scriptHex: string (required) - The hexadecimal encoded script that you want to decode. The script could be a transaction output script (scriptPubKey), a redeem script, or any other valid script in hex format.

Response

finalizepsbt

btc_finalizepsbt is used to finalize a Partially Signed Bitcoin Transaction (PSBT). This process involves completing the signing of the transaction and converting it into a fully signed transaction that is ready to be broadcast to the Bitcoin network.

Here's a breakdown of its functionality:

  1. Completing Signatures: The primary function of btc_finalizepsbt is to complete the signing of all inputs in the PSBT. It checks if all necessary signatures are present and valid for each input.

  2. Constructing the Final Transaction: Once all inputs are fully signed, btc_finalizepsbt constructs a final, standard Bitcoin transaction from the PSBT. This transaction is in a standard serialized transaction format, which is recognized and can be processed by the Bitcoin network.

  3. Ensuring Transaction Validity: The API call also checks that the transaction is valid. This includes ensuring that all inputs are correctly signed and that the transaction conforms to Bitcoin's transaction rules.

  4. Extracting the Transaction: If the PSBT is fully signed, btc_finalizepsbt extracts and returns the fully signed transaction in a hexadecimal string format. This string can then be directly submitted to the Bitcoin network for confirmation and inclusion in a block.

  5. Use in Multi-Party Transactions: btc_finalizepsbt is particularly useful in multi-party transaction scenarios where a PSBT has been passed around multiple parties for signing. It provides a simple and secure way to finalize the transaction once all parties have provided their signatures.

Params

psbt: string (required) - the PSBT in base64-encoded format.

extract: boolean (optional, default = true) - When set to true, the call will automatically extract and return the fully signed transaction in raw format (hexadecimal string) if the PSBT is finalized successfully. If set to false, the PSBT is finalized but the raw transaction is not automatically extracted.

Response

getrawtransaction

btc_getrawtransaction retrieves detailed information about a specific transaction in the Bitcoin network. It's particularly useful for examining the details of transactions that are either in the mempool or already included in a block.

By default this function only works for mempool transactions. When called with a blockhash argument, btc_getrawtransaction will return the transaction if the specified block is available and the transaction is found in that block.

Params

txid: string (required) - The transaction ID of the transaction you want to retrieve.

verbose: boolean (optional, default = false) - A boolean flag that indicates the format of the output. If set to true (or 1), the output will be JSON formatted and contain detailed, human-readable information about the transaction. If set to false (or 0), the output will be the raw transaction in hexadecimal format.

blockhash: string (optional) - The hash of the block in which to look for the transaction. If provided, it speeds up the search by limiting it to a specific block. It's particularly useful for transactions that are not in the mempool but included in a block.

Response

joinpsbts

btc_joinpsbts is used for joining multiple Partially Signed Bitcoin Transactions (PSBTs) into a single PSBT. PSBT is a standard format for Bitcoin transactions that are not fully signed, allowing for transactions to be passed around multiple parties for signing without revealing the private keys.

Functionality of btc_joinpsbts includes:

  1. Combining Transactions: It takes multiple PSBTs as input and combines them into one. This is particularly useful in scenarios where different parties have created separate PSBTs for different inputs or outputs, and these need to be consolidated into a single transaction.

  2. Facilitating Multi-Party Transactions: In situations where a transaction requires inputs or consents from multiple parties, each party can create their own PSBT. btc_joinpsbts then merges these into a single PSBT that encompasses all the inputs, outputs, and signatures provided by the individual parties.

  3. Streamlining the Signing Process: Once the PSBTs are joined, the resulting single PSBT can be passed to each relevant party for signing. This streamlines the process, as each party can sign the same transaction instead of having to deal with multiple transactions.

  4. Use in Complex Transaction Scenarios: This call is particularly useful in complex transaction scenarios like multi-signature transactions, CoinJoin transactions, or batch processing of transactions.

Params

psbt_array: [strings] (required) - An array of PSBTs in base64 string format. Each PSBT in the list represents a transaction that has been partially signed or constructed but not finalized.

Response

sendrawtransaction

Submit a raw transaction (serialized, hex-encoded) to local node and network.

Note that the transaction will be sent unconditionally to all peers, so using this for manual rebroadcast may degrade privacy by leaking the transaction’s origin, as nodes will normally not rebroadcast non-wallet transactions already in their mempool.

Also see createrawtransaction and signrawtransactionwithkey calls.

Params

raw_tx: string (required) - The hex string of the raw transaction.

maxfeerate: number (number or string, optional, default=0.10) - Reject transactions whose fee rate is higher than the specified value, expressed in BTC/kB. Set to 0 to accept any fee rate.

Response

testmempoolaccept

btc_testmempoolaccept is used to test how a transaction would be received by the mempool without actually broadcasting it to the network. Here's an overview of its functionality:

  1. Transaction Validation: It validates a raw transaction to check whether it would be accepted into the mempool. This validation includes various checks like transaction syntax, structure, and whether it meets the network's consensus rules.

  2. Fee and Size Checks: The call assesses whether the transaction fees are adequate and if the transaction size is within acceptable limits.

  3. Double-Spend Checks: It verifies that the transaction doesn't attempt to double-spend any UTXOs (Unspent Transaction Outputs).

  4. Chain State Consideration: The API call considers the current state of the blockchain and the mempool to evaluate if the transaction would be accepted at that particular moment.

  5. No Actual Broadcast: Importantly, btc_testmempoolaccept does not broadcast the transaction to the network. It's a purely local test to see if the transaction would be accepted by the mempool under current conditions.

  6. Response Data: It returns information on whether the transaction would be accepted and, if not, provides details about why it would be rejected.

Note that the transaction will be sent unconditionally to all peers, so using this for manual rebroadcast may degrade privacy by leaking the transaction’s origin, as nodes will normalin getgly not rebroadcast non-wallet transactions already in their mempool.

Params

raw_txs: [string] (required) - An array of raw transaction strings (in hexadecimal format). Each string represents a serialized transaction that you want to test for mempool acceptance. Even if you're testing just one transaction, it needs to be wrapped in an array.

maxfeerate: number (number or string, optional, default=0.10) - specifies the maximum fee rate, in satoshis per virtual byte, that a transaction can have to be considered for mempool acceptance in this test. If a transaction's fee rate is higher than this value, the testmempoolaccept call will reject it. If this parameter is not set, the node's default mempool maximum fee rate is used. Set to 0 to accept any fee rate.

Response

utxoupdatepsbt

btc_utxoupdatepsbt updates a PSBT with information about the UTXOs it spends. This is particularly useful in scenarios where a PSBT lacks certain details about the UTXOs, which are necessary for signing and finalizing the transaction.

Params

psbt: string (required) - The base64-encoded PSBT that needs updating. This PSBT should have inputs and outputs already defined but might be missing UTXO details.

descriptors: string array (optional) - An array of output descriptors that provide information about the output scripts of the UTXOs being spent. This parameter is optional but can be helpful in cases where the PSBT does not have full UTXO information.

Response

Util RPCs

createmultisig

btc_createmultisig creates a multi-signature address. Multi-signature addresses require more than one private key to authorize a transaction, enhancing the security of Bitcoin transactions

Params

nrequired: string (required) - An integer specifying the number of required signatures to spend bitcoins from the multi-signature address. For example, in a "2-of-3" multi-signature setup, nrequired would be 2.

keys: string array (required) - An array of strings, where each string is a public key. These public keys are used to construct the multi-signature address. The number of keys in the array can be more than nrequired.

address_type: string (optional) - A string specifying the type of address to create. The options usually include "legacy" (for P2SH addresses) and "bech32" (for P2WSH addresses). If omitted, the default is typically "legacy".

Response

deriveaddresses

btc_deriveaddresses derives one or more addresses from an output descriptor. Output descriptors provide a human-readable way to describe Bitcoin addresses, including information about how to spend coins sent to these addresses.

Params

descriptor: string (required) - A string representing the output descriptor from which addresses are to be derived. This descriptor includes details about the type of address, the public keys involved, and any additional scripting requirements.

begin: string (optional) - An integer specifying the starting index for address derivation. This is relevant for descriptors that define a range of addresses, like those used in HD wallets. If omitted, the default value is typically 0.

end: string (optional) - An integer specifying the ending index for address derivation. Like the begin parameter, this defines the range of addresses to derive from the descriptor. If omitted, the API call will only derive the address at the begin index.

Response

estimatesmartfee

btc_estimatesmartfee estimates the transaction fee per kilobyte that should be included with a transaction in order to have it confirmed within a certain number of blocks. This estimation is based on the current state of the mempool and recent blocks.

Params

conf_target: string (required) - An integer specifying the desired confirmation time, in number of blocks, for the transaction. For example, setting this to 6 would mean you want the transaction to be confirmed within approximately 6 blocks.

estimate_mode: string (optional) - A string indicating the estimation strategy to use. Possible values include:

  • "UNSET" (default): The Bitcoin Core algorithm will select the best estimation mode automatically.

  • "ECONOMICAL": Provides fee estimates that aim to minimize costs.

  • "CONSERVATIVE": Provides higher fee estimates that prioritize confirmation reliability over cost.

Response

getdescriptorinfo

btc_getdescriptorinfo provides information about a descriptor. A descriptor is a more expressive way to describe Bitcoin script types for wallets, including information on how to spend outputs sent to these addresses. The call calculates and returns a checksum for the descriptor, which is used to verify its integrity.

Params

descriptor: string (required) - A string representing the output descriptor to be analyzed. This descriptor should contain information about the script or address type, along with key information.

Response

getindexinfo

btc_getindexinfo obtains information about the state of the blockchain indexes. These indexes are additional structures maintained by the node, which provide faster access to certain types of data, like transaction data or block information.

Params

None

Response

validateaddress

btc_validateaddress validates and provides detailed information about a Bitcoin address. If the address is valid, it provides detailed information about it, including the address type, whether it belongs to the wallet, and its associated public key (if available). For script addresses, it provides information about the script.

Params

address: string (required) - The Bitcoin address to be validated.

Response

verifymessage

btc_verifymessage verifies a signed message. This function is used in scenarios where you need to prove ownership of a Bitcoin address or validate the authenticity of a message signed with a Bitcoin private key.

Params

address: string (required) - The Bitcoin address used to sign the message.

signature: string (required) - The signature created by signing the message with the private key of the Bitcoin address.

message: string (required) - The original message that was signed.

Previousesplora (Block Explorer APIs)NextMulticall

Last updated