Spark CLI

Prerequisites

Node.js 20+

Using our Spark CLI tool

We have a CLI tool that allows you to test your wallet operations on Spark. No coding is required!Run the CLI instantly with npx:

npx @buildonspark/cli

Or install it globally:

npm install -g @buildonspark/cli
spark-cli

You can also pass options:

npx @buildonspark/cli --network mainnet
npx @buildonspark/cli --network regtest

This will start the CLI tool and you will be able to interact with the wallet. Run help to see the available commands.

Command Reference

Wallet Setup & Information

Command	Usage
`initwallet`	`initwallet [mnemonic \| seed]` - Create a new wallet from a mnemonic or seed. If no mnemonic or seed is provided, a new mnemonic will be generated.
`getbalance`	Get the wallet's balance
`identity`	Get the wallet's identity public key
`getsparkaddress`	Get the wallet's spark address
`gettransfers`	`gettransfers [limit] [offset]` - Get a list of transfers

Address Operations

Command	Usage
`encodeaddress`	`encodeaddress <identityPublicKey> <network>` - Encodes a identity public key to a spark address (network: mainnet, regtest, testnet, signet, local)
`decodesparkaddress`	`decodesparkaddress <sparkAddress> <network>` - Decode a spark address to get the identity public key (network: MAINNET\|REGTEST\|SIGNET\|TESTNET\|LOCAL)

Deposits

Command	Usage
`getstaticdepositaddress`	Get a static address to deposit funds from L1 to Spark
`getlatesttx`	`getlatesttx <address>` - Get the latest deposit transaction id for an address
`getutxosfordepositaddress`	`getutxosfordepositaddress <depositAddress> <excludeClaimed(true\|false)>` - Get all UTXOs for a deposit address
`claimstaticdepositquote`	`claimstaticdepositquote <txid> [outputIndex]` - Get a quote for claiming a static deposit
`claimstaticdeposit`	`claimstaticdeposit <txid> <creditAmountSats> <sspSignature> [outputIndex]` - Claim a static deposits
`claimstaticdepositwithmaxfee`	`claimstaticdepositwithmaxfee <txid> <maxFee> [outputIndex]` - Claim a static deposit with a max fee

Refunds

Command	Usage
`refundstaticdepositlegacy`	`refundstaticdepositlegacy <depositTransactionId> <destinationAddress> <fee> [outputIndex]` - Refund a static deposit legacy
`refundstaticdeposit`	`refundstaticdeposit <depositTransactionId> <destinationAddress> <satsPerVbyteFee> [outputIndex]` - Refund a static deposit
`refundandbroadcaststaticdeposit`	`refundandbroadcaststaticdeposit <depositTransactionId> <destinationAddress> <satsPerVbyteFee> [outputIndex]` - Refund and broadcast a static deposit

Lightning Network

Command	Usage
`createinvoice`	`createinvoice <amount> <memo> <includeSparkAddress> [receiverIdentityPubkey] [descriptionHash]` - Create a new lightning invoice
`payinvoice`	`payinvoice <invoice> <maxFeeSats> <preferSpark> [amountSatsToSend]` - Pay a lightning invoice
`lightningsendfee`	`lightningsendfee <invoice>` - Get a fee estimate for a lightning send
`getlightningsendrequest`	`getlightningsendrequest <requestId>` - Get a lightning send request by ID
`getlightningreceiverequest`	`getlightningreceiverequest <requestId>` - Get a lightning receive request by ID

Spark Transfers

Command	Usage
`createsparkinvoice`	`createsparkinvoice <asset("btc" \| tokenIdentifier)> [amount] [memo] [senderPublicKey] [expiryTime]` - Create a spark payment request. Amount is optional. Use _ for empty optional fields
`sendtransfer`	`sendtransfer <amount> <receiverSparkAddress>` - Send a spark transfer
`fulfillsparkinvoice`	`fulfillsparkinvoice <invoice1[:amount1]> <invoice2[:amount2]> ...` - Fulfill one or more Spark token invoices (append :amount if invoice has no preset amount)
`querysparkinvoices`	`querysparkinvoices <invoice1> <invoice2> ...` - Query Spark token invoices raw invoice strings

Withdrawals

