NPM Package
Cardware BTC NPM Library
View On NPM: https://www.npmjs.com/package/cardware-btc
This is the documentation for the BTC NPM package that communicates with the Cardware device.
The library requires an electrs endpoint to query the bitcoin blockchain.
It allows users to create a Watch-Only Wallet on Web.
All data that is transferred between the web wallet and the Cardware device is done through scanning QR codes.
Users must first pair the web wallet with their Cardware device.
Once paired they are then able to view the BTC address of their Cardware device, see their confirmed and unconfirmed BTC balances and send BTC from their Cardware device.
When sending, the watch only wallet will create an unsigned transaction which will be split up into QR codes. The user will then be prompted to scan these QRcodes with their Cardware device. The user will then confirm the transactions details which will then create a signed transaction which their Cardware device will split up into QR codes. The web wallet then scans these QR codes, decodes them and broadcasts the transaction.
Documentation
Initialization
Code
import Wallet from 'cardware-btc'; New Wallet
This function initializes a wallet object in your web wallet. The zpub is received from the Cardware device after successfully pairing the web wallet and Cardware device. The pairing process involves scanning the pair QR codes from the Cardware device, extracting the zpub, then using it in creating the wallet object.
Parameters
zpub
string
The zpub of the the hardware wallet.
"vpub5ZNhc5KKM6hACK6QDuo6UG1749XUeXf9Gbu8rcZQnNDeMJwUPrwzEVKsF7X7EzZe5yqwymfMA1tGJ9qAmjdmGHSkRW7SruCEDz9mgEkwWvN"
esplora_url
string
The address of the esplora you are using.
"https://blockstream.info/api"
network
string
The network you are using (mainnet or testnet).
"mainnet"
Code
var wallet = await new Wallet(zpub, esplora_url, network);Output
No outputs.
Sync
This function syncs your web wallet to make sure it has all the correct information to be able to get balances, construct unsigned transactions and broadcast transactions.
Parameters
No parameters.
Code
await wallet.sync();Output
The output is a string.
success
The wallet has synced successfully.
"Sync successful."
error
There is an issue fetching the fee estimates.
"Error: Fee sync error."
error
There is an issue with connecting to the esplora url.
"Error: Failed to connect to full node (Esplora)."
error
There is an issue deserializing the transaction.
"Error: Failed to deserialize transaction."
Sync to Depth
This function syncs your web wallet with max depth as a parameter to make sure it has all the correct information to be able to get balances, construct unsigned transactions and broadcast transactions.
Parameters
max_depth
string
The max depth of the addresses you need to sync.
"m/0/0"
Code
await wallet.sync_to_depth(max_depth);Output
The output is a string.
success
The wallet has synced successfully.
"Sync successful."
error
There is an issue fetching the fee estimates.
"Error: Fee sync error."
error
There is an issue with connecting to the esplora url.
"Error: Failed to connect to full node (Esplora)."
error
There is an issue deserializing the transaction.
"Error: Failed to deserialize transaction."
Estimate Fees
This function estimates fees for a send transaction which takes a variable called number of blocks where the lower the number of blocks, the higher the estimated fee and the faster the transaction will confirm. Users can batch send transactions by populating multiple addresses and multiple amounts however the user must make sure both arrays have the same length.
Parameters
addresses
array[string]
The addresses to send to.
["bc1q82d5gkw4xa0dgs55khfx0y4s7ntjwtfxu4h4fg"]
amounts
array[int64]
The send amounts in satoshis.
[1480]
number_of_blocks
int32
The number of blocks for fee estimation. The lower the number, the higher the fee.
3
Code
let result = wallet.estimate_fee(addresses, amounts, number_of_blocks);Output
The output is a uint64.
success
The fee estimation for a transaction (in satoshis).
1480
error
The addresses array and the amounts array are not the same length.
0
error
There is an issue parsing the network.
1
error
There is an invalid recipient address.
2
error
There is an issue fetching the fee estimates.
3
error
There is insufficient BTC to make this transaction.
4
error
There are no UTXOs to spend.
5
Estimate Sweep Fees
This function estimates fees for a max send transaction which takes a variable called number of blocks where the lower the number of blocks, the higher the estimated fee and the faster the transaction will confirm. This is called a sweep when a user wants to empty their wallet.
Parameters
number_of_blocks
int32
The number of blocks for fee estimation. The lower the number, the higher the fee.
3
Code
let result = wallet.estimate_sweep_fee(number_of_blocks);Output
The output is a uint64.
success
The fee estimation for a transaction (in satoshis).
1480
error
There is an issue parsing the network.
1
error
There is an issue fetching the fee estimates.
3
error
There are no UTXOs to spend.
5
Send
This function creates an unsigned transaction which it converts into a base64 string which it then splits up into chunks to be put into multiple QR codes. At the beginning of each chunk extra information is added. The extra information has the format of ( + index of QR code + / + total QR codes + ) + part of the unsigned transaction as a base64 string.
Parameters
addresses
array[string]
The addresses to send to.
["bc1q82d5gkw4xa0dgs55khfx0y4s7ntjwtfxu4h4fg"]
amounts
array[int64]
The send amounts (in satoshis).
[1000]
fee
int64
The transaction fee worked out in estimate_fee (in satoshis).
1480
Code
var qrcode_chunks = wallet.send(addresses, amounts, fee);Output
The output is an array of strings.
success
An array of base64 strings which can be shown as QR codes.
["(0/6)AgAAAAJCfJSUSIPEKOeG56APmMCEP6zPRPCz1/zyBsnFR5", "(1/6)gNNAAAAAAA/////4j8W+GTLq29Of7VdtqzMmkGpLJocgYd", "(2/6)1l/n4Crlse8vAAAAAAD/////AtAHAAAAAAAAFgAU3HfuEr", "(3/6)x48JEWN7r+DtOnmtCUXWBCWgAAAAAAABYAFDqbRFnVN17U", "(4/6)QpS10meSsPTXJy0mAAAAAA==:AAAAAOgDAAAAAAAAAAAAA", "(5/6)KhhAAAAAAAA"]
error
The addresses array and the amounts array are not the same length.
["Error: Recipients and amounts arrays must be the same length."]
error
The address is not associated with the BTC network.
["Error: Failed to parse network."]
error
The send amount is under the dust limit of 546.
["Error: Send amount under dust limit."]
error
There is insufficient BTC to make this transaction.
["Error: Insufficient funds."]
error
There are no UTXOs to spend.
["Error: No UTXOs to spend."]
error
There is an issue with the derivation path.
["Error: Derivation path error."]
error
There is an invalid recipient address.
["Error: Invalid recipient address."]
error
There is an issue with the multi-sig size and threshold.
"Error: Invalid multi-sig size and threshold, please use n/n eg. 2/3."
error
There is an issue deriving the zpub.
"Error: Zpub derivation error."
error
There are no zpubs to create a wallet.
"Error: Wallet requires at least one zpub."
Broadcast
This function needs a signed transaction as a base64 string. It gets this by scanning the QR codes on the Cardware device. When scanning the QR codes of the signed transaction from the Cardware device it follows the format of ( + index of QR code + / + total QR codes + ) + part of the signed transaction as a base64 string.
Parameters
signed_transaction
string
The signed transaction in base64 that needs to be broadcasted.
"AgAAAAABAUJ8lJRIg8Qo54bnoA+YwIQ/rM9E8LPX/PIGycVHmA00AQAAAAD/////AugDAAAAAAAAFgAUOptEWdU3XtRClLXSZ5Kw9NcnLSabIwAAAAAAABYAFDWIiG3dUA5i2rzZg529bq4aQWPFAkgwRQIhAPk1OEfut27Z/YZsu5Xeik10inhcYYfXDXFRkOnqz/Y8AiBvx0Uqw3q3+LV8MA/cJZKComCL/2r/zXIx9cay94JXIwEhA4HigQXlfm+OMUk3YXW5cGxWOYZqfPzF0dMNLyWSHw+FAAAAAA=="
Code
await wallet.broadcast(signed_transaction);Output
The output is a strings.
success
The transaction ID of the broadcasted transaction.
"340d9847c5c906f2fcd7b3f044cfac3f84c0980fa0e786e728c4834894947c42"
error
There is an issue parsing the base64 transaction string.
"Error: Failed to parse base64 transaction."
error
There is an issue decoding the hex transaction.
"Error: Decoding failed."
error
The signed transaction is invalid.
"Error: Invalid transaction."
error
There is an issue broadcasting the transaction.
"Error: Failed to broadcast transaction."
Broadcast Multisig
This function needs an array of signed transactions as a list of base64 strings. It gets these by scanning the QR codes on the Cardware devices that are part of the multisig. When scanning the QR codes of the signed transaction from the Cardware device it follows the format of ( + index of QR code + / + total QR codes + ) + part of the signed transaction as a base64 string.
Parameters
transaction_signatures
array[string]
An array of signed transactions in base64 which will be used to broadcast the multisig transaction.
["AgAAAAABAbIVaiUeeL10JflXCbw4727RyErZ8/+ERs9hdIrVmrpNAQAAAAD/////AegDAAAAAAAAFgAUg3fJmFw+Xphk3Et2NlpZUoP4XycDSDBFAiEAk5onGG5supY9hsaXdgNIFOoT//95KXLdsO66FIZyo1gCIFmOTSc/6AIGc5hi1d5hBD9dCeApNs2b/frRSLq4VOc/ASECcikWYSZ3j4ahirRPBY3ZAasVUf7KelhHCdevmCn5MgVHUiECGXDMUG+QxA779XjIsWRTtZfDH1A3SV/KrTvZh6e9CJUhAnIpFmEmd4+GoYq0TwWN2QGrFVH+ynpYRwnXr5gp+TIFUq4AAAAA", "AgAAAAABAbIVaiUeeL10JflXCbw4727RyErZ8/+ERs9hdIrVmrpNAQAAAAD/////AegDAAAAAAAAFgAUg3fJmFw+Xphk3Et2NlpZUoP4XycDSDBFAiEAw/GaAfnJhAEmdWl8wuCN73qXcgBrcdxMp6/+xMVCPdECIEQIrLKA8tONmhswU1FU7HSDthx/pIxj1PXvGaVq7h7EASECGXDMUG+QxA779XjIsWRTtZfDH1A3SV/KrTvZh6e9CJVHUiECGXDMUG+QxA779XjIsWRTtZfDH1A3SV/KrTvZh6e9CJUhAnIpFmEmd4+GoYq0TwWN2QGrFVH+ynpYRwnXr5gp+TIFUq4AAAAA"]
Code
await wallet.broadcast_multisig(transaction_signatures);Output
The output is a string.
success
The transaction ID of the broadcasted transaction.
"340d9847c5c906f2fcd7b3f044cfac3f84c0980fa0e786e728c4834894947c42"
error
There is an issue deriving the zpub.
"Error: Zpub derivation error."
error
There is an issue parsing the base64 transaction string.
"Error: Failed to parse base64 transaction."
error
There is an issue decoding the hex transaction.
"Error: Decoding failed."
error
The signed transaction is invalid.
"Error: Invalid transaction."
error
One or more of the signed transactions is invalid.
"Error: Invalid transaction signatures."
error
There is an issue broadcasting the transaction.
"Error: Failed to broadcast transaction."
Address
This function returns the address of your Cardware device.
Parameters
No parameters.
Code
const result = wallet.address();Output
The output is a string.
success
The address of the wallet.
"bc1qxkygsmwa2q8x9k4umxpem0tw4cdyzc79kn5r5p"
error
There is an invalid extended public key.
"Error: Invalid extended public key."
error
There is an issue deriving the zpub.
"Error: Zpub derivation error."
New Address
This function returns the address of your Cardware device at a certain depth.
Parameters
derivation_path
string
The derivation path the new address must be derived from.
"m/0/0"
Code
const result = wallet.new_address(derivation_path);Output
success
The address of the wallet.
"bc1qxkygsmwa2q8x9k4umxpem0tw4cdyzc79kn5r5p"
error
There is an invalid extended public key.
"Error: Invalid extended public key."
error
There is an issue deriving the zpub.
"Error: Zpub derivation error."
error
There is an issue with the multi-sig size and threshold.
"Error: Invalid multi-sig size and threshold, please use n/n eg. 2/3."
error
There are no zpubs to create a wallet.
"Error: Wallet requires at least one zpub."
Balance
This function returns confirmed balance of your Cardware device.
Parameters
No parameters.
Code
const result = wallet.balance();Output
The output is a unint64.
success
The confirmed balance of your wallet (in satoshis).
"11225"
Unconfirmed Balance
This function returns unconfirmed balance of your Cardware device.
Parameters
No parameters.
Code
const result = wallet.unconfirmed_balance();Output
The output is a unint64.
success
The unconfirmed balance of your wallet (in satoshis).
"1000"
Last updated