NAV
php

Bitsplit API

Welcome to the Bitsplit API. Bitsplit is a cryptocurrency mass token distribution and payment routing service. Currently supporting Counterparty tokens only.

Visit bitsplit.tokenly.com and go to your dashboard to obtain an API key pair.

<?php
use Tokenly/BitsplitClient/Client as BitsplitClient;

$base_url = 'https://bitsplit.tokenly.com';
$key = BITSPLIT_KEY;
$secret = BITSPLIT_SECRET;

$client = new BitsplitClient($base_url, $key, $secret);

If you are using PHP, we recommend you use the BitsplitClient\Client class for easier API interaction.

Download from github here or include it in your Composer compatible project using
composer require tokenly/bitsplit-client.

Authentication

<?php

$params = array(); //your input data
$params['key'] = BITSPLIT_KEY;
$query = http_build_query($params);
$request_hash = hash('sha256', $query.BITSPLIT_SECRET);

$url = 'https://bitsplit.tokenly.com/api/v1/endpoint?key='.BITSPLIT_KEY.'&request_hash='.$request_hash;

//make appropriate HTTP request etc.

All API methods require a Client Key for access, and some methods also require signing with the API Secret.

For methods requiring Client Key, include the query parameter key=<MY CLIENT KEY> in your request.

For methods requiring the API Secret, the request_hash query parameter must be set.

To obtain the value for the request_hash parameter, create a hash using the following formula:

$request_hash = hash('sha256', $input_string.$api_secret);

Where $input_string is the combined http query string of endpoint query string + any json input, excluding request_hash itself.

Distributions

Use these methods to distribute tokens to many addresses and manage your distributions.

Create Distribution

This method will initiate a new token distribution to a desired set of addresses. A deposit address will be generated and the system will wait for the tokens to arrive before continuing to next stage.

Must send to at least 3 or more unique addresses.

HTTP Method
POST https://bitsplit.tokenly.com/api/v1/distribute/create

Authentication: key + request_hash

<?php

$asset = 'LTBCOIN';
$send_list = array();
$send_list['1AnxkFGEwjN4XL4ZWpbQ36wubFcxnwTU5K'] = 100000;
$send_list['1CTKPjRMiMAcyywy1KRs9JZShWiRUudqnS '] = 100000;
$send_list['19ADjZ2CUKP2kkh2qzmpGd5CYAMJNQ896V '] = 250000;
$use_fuel = true;
$label = 'My test distribution';

$client = new BitsplitClient(BITSPLIT_HOST, BITSPLIT_KEY, BITSPLIT_SECRET);
$create = $client->createDistribution($asset, $send_list, $use_fuel, array('label' => $label));

if($create){
    //success
    $id = $create['id'];
    $address = $create['deposit_address'];
}

Request Parameters

Parameter Type Description
asset string Token to distribute - required
address_list array List of addresses and amounts to send - required
use_fuel boolean Automatically source bitcoin fees from fuel address
value_type string fixed or percent
asset_total float Total amount to split if using percent value_type
label string Reference label, shows up on notifications
webhook string Endpoint to receive webhook notifications.
hold boolean Start the distribution in hold mode.

Returns: result (Distribution Object)

List Distributions

Obtain a list of distributions made by your account, ordered newest to oldest.

<?php

$list = $client->listDistributions();
if($list){
    foreach($list as $distro){
        //do something
    }
}


HTTP Method
GET https://bitsplit.tokenly.com/api/v1/distribute

Authentication: key

Returns: result (array of Distribution List Objects)

Get Distribution

Get details on an individual distribution.

<?php

$address = '1FhemSGz1FkRmAs8QhYTaDUztpMv16ki9D';
$get = $client->getDistributions($address);


HTTP Method
GET https://bitsplit.tokenly.com/api/v1/distribute/{id}

Authentication: key

URL Parameters:

Parameter Description
id distribution ID or deposit address

Returns: result (Distribution Object)

Update Distribution

Update (limited) details on a distribution.

HTTP Method
PATCH https://bitsplit.tokenly.com/api/v1/distribute/{id}

Authentication: key + request_hash

<?php

//put distribution on hold
$address = '1FhemSGz1FkRmAs8QhYTaDUztpMv16ki9D';
$hold = 1;
$params = array('hold' => $hold);
$update = $client->updateDistribution($address, $params);

URL Parameters:

Parameter Description
id distribution ID or deposit address

Request Parameters:

Parameter Type Description
label string Reference label, shows up on notifications
webhook string Endpoint to receive webhook notifications.
hold boolean Toggle hold mode on distribution

Returns: result (Distribution Object)

Delete Distribution

Removes distribution from the system.

Cannot delete non-completed distributions which have received funds and are in progress.

HTTP Method
DELETE https://bitsplit.tokenly.com/api/v1/distribute/{id}

<?php

