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:
Descriptions of these JSON-RPC methods are reproduced below.
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.
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).
hash_type: string (optional, default = hash_serialized_2) - Which UTXO set hash should be calculated. Options: ‘hash_serialized_2’ (the legacy algorithm), ‘none’.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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:
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.
Fee and Size Checks: The call assesses whether the transaction fees are adequate and if the transaction size is within acceptable limits.
Double-Spend Checks: It verifies that the transaction doesn't attempt to double-spend any UTXOs (Unspent Transaction Outputs).
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
