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:
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.