$address = '1FhemSGz1FkRmAs8QhYTaDUztpMv16ki9D';
$delete = $client->deleteDistribution($address);
if($delete){
    //success
}
else{
    //failure
}

Authentication: key + request_hash

URL Parameters:

Parameter Description
id distribution ID or deposit address

Returns: result (boolean)

Distribution Object

This is the response object containing individual distribution details.

{
  "result": {
    "id": '522124c8-0d4d-400e-aaaf-78a7f2c6527e',
    "label": "my test distribution",
    "created_at": "2016-06-09 08:21:26",
    "updated_at": "2016-06-09 08:21:26",
    "stage": 1,
    "stage_message": null,
    "complete": 0,
    "deposit_address": "1FhemSGz1FkRmAs8QhYTaDUztpMv16ki9D",
    "network": "btc",
    "asset": "LTBCOIN",
    "asset_total": 554533140000,
    "fee_total": 77720,
    "asset_received": 0,
    "fee_received": 0,
    "hold": 0,
    "use_fuel": 1,
    "webhook": null,
    "asset_totalFloat": 5545.3314,
    "fee_totalFloat": 0.0007772,
    "asset_receivedFloat": 0,
    "fee_receivedFloat": 0,
    "stage_name": "CollectTokens",
    "address_list": [
      {
        "destination": "1AnxkFGEwjN4XL4ZWpbQ36wubFcxnwTU5K",
        "quantity": 2000000000,
        "utxo": null,
        "txid": null,
        "confirmed": 0,
        "updated_at": "2016-06-09 08:21:26",
        "quantity_float": 20
      },
      {
        "destination": "1CTKPjRMiMAcyywy1KRs9JZShWiRUudqnS",
        "quantity": 2523140000,
        "utxo": null,
        "txid": null,
        "confirmed": 0,
        "updated_at": "2016-06-09 08:21:26",
        "quantity_float": 25.2314
      },
      {
        "destination": "19ADjZ2CUKP2kkh2qzmpGd5CYAMJNQ896V",
        "quantity": 550010000000,
        "utxo": null,
        "txid": null,
        "confirmed": 0,
        "updated_at": "2016-06-09 08:21:26",
        "quantity_float": 5500.1
      }
    ]
  }
}

Response variables

Variable Type Description
id string Distribution Unique ID
label string Reference label
created_at timestamp Date initiated
updated_at timestamp Last updated
stage integer Current stage ID
stage_message integer Extra status message from stage
complete integer If distribution complete or not
deposit_address string Bitcoin address
network string Cryptocurrency network
asset integer Token name
asset_total integer Total required amount of tokens to send, in satoshis
fee_total integer BTC fee required, in satoshis
asset_received integer Tokens received, in satoshis
fee_received integer BTC fees received, in satoshis
hold integer If distro on hold
use_fuel integer Automatically source fees from fuel address
webhook integer Notify URL with updates
asset_totalFloat float Total tokens to send as a more human readable value
fee_totalFloat float Fee total as a float
asset_receivedFloat float Tokens received as a float
fee_receivedFloat float Fee received as a float
stage_name string Code name for current stage ID
address_list array Array of Distribution TX Objects

Distribution List Object

This is the same as Distribution Object except without the address_list response variable.

Distribution TX Object

Data shown in the address_list response variable from the Distribution Object.

      {
        "destination": "19ADjZ2CUKP2kkh2qzmpGd5CYAMJNQ896V",
        "quantity": 550010000000,
        "utxo": "2c330171bdf32d60c6aaa98493abb084c799887df8fb507908fbb231de8323c9:0",
        "txid": null,
        "confirmed": 0,
        "updated_at": "2016-06-09 08:21:26",
        "quantity_float": 5500.1
      }

Response variables

Variable Type Description
destination string Destination address
quantity integer Quantity to send, in satoshis
utxo string UTXOs to use, in format <txid>:<n> (comma separated)
txid string TX ID, if sent
confirmed integer If confirmed on blockchain
updated_at timestamp Last updated
quantity_float float Quantity to send as a human readable float

Distribution Stages

{
    "0": "Initialize",
    "1": "CollectTokens",
    "2": "CollectFuel",
    "3": "PrimeUtxos",
    "4": "PrepareTxs",
    "5": "BroadcastTxs",
    "6": "ConfirmBroadcasts",
    "7": "ConsolidateTxs",
    "8": "CompleteCleanup"
}


Each distribution goes through 9 stages from start to finish, distributing your tokens as efficiently as possible.

Details on each stage listed below:

Name ID Description
Initialize 0 Initial setup and deposit address generated
CollectTokens 1 Waits for asset_total to arrive
CollectFuel 2 Waits for BTC fees to arrive and/or auto sends fees from fuel address
PrimeUtxos 3 Prepares UTXO set for all required transactions
PrepareTxs 4 Assigns a confirmed UTXO to each destination address
BroadcastTxs 5 Constructs and broadcasts all transactions to network
ConfirmBroadcasts 6 Waits until all broadcasts have reached at least 1 confirmation
ConsolidateTxs 7 Cleans up UTXO set if needed
CompleteCleanup 8 Marks complete and forwards leftover change to service as a fee

