NAME

Finance::BitStamp::API - Perl extension for handling the BitStamp API and IPN calls.

SYNOPSIS

  use Finance::BitStamp::API;

  # all the standard BitStamp API calls...

  my $bitstamp       = Finance::BitStamp::API->new(key => 'abc123');
  my $ticker         = $bitstamp->ticker;
  my $btc_address    = $bitstamp->bitcoin_address;
  my $btc_withdrawal = $bitstamp->bitcoin_withdrawal(amount => '1.0', address => $address);

  # The bitstamp object contains all the request data from the last request...

  my $user_agent = $bitstamp->user_agent;

  if ($bitstamp->success) {
      print 'SUCESS';
  }
  else {
      print 'FAIL';
      my $error = $bitstamp->error;
  }


  # A more useful example...
  my $bitstamp  = Finance::BitStamp::API->new(key => $key, secret => $secret, client_id => $client_id);
  my $buy = $bitstamp->buy(amount => '10.00');

  if ($buy) {
      printf "The BitStamp invoice ID is %s. You can see it here: %s\n", @{$buy}{qw(id url)};
  }
  else {
      printf "An error occurred: %s\n", $bitstamp->error;
  }

DESCRIPTION

This API module provides a quick way to access the BitStamp API from perl without worrying about the connection, authenticatino and an errors in between.

You call these on the API object created like this:

  my $bitstamp = Finance::BitStamp::API->new(key => $key, secret => $secret, client_id => $client_id);

...Where those variable are provided to you by BitStamp through their merchant interface.

The primary PUBLIC methods are:

    ticker(), orderbook(), public_transactions(), conversion_rate()

The primary PRIVATE Information methods are:

    balance(), transactions(), withdrawals(), ripple_address(), bitcoin_address(), orders(), pending_deposits()

The primary PRIVATE Actions methods are:

    cancel(), buy(), sell(), bitcoin_withdrawal(), ripple_withdrawal()

The return value is a hash representing the BitStamp response.

  my $response_as_a_hash = $bitstamp->bitcoin_withdrawal(amount => $amount, address => $address);

The return value will be undefined when an error occurs...

  if ($bitstamp->is_success) {
      # the last primary method call worked!
  }
  else {
      print "There was an error: " . $bitstamp->error;
      # more detail can be found in the bitstamp object using...
      my $ua           = $bitstamp->user_agent;
      my $raw_request  = $bitstamp->http_request;
      my $raw_response = $bitstamp->http_response;
      # further inspection could go here (like dumping the content of the useragent)
  }
  

METHODS

new()

Create a new Finance::BitStamp::API object.

etc()

etc

ATTRIBUTES

is_ready()

Will return true if the request is set and all conditions are met. Will return false if: - the request object does not exist - the request object requires authentication and no key is provided - the request object does not have the manditory parameters set that BitStamp requires for that request.

HOWTO DETECT ERRORS

The design is such that the action methods (invoice_create(), invoice_get(), rates() and ledger()) will return false (0) on error. On success it will contain the hash of information from the BitStamp JSON response. Your code should just check whether or not the response exists to see if it worked. If the response does not exist, then then the module detected a problem. The simplest way to handle this is to print out $bitstamp->error. A coding example is provided above in the SYNOPSIS.

NOTES

This module does not do accessive error checking on the request or the response. It will only check for "required" parameters prior to sending a request to BitStamp. This means that you provide a word for a 'amount' parameter, and this module will happily send that off to BitStamp for you. In these cases we are allowing BitStamp to decide what is and is not valid input. If the input values are invalid, we expect BitStamp to provide an appropriate response and that is the message we will return to the caller (through $bitstamp->error).

This module does not validate the response from BitStamp. In general it will return success when any json response is provided by Bitpay without the 'error' key. The SSL certificate is verified automatically by LWP, so the response you will get is very likely from BitStamp itself. If there is an 'error' key in the json response, then that error is put into the $bitstamp->error attribute. If there is an 'error' parsing the response from BitStamp, then the decoding error from json is in the $bitstamp->error attribute. If there is a network error (not 200), then the error code and $response->error will contain the HTTP Response status_line() (a string response of what went wrong).

SEE ALSO

The BitStamp API documentation: This project on Github: https://github.com/peawormsworth/Finance-BitStamp-API

AUTHOR

Jeff Anderson, <peawormsworth@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2014 by Jeff Anderson

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.

cpanm Finance::BitStamp::API

perl -MCPAN -e shell
install Finance::BitStamp::API