Command	Usage
`withdraw`	`withdraw <amount> <onchainAddress> <exitSpeed(FAST\|MEDIUM\|SLOW)> [deductFeeFromWithdrawalAmount(true\|false)]` - Withdraw funds to an L1 address
`withdrawalfee`	`withdrawalfee <amount> <withdrawalAddress>` - Get a fee estimate for a withdrawal (cooperative exit)
`getcoopexitrequest`	`getcoopexitrequest <requestId>` - Get a coop exit request by ID

Unilateral Exit

Command	Usage
`unilateralexit`	`unilateralexit [testmode=true]` - Interactive unilateral exit flow (normal mode: timelocks must be naturally expired, test mode: automatically expires timelocks)
`getleaves`	Get all leaves owned by the wallet
`checktimelock`	`checktimelock <leafId>` - Get the remaining timelock for a given leaf
`leafidtohex`	`leafidtohex <leafId1> [leafId2] [leafId3] ...` - Convert leaf ID to hex string for unilateral exit
`generatefeebumppackagetobroadcast`	`generatefeebumppackagetobroadcast <feeRate> <utxo1:txid:vout:value:script:publicKey> [utxo2:...] [nodeHexString1] [nodeHexString2 ...]` - Get fee bump packages for unilateral exit transactions (if no nodes provided, uses all wallet leaves)
`generatefeebumptx`	`generatefeebumptx <cpfpTx>` - Generate a fee bump transaction for a given cpfp transaction
`signfeebump`	`signfeebump <feeBumpPsbt> <privateKey>` - Sign a fee bump package with the utxo private key

Tokens

Command	Usage
`createtoken`	`createtoken <tokenName> <tokenTicker> <decimals> <maxSupply> <isFreezable>` - Create a new token
`transfertokens`	`transfertokens <tokenIdentifier> <receiverAddress> <amount>` - Transfer tokens
`batchtransfertokens`	`batchtransfertokens <tokenIdentifier> <receiverAddress1:amount1> <receiverAddress2:amount2> ...` - Transfer tokens with multiple outputs
`minttokens`	`minttokens <amount>` - Mint new tokens
`burntokens`	`burntokens <amount>` - Burn tokens
`freezetokens`	`freezetokens <sparkAddress>` - Freeze tokens for a specific address
`unfreezetokens`	`unfreezetokens <sparkAddress>` - Unfreeze tokens for a specific address
`querytokentransactions`	`querytokentransactions [--sparkAddresses] [--ownerPublicKeys] [--issuerPublicKeys] [--tokenTransactionHashes] [--tokenIdentifiers] [--outputIds] [--order] [--pageSize] [--offset]` - Query token transaction history. Note: Only one filter type can be used per query. Use `--sparkAddresses` (recommended) instead of deprecated `--ownerPublicKeys`.
`decodetokenidentifier`	`decodetokenidentifier <tokenIdentifier>` - Returns the raw token identifier as a hex string

Token Issuer Operations

Command	Usage
`getissuertokenbalance`	Get the issuer's token balance
`getissuertokenmetadata`	Get the issuer's token metadata
`getissuertokenidentifier`	Get the issuer's token identifier
`getissuertokenpublickey`	Get the issuer's token public key
`gettokenl1address`	Get the L1 address for on-chain token operations

Testing & Development

Command	Usage
`testonly_generateexternalwallet`	Generate test wallet to fund utxos for fee bumping
`testonly_generateutxostring`	`testonly_generateutxostring <txid> <vout> <value> <publicKey>` - Generate correctly formatted UTXO string from your public key

System

Command	Usage
`enablelogging`	`enablelogging <true\|false>` - Enable or disable logging
`setloggerlevel`	`setloggerlevel <trace\|info>` - Set the logging level
`help`	Show this help message
`exit/quit`	Exit the program

Introduction

Installation

Wallet

Transfers

Deposits

Withdrawals

Fees

Spark Signer Interface

Tools

Prerequisites

Using our Spark CLI tool

Command Reference

Wallet Setup & Information

Address Operations

Deposits

Refunds

Lightning Network

Spark Transfers

Withdrawals

Unilateral Exit

Tokens

Token Issuer Operations

Testing & Development

System