File Coverage

blib/lib/Finance/Bitcoin/API.pm
Criterion Covered Total %
statement 14 25 56.0
branch 0 4 0.0
condition 0 9 0.0
subroutine 5 6 83.3
pod 1 1 100.0
total 20 45 44.4


line stmt bran cond sub pod time code
1             package Finance::Bitcoin::API;
2              
3             BEGIN {
4 1     1   2 $Finance::Bitcoin::API::AUTHORITY = 'cpan:TOBYINK';
5 1         22 $Finance::Bitcoin::API::VERSION = '0.902';
6             }
7              
8 1     1   15 use 5.010;
  1         3  
  1         36  
9 1     1   1008 use Moo;
  1         25738  
  1         6  
10 1     1   2685 use JSON::RPC::Legacy::Client;
  1         96051  
  1         39  
11 1     1   12 use Scalar::Util qw( blessed );
  1         3  
  1         547  
12              
13             has endpoint => (is => "rw", default => sub { "http://127.0.0.1:8332/" });
14             has jsonrpc => (is => "lazy", default => sub { "JSON::RPC::Legacy::Client"->new });
15             has error => (is => "rwp");
16              
17             sub call
18             {
19 0     0 1   my $self = shift;
20 0           my ($method, @params) = @_;
21            
22 0           $self->_set_error(undef);
23            
24 0           my $return = $self->jsonrpc->call($self->endpoint, {
25             method => $method,
26             params => \@params,
27             });
28            
29 0 0 0       if (blessed $return and $return->can('is_success') and $return->is_success)
    0 0        
      0        
30             {
31 0           $self->_set_error(undef);
32 0           return $return->result;
33             }
34             elsif (blessed $return and $return->can('error_message'))
35             {
36 0           $self->_set_error($return->error_message);
37 0           return;
38             }
39             else
40             {
41 0           $self->_set_error(sprintf('HTTP %s', $self->jsonrpc->status_line));
42 0           return;
43             }
44             }
45              
46             1;
47              
48             __END__
49              
50             =head1 NAME
51              
52             Finance::Bitcoin::API - wrapper for the Bitcoin JSON-RPC API
53              
54             =head1 SYNOPSIS
55              
56             use Finance::Bitcoin::API;
57            
58             my $uri = 'http://user:password@127.0.0.1:8332/';
59             my $api = Finance::Bitcoin::API->new( endpoint => $uri );
60             my $balance = $api->call('getbalance');
61             print $balance;
62              
63             =head1 DESCRIPTION
64              
65             This module provides a low-level API for accessing a running
66             Bitcoin instance.
67              
68             =over 4
69              
70             =item C<< new( %args ) >>
71              
72             Constructor. %args is a hash of named arguments. You need to provide the
73             'endpoint' URL as an argument.
74              
75             =item C<< call( $method, @params ) >>
76              
77             Call a method. If successful returns the result; otherwise returns undef.
78              
79             B<< Caveat: >> The protocol used to communicate with the Bitcoin daemon
80             is JSON-RPC based. JSON differentiates between numbers and strings:
81             C<< "1" >> and C<< 1 >> are considered to be different values. Perl
82             (mostly) does not. Thus the L<JSON> module often needs to guess whether
83             a parameter (i.e. an item in C<< @params >>) is supposed to be a number
84             or a string. If it guesses incorrectly, this may result in the wrong
85             JSON getting sent to the Bitcoin daemon, and the daemon thus returning
86             an error. To persuade L<JSON> to encode a value as a number, add zero to
87             it; to persuade L<JSON> to encode a value as a string, interpolate it.
88             For example:
89              
90             $api->call(
91             "sendfrom",
92             "$from_adr", # Str
93             "$to_adr", # Str
94             $btc + 0, # Num
95             6, # literal: perl already knows this is a Num
96             );
97              
98             =item C<< endpoint >>
99              
100             Get/set the endpoint URL.
101              
102             =item C<< jsonrpc >>
103              
104             Retrieve a reference to the L<JSON::RPC::Legacy::Client> object being used. In particular
105             C<< $api->jsonrpc->ua >> can be useful if you need to alter timeouts or HTTP proxy
106             settings.
107              
108             =item C<< error >>
109              
110             Returns the error message (if any) that resulted from the last C<call>.
111              
112             =back
113              
114             =head1 BUGS
115              
116             Please report any bugs to L<http://rt.cpan.org/>.
117              
118             =head1 SEE ALSO
119              
120             L<Finance::Bitcoin>.
121              
122             L<http://www.bitcoin.org/>.
123              
124             =head1 AUTHOR
125              
126             Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
127              
128             =head1 COPYRIGHT
129              
130             Copyright 2010, 2011, 2013, 2014 Toby Inkster
131              
132             This library is free software; you can redistribute it and/or modify it
133             under the same terms as Perl itself.
134              
135             =head1 DISCLAIMER OF WARRANTIES
136              
137             THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
138             WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
139             MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.