Distribution Webhook Object

When using the webhook field in your distributions, the endpoint provided will be queried during each stage of the distribution process, and a final time on completion.

Example webhook payload data:

{
  "id": "faacb1a4-86e5-45d4-ae66-29ba7f38543b",
  "time": "2016-10-28T18:43:16Z",
  "attempt": 1,
  "apiToken": "Tfje2CDQNzyckWKM",
  "signature": "0f6ecaecaa304319cdbeace4dc34d11a1a98791c8aaa34914b6a3f0f9d333964",
  "payload": "{\"event\":\"update\",\"notificationId\":\"faacb1a4-86e5-45d4-ae66-29ba7f38543b\",\"distributionId\":\"760a99d5-2a3b-4fa7-88ab-5ad1f31ce514\",\"label\":\"test distro webhooks\",\"createdAt\":{\"date\":\"2016-10-28 18:41:59\",\"timezone_type\":3,\"timezone\":\"UTC\"},\"updatedAt\":{\"date\":\"2016-10-28 18:43:16\",\"timezone_type\":3,\"timezone\":\"UTC\"},\"stage\":1,\"stageMessage\":\"receiving\",\"complete\":0,\"depositAddress\":\"1HrvqVSJMfZJ1WU2JZfpYFeJE6kJcFQaMu\",\"network\":\"btc\",\"asset\":\"LTBCOIN\",\"assetTotal\":300000000,\"feeTotal\":82220,\"assetReceived\":0,\"feeReceived\":0,\"hold\":0,\"use_fuel\":1,\"webhook\":\"http:\\\/\\\/earnfreebitcoins.com\\\/test-bitsplit-webhook.php\",\"assetTotalFloat\":3,\"feeTotalFloat\":0.0008222,\"assetReceivedFloat\":0,\"feeReceivedFloat\":0,\"stageName\":\"CollectTokens\"}"
}

Notification variables

Variable Type Description
id string Unique ID for this notification
time timestamp Time received
attempt integer How many times this notification has been attempted
apiToken string API client ID that this belongs to
signature string HMAC signature of request using API client secret
payload string JSON encoded string with the actual payload data

Payload variables

Variable Type Description
event string Type of notification, either complete or update
*notificationId string Unique ID of this webhook notification
distributionId string Unique ID of this distribution
label string Distribution label
createdAt timestamp Date distribution created
updatedAt timestamp Time distribution last updated
stage integer Processing stage ID
stageMessage string Status message of current stage, e.g ‘receiving’
depositAddress string Distribution bitcoin address
network string Cryptocurrency network (btc)
asset string Token to distribute
assetTotal integer Total amount of tokens to distribute, in satoshis
feeTotal integer Total BTC fuel cost, in satoshis
assetReceived integer Tokens received, in satoshis
feeReceived integer Fee received, in satoshis
hold boolean True if distribution paused / on hold
use_fuel boolean True if automatically sourcing fuel from account fuel address
webhook string Distribution webhook field
assetTotalFloat float Human readable total token quantity
feeTotalFloat float Human readable total fuel cost
assetReceivedFloat float Human readable tokens received
feeReceivedFloat float Human readable fuel received
stageName string Alias of the current processing stage, e.g 'CollectTokens’

Fuel

Optionally, instead of funding the BTC fees for every distribution seperately, you may deposit BTC into a single fuel address which can then be used to automatically fund future transactions.

This allows you (from a users perspective) to trigger distributions using only one transaction (sending the tokens) instead of two (tokens + fee).
Make sure to set use_fuel to true on your distributions.

Get Fuel Info

<?php
$info = $client->getFuelInfo();
$fuel_address = $info['fuel_address'];
$fuel_balance = $info['fuel_balanceFloat'];

Gets fuel address and balance info.

HTTP Method
GET https://bitsplit.tokenly.com/api/v1/self

Authentication: key

Returns: result (Fuel Info Object)

Fuel Info Object

{
  "result": {
    "fuel_address": "16K4Xh3798pizCJxyY8QY5M4jZjZ6ESuAP",
    "fuel_balance": 2381949,
    "fuel_pending": 0,
    "fuel_spent": 0,
    "fuel_balanceFloat": 0.02381949,
    "fuel_pendingFloat": 0,
    "fuel_spentFloat": 0
  }
}

Response object returned by Get Fuel Info method.

Response variables

Variable Type Description
fuel_address string BTC fuel address
fuel_balance integer Current fuel balance, in satoshis
fuel_pending integer BTC pending confirmation
fuel_spent integer Total BTC fuel spent
fuel_balanceFloat float Balance as a float, human readable
fuel_pendingFloat float Pending as a float
fuel_spentFloat float Spent total as a float
php