The SparkBit API allows your own software to control SparkBit’s operations.

By default, SparkBit provide a simple graphical user interface on Windows, Mac and Linux for receiving, holding, verifying and sending CoinSpark messages and assets as well as regular bitcoin. By activating the JSON-RPC API in SparkBit 0.9.3+, these activities can be performed by other pieces of software in an automated fashion, turning SparkBit into the hub of a broader system. The API also enables SparkBit to be used as a replacement for Bitcoin Core in many use cases, with the advantage of it being a lightweight (SPV) client that doesn’t store the entire blockchain.

Activating the SparkBit API (Linux command line)

If you are running on Linux without a graphical interface, we recommend running the JAR file rather than a version packaged with JWrapper.

  • Run java -version to ensure Java is installed correctly. If not, install it as follows.
  • Switch to the directory where SparkBit will be installed.
  • Download the SparkBit JAR from this page using a tool such as wget.
  • Run SparkBit from the JAR: java -jar sparkbit-*.jar
  • After a few seconds, quit SparkBit by pressing Control-C. The default configuration files should have been automatically created.
  • Open ~/SparkBit-Data/jsonrpc.properties in your favorite text editor.
  • Change rpcserver=false to rpcserver=true and save changes.
  • By default incoming API connections will only be accepted from the same computer on which SparkBit is running. To allow connections from anywhere on the Internet, also add rpcallowip=-.-.-.- into the jsonrpc.properties file.
  • Re-run SparkBit in the background: java -jar sparkbit-*.jar &

Activating the SparkBit API (Windows, Mac or Linux with GUI)

If you are running on Windows, Mac or Linux with a graphical user interface:

  • Download SparkBit for your platform, install and open it.
  • Wait until the user interface appears, then quit. This will create the default configuration files.
  • Find the SparkBit-Data directory that was just created, in the following location:

    Windows: C:\Users\<UserName>\AppData\Roaming\SparkBit-Data
    Mac: ~/Library/Application Support/SparkBit-Data
    Linux: ~/SparkBit-Data

  • Open the jsonrpc.properties file in a text editor, change rpcserver=false to rpcserver=true, and save changes.
  • Reopen SparkBit. A “JSON-RPC” indicator should appear in the bottom right of the window, to indicate the API server is running.
  • SparkBit will immediately reflect all API calls in the wallet interface. If you prefer to run SparkBit with no interface, uncomment headless=true in jsonrpc.properties and restart SparkBit.

Getting started with the SparkBit API

Once the SparkBit API has been activated, you can start issuing API commands and viewing their responses.

  • Download sparkbit-cli from the link at the bottom of the SparkBit page. This is a separate download and provides an easy command-line interface to the API, by connecting using the settings in jsonrpc.properties.
  • Run sparkbit-cli getstatus to check the connection is working and sparkbit-cli on its own for help. If you are using sparkbit-cli to connect to a remote server using its domain name, it expects a valid SSL certificate to be installed on the server unless the -k option is used. See API configuration for more information on installing a valid SSL certificate.
  • Alternatively, communicate with the API directly via JSON-RPC, following the settings in jsonrpc.properties. SparkBit uses JSON-RPC 2.0 with fixed positional parameters. By default access is granted only to https requests coming from the same computer.
  • You can stop SparkBit running by issuing the stop command via the API.

API server configuration

The jsonrpc.properties file contains many settings for the API server, for example: which TCP port it listens on, whether to allow non-secure HTTP connections, which IP addresses can connect, and which ciphers and SSL certificates to use. Click to learn more about configuring the API.

API log file

Check the log/jsonrpc.log file in your SparkBit-Data directory for information about API calls, responses and errors. If you are running SparkBit via the JAR file, you can change the level of logging by running it as follows: java -jar sparkbit-*.jar log=debug

Acceptable values for the log parameter are off, warn, info, log, debug and error.

List of API calls

The SparkBit API is available in a Barrister IDL file called sparkbit_api.idl, to enable you to save time when creating your own language bindings.

