Documentation

Our lightweight, easy to use API let's you implement and control the miner with ease. We're constantly working hard to add new features so please check back.

Quick Start

Place the SpareChange miner script in the head of your website.

<script type="text/javascript" src="https://www.sparechange.io/static/sparechange.js"></script>

To start mining place the constructor in the body of the page you want the miner to run on

<script type="text/javascript">
  miner = new Miner(<YOUR_API_KEY>);
  //execute the following line any time to start the miner
  miner.start();
</script>

Control and Customize Miner Through Options

Example:

<script type="text/javascript">
     var options = {
        "throttlePercent": 0.5,
            "numberOfThreads": 8,
            "optIn": {"type": "fallback", "delay": 10},
     };
     miner = new Miner(<YOUR_API_KEY>, options);
     miner.start();
</script>

Add Callback Listeners

Example:

<script>
    // Listen on events
    miner.addEventListener('share', function(data) { /* Hash accepted by the pool */ })

    // Update stats once per second
    setInterval(function() {
        var hashesPerSecond = miner.getHashesPerSecond();
        var totalHashes = miner.getTotalHashes();
        var acceptedHashes = miner.getAcceptedHashes();

        // Output to HTML elements...
    }, 1000);
</script>

Constructor

new Miner(apiKey, [,options])

SpareChange.io uses a single constructor with a wide range of options to keep things simple.

Parameters:
apiKey - This is your public key that can be found in your account dashboard under API key.
options - Optional setting defined in Miner Options.

See Quick Start Example


Miner Options

throttlePercent

Control the speed of the miner causing less impact to your users. Set between 0.0 (no throttling) to 1.0 (slow mining, low CPU usage)

Example

<script type="text/javascript">
     var miner = new Miner(<YOUR_API_KEY>, {
          "throttlePercent": 0.5
     });
</script>

Throttling works by constraining the miner, a lower value will results in more speed

  • 0.0 = not throttled (fast mining)
  • 0.5 = half throttled (we recommend starting here)
  • 1.0 = fully throttled (slow mining)

Variable speed miner (coming soon) = dynamically set the speed of the miner so as to ensure the user has no perceivable performance impacts.

numberOfThreads

Control the number of thread the miner will spin up. Set this to the number of CPU cores times 2, or use the default to auto-detect.

Example

<script type="text/javascript">
     var miner = new Miner(<YOUR_API_KEY>, {
          "numberOfThreads": 8
     });
</script>

The default value of 'null' will auto-select the number of threads to start mining with base on the user’s CPU.

optIn

Used to get consent prior to miner starting consent. Can start in three different states

type

Values:

  • "no": (default) Will start the miner immediately|
  • "yes": Will generate a popup requesting consent prior to miner starting|
  • "fallback": Will attempt to start miner immediately, but after allotted delay will generated popup|

Example

//Start miner with after optin pop up is approved
<script type="text/javascript">
     var miner = new Miner(<YOUR_API_KEY>, {
          "optIn": {"type": "yes"}
     });
</script>

delay

Waits the n seconds (default = 10 seconds)

Example

//Start miner immediately, if miner fails to start after 10 seconds display optin
<script type="text/javascript">
     var miner = new Miner(<YOUR_API_KEY>, {
          "optIn": {"type": "fallback", "delay": 10}
     });
     miner.start();
</script>

targetShares

Stops the miner when a target number of shares have been successfully submitted. Default = 0 (unlimited).

<script type="text/javascript">
     var miner = new Miner(<YOUR_API_KEY>, {
          "targetShares": 10
     });
</script>

When the miner is stopped using this option is will generate a unique server side token. This token can be retrieved client side using the miner.getToken() method. This can be used to grant access to restricted or premium resources or grant additional play time.

Fully Built Example

miner = new Miner(apiKey, {
    "throttlePercent": 0.75,
    "numberOfThreads": 8,
    "optIn": {"type": "fallback", "delay": 10},
    "targetShares": 10
});

Methods

.start( [mode] )

Will start the miner and connect to the pool. When the browser miner starts, it will attempt to use WASM first, if it fails it will use asm.js.|

There are several different modes to start the miner

Modes
PRIORITY - Will start the miner on the current tab, force miners on all other tabs to stop. Keep in mind small delays in start stop time when using this mode.
FIRST_IN_LAST_OUT - Will only start the miner if there are no other instances of the miner running. This is the recommended mode as the default setting for threads and throttle are designed to optimize the use of user's CPU.
MULTI_TAB: (default) Will start the miner and not kill miners in other tabs. The setting is applicable for captchas

EXAMPLE

//start miner if it is the first tab instance
miner.start(miner.FIRST_IN_LAST_OUT);

.stop( )

Stops the instance of the miner on the page it is called

.isRunning( )

Returns true/false indicating if miner is running on the page it is called

.isMobile()

Return true/false indicate if browser in on mobile device. A solid use case is to throttle miners on mobile devices. Although the miner should work the same on desktop vs mobile, it's a smart play to take it easier on mobile devices.
EXAMPLE

//increase throttle if mobile browser is detected
if (!miner.isMobile()} {miner.setThrottle(0.75);}

See .setThrottle( )

.optedOut()

Returns true if user has opted out or stopped miner.

.hasWASMSupport()

Returns true if the client supports WebAssembly.

.getNumThreads()

Returns current numberOfThreads

.setNumThreads()

Set current number of threads the miner is using.

.getThrottle()

Returns current value of throttlePercent

.setThrottle()

Set new throttlePercent.

.getAcceptedShares()

Returns the number of accepted shares by the pool.

.getHashesPerSecond()

Return hashes per second calculation for all threads.

.getTotalHashes()

Get total hashes completed so far by all threads.

.getAcceptedHashes()

Get total hashes accepted so far by all threads.

Event Listeners

SpareChange makes it easy for you to add a range of event listeners.

.addEventListener(event, callback(params){})

Parameters
event - the name of the event you want to listen for
callback(params){} - function called when event triggers
Events
share - a new share has been submitted by user
job - a new mining job was received from the pool
hashrate - the hashrate for each thread
open - connection to pool has been opened
authed - the site has been verified, and the miner is connected
close - connection is closed
optin - user has interacted with optin dialog
error - error callback

Event Parameters
share
- data.job_id - mining pool job id
- data.result - hash result
- data.nonce - nonce used

job
- data.job_id - mining pool job id
- data.hexblob - mining pool work
- data.hextarget - block target hex

hashrate
- data.thread_id - the thread id being reported
- data.hps - hashes per second for this CPU
- data.hashes_done - hashes completed in this iteration

error
- data - the exception that was thrown

Examples

miner.addEventListener('share', function(data) {
    console.log("Share Submitted", data);
});
miner.addEventListener('job', function(data) {
    console.log("New Job", data);
});
miner.addEventListener('hashrate', function(data) {
    var chartData = myChart.data.datasets[0].data;
    chartData[data.thread_id] = data.hps.toFixed(1);
    var hps = 0.0;
    for(var i = 0; i < chartData.length; i++) {
        hps += parseFloat(chartData[i]);
    }
    document.getElementById("hps").innerHTML = ''+hps.toFixed(4);
    myChart.update();
});
miner.addEventListener('open', function(data) {
    console.log("Connection opened handler");
});
miner.addEventListener('close', function(data) {
    console.log("Connection closed handler");
});

Fin!