NAME

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

SYNOPSIS

  use Finance::LocalBitcoins::API;

  # all the standard LocalBitcoins API calls...

  my $api = Finance::LocalBitcoins::API->new(token => $token);

  # access public requests...
  my $ticker = $api->ticker; 

  # make private requests...
  my $wallet = $api->wallet;

  # private request with parameters...
  my $withdrawal = $api->withdrawal(amount => $amount, currency => $currency, address => $address, 

  # access the user agent of the last request...
  my $user_agent = $api->user_agent;

  # the is_success() and error() methods are also useful...
  if ($api->is_success) {
      print 'SUCESS';
  }
  else {
      print 'FAIL';
      my $error = $api->error;
  }


  # A more useful example...
  my $api  = Finance::LocalBitcoins::API->new(token => $token);
  my $contacts = $api->get_contacts();

  if ($contacts) {
      printf "You have %d contacts\n", scalar @$contacts;
  }
  else {
      printf "An error occurred: %s\n", $api->error;
  }

DESCRIPTION

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

You create an object like this:

    my $api = Finance::LocalBitcoins::API->new(%params);
    # required param keys: token

The methods you call that match the API spec are:

    $api->orderbook(%params);
    # required: currency

    $api->tradebook(%params);
    # required: currency
    # optional: since

    $api->ticker();
    # a ticker for all currencies

    ...etc...

REQUEST PARAMETERS:

    currency - a string. "CAD", "USD", "GBP", "EUR", etc.

    since - a date in the format 'YYYY-MM-DD'

    ...etc...

METHODS

new()

    my $api = Finance::LocalBitcoins::API->new(token => $token);

Create a new Finance::LocalBitcoins::API object. token is required. These values are provided by LocalBitcoins through their online administration interface.

Other Methods

The methods you will use are discussed in the DESCRIPTION. For details on valid parameter values, please consult the offical LocalBitcoins API documentation.

ATTRIBUTES

token()

These are usually set during object instantiation. But you can set and retrieve them through these attributes. The last set values will always be used in the next action request. These values are obtained from LocalLocalBitcoinsBitcoins through your account.

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 LocalBitcoins requires for that request.

error()

If the request did not work, error() will contain a hash representing the problem. The hash contains the keys: 'type' and 'message'. These are strings. ie:

    print "The error type was: " . $api->error->{type};
    print "The error message was: " . $api->error->{message};

user_agent()

This will contain the user agent of the last request to LocalBitcoins. Through this object, you may access both the HTTP Request and Response. This will allow you to do detailed inspection of exactly what was sent and the raw LocalBitcoins response.

request()

This will contain the Request object of the last action called on the object. It is not a HTTP Request, but rather a config file for the request URL, params and other requirements for each post to localbitcoins. You will find these modules using the naming Finance::LocalBitcoins::API::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 LocalBitcoins 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 $api->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 LocalBitcoins. This means that you provide a word for a 'amount' parameter, and this module will happily send that off to LocalBitcoins for you. In these cases we are allowing LocalBitcoins to decide what is and is not valid input. If the input values are invalid, we expect LocalBitcoins to provide an appropriate response and that is the message we will return to the caller (through $api->error).

This module does not validate the response from LocalBitcoins. In general it will return success when any json response is provided by LocalBitcoins without the 'error' key. The SSL certificate is verified automatically by LWP, so the response you will get is very likely from LocalBitcoins itself. If there is an 'error' key in the json response, then that error is put into the $api->error attribute. If there is an 'error' parsing the response from LocalBitcoins, then the decoding error from json is in the $api->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 LocalBitcoins API documentation: unknown (2014-06-11). contact Cavirtex. This project on Github: https://github.com/peawormsworth/Finance-LocalBitcoins-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::LocalBitcoins::API

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