Bittylicious API

List trades

• URL is https://bittylicious.com/api/v1/list
• Required input data (POST fields):
  • api_key
  • offerID
  • active (true to list only active trades, false to list all trades)
• Returned data (JSON structure)
  • success (true or false)
  • trades array:
    • status (trade status, e.g. PAID)
    • reference (trade ID)
    • amountCurrency (e.g. 10.30)
    • currency (e.g. GBP)
    • amountBTC
    • statusExpiry (MySQL DATETIME of the expiry of this status)

Complete trade

• URL is https://bittylicious.com/api/v1/complete
• Required input data (POST fields):
  • api_key
  • offerID
  • reference (trade reference)
  • action = 'complete'
  • signature (see below)
• Optional input data (POST fields):
  • transCommentaryFull (full transaction commentary)
  • transType (transaction type, e.g. Faster Payments In)
  • transReference (transaction reference, usually matches reference above)
  • transOtherParty (other party in this transaction, usually the name of the sender)
• Returned data (JSON structure)
  • success (true or false)

Signature

In order to confirm that a trade should be paid out, the bank account client needs to send the signed output of a message to Bittylicious. The part of Bittylicious that actually sends out the coins will then verify this against the public key assigned to this offer.

The message that needs to be signed takes the JSON form and is encoded using sha512:

• version = 1
• reference = trade reference
• btcaddress = BTC address coins will be sent to
• updateID = update identifier provided in response to the Trade List API call plus 1

For example, the following could be signed:

{"version":1,"reference":"BJU02PF7S","btcaddress":"1B4oWw64wPIW9jf01oaabNoK67qxYeNJg3","updateID":3}

PHP code to do this is as follows:

 <?php
       if (!isset($argv[3]))
       {
               echo "Syntax: {$argv[0]} TradeReference BTCAddress UpdateID [debug]\n";
               die();
       }
 
       // Build data
       $tradeID = $argv[1];
       $btcAddress = $argv[2];
       // Plus one because this update increments the updateID anyway
       $updateID = $argv[3] + 1;
       $data = json_encode(array('version' => (int)1, 'reference' => $tradeID, 'btcaddress' => $btcAddress, 'updateID' => (int)$updateID));
 
       if (isset($argv[4]) && $argv[4] == 'debug')
               echo "Data is {$data}\n";
 
       // Get private key
       $fp = fopen("private.key", "r");
       if (!$fp)
               die("Could not open private key private.key\n");
       $priv_key = fread($fp, 8192);
       fclose($fp);
       $pkeyid = openssl_get_privatekey($priv_key);
       if (!$pkeyid)
               die("Private key not valid");
 
       // compute signature
       openssl_sign($data, $signature, $pkeyid, 'sha512');
 
       // free the key from memory
       openssl_free_key($pkeyid);
 
       echo base64_encode($signature) . "\n";
 ?>