Command Parameters Description
addasset walletname assetref Manually add an asset by its reference assetref to wallet walletname. Returns true if successful, including if the asset already exists in the wallet.
createaddresses walletname
numaddresses
Create numaddresses new bitcoin/CoinSpark addresses (with their corresponding private keys) in wallet walletname. A maximum of 100 addresses can be created per call. Returns the list of addresses with their label, bitcoin address and CoinSpark address.
createwallet walletname Create a new wallet named walletname. This name is used for the wallet’s files in SparkBit-Data, and for all subsequent API operations on the wallet. Wallet names can contain upper or lower case alphanumeric symbols, hyphens (-) and underscores (_), though they must start with an alphanumeric. Note that walletname is distinct from the wallet description shown in the SparkBit user interface. Returns true if successful.
deleteasset walletname assetref Delete the asset with reference assetref from wallet walletname. This is only permitted if there is zero balance of this asset or if the asset is invalid and canDeleteInvalidAssets=true has been set in sparkbit.properties. Returns true if successful.
deletewallet walletname Delete wallet walletname. This is only permitted if the wallet has zero balance of bitcoin and all assets. Returns true if successful.
getstatus none Get the status of SparkBit. Returns SparkBit’s version number, the number of connections to bitcoin nodes, and the name and synchronization status for each open wallet.
listaddresses walletname Retrieve the list of addresses belonging to wallet walletname. For each address, returns the label, bitcoin address and corresponding CoinSpark address.
listbalances walletname
onlyvisible
Retrieve the balance of bitcoin and assets held by wallet walletname, with additional information about each asset. If onlyvisible is true, only retrieve the balance for assets which are visible in the user interface. For bitcoin and each asset, returns the total and spendable balances in three forms: raw is the integer number of units represented by the blockchain, qty is the real quantity (the raw value multiplied by 108 for bitcoin and the multiple field for CoinSpark assets), and display is a string containing the quantity with the appropriate prefix and/or suffix.
listtransactions walletname
numtransactions
Retrieve the most recent numtransactions transactions sent or received by wallet walletname. For each transaction, returns the quantity of bitcoin and other assets moved, in the same raw, qty and display forms as the listbalances call above.
listunspent walletname minconf
maxconf addresses
Returns the unspent transaction inputs in wallet walletname which have between minconf and maxconf confirmations. To filter by received address, provide a comma-separated list of bitcoin or CoinSpark addresses, otherwise pass - or the empty string.
listwallets none Retrieve a list of the wallets that are open in SparkBit. Each name returned matches that of the wallet’s files in SparkBit-Data, and is used for all API operations on that wallet.
refreshasset walletname assetref Manually refresh the asset with reference assetref in wallet walletname. This begins the process of SparkBit downloading the asset web page and contract, and ensuring that their hash matches that in the asset’s genesis transaction. It also re-checks the quantity of that asset in the wallet via the asset’s tracking server. Returns true if the refresh operation was started successfully. You can then poll the asset’s state via listbalances to determine when the refresh operation has finished.
sendasset walletname address
assetref quantity
senderpays
Send quantity units of the asset with reference assetref from wallet walletname to CoinSpark address address, with a minimum amount of bitcoin required to enable the transaction. The quantity is specified in display units, i.e. to match the qty field in the output from listbalances and listtransactions. If senderpays is true, then the sender pays any CoinSpark payment charges (as defined in the asset genesis, not to be confused with bitcoin transaction charges), otherwise these are deducted from the recipient. If successful, returns the bitcoin txid of the send transaction. Note that the SparkBit API does not currently support password-protected wallets.
sendassetmessage
(SparkBit 0.9.4+)
walletname address
assetref quantity
senderpays message
This works like sendasset but includes the message with the transaction. The address must be a CoinSpark address from a wallet which supports assets and messages.
sendassetusing
(named sendassetwith before SparkBit 0.9.4)
walletname txid
vout address
assetref quantity
senderpays
This works like sendasset but ensures that a particular transaction output txid/vout is included as an input to the outgoing transaction, along with any additional outputs required. This creates a dependency between an incoming transaction and an outgoing transaction, to protect exchange transactions against double spends. Use listunspent to retrieve a list of available unspent transaction outputs.
sendbitcoin walletname address
amount
Send bitcoin only from wallet walletname to the bitcoin or CoinSpark address. The amount is specified in units of bitcoin (BTC). If successful, returns the bitcoin txid of the send transaction. Note that the SparkBit API does not currently support password-protected wallets.
sendbitcoinasset
(SparkBit 0.9.4+)
walletname address
btcamount assetref
assetqty senderpays
This works as a combination of sendasset and sendbitcoin, sending assetqty units of asset assetref together with btcamount BTC in a single transaction output.
sendbitcoinassetmessage
(SparkBit 0.9.4+)
walletname address
btcamount assetref
assetqty senderpays
message
This works like sendbitcoinasset but includes the message with the transaction. The address must be a CoinSpark address from a wallet which supports assets and messages.
sendbitcoinmessage
(SparkBit 0.9.4+)
walletname address
amount message
This works like sendbitcoin but includes the message with the transaction. The address must be a CoinSpark address from a wallet which supports messages.
sendbitcoinusing
(named sendbitcoinwith before SparkBit 0.9.4+)
walletname txid vout
address amount
This works like sendbitcoin but ensures that a particular transaction output txid/vout is included as an input to the outgoing transaction, along with any additional outputs required. This creates a dependency between an incoming transaction and an outgoing transaction, to protect exchange transactions against double spends. Use listunspent to retrieve a list of available unspent transaction outputs.
setaddresslabel walletname address
label
Set the label of address in wallet walletname. The address may be provided as a bitcoin address or any CoinSpark address that maps to that bitcoin address. Returns true if successful.
setassetvisible walletname assetref
isvisible
Set the visibility of the asset with reference assetref in wallet walletname to isvisible. This affects whether the asset is shown in the top pane of the user interface, and whether its balance is returned by a call to listbalances with onlyvisible=true. Returns true if successful.
stop none Shut down SparkBit and the JSON-RPC server. Returns true if the command was issued successfully, and SparkBit will actually exit after a few more seconds.