1package Finance::Bitcoin::API;
2
3BEGIN {
4	$Finance::Bitcoin::API::AUTHORITY = 'cpan:TOBYINK';
5	$Finance::Bitcoin::API::VERSION   = '0.902';
6}
7
8use 5.010;
9use Moo;
10use JSON::RPC::Legacy::Client;
11use Scalar::Util qw( blessed );
12
13has endpoint => (is => "rw",   default => sub { "http://127.0.0.1:8332/" });
14has jsonrpc  => (is => "lazy", default => sub { "JSON::RPC::Legacy::Client"->new });
15has error    => (is => "rwp");
16
17sub call
18{
19	my $self = shift;
20	my ($method, @params) = @_;
21
22	$self->_set_error(undef);
23
24	my $return = $self->jsonrpc->call($self->endpoint, {
25		method    => $method,
26		params    => \@params,
27	});
28
29	if (blessed $return and $return->can('is_success') and $return->is_success)
30	{
31		$self->_set_error(undef);
32		return $return->result;
33	}
34	elsif (blessed $return and $return->can('error_message'))
35	{
36		$self->_set_error($return->error_message);
37		return;
38	}
39	else
40	{
41		$self->_set_error(sprintf('HTTP %s', $self->jsonrpc->status_line));
42		return;
43	}
44}
45
461;
47
48__END__
49
50=head1 NAME
51
52Finance::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
65This module provides a low-level API for accessing a running
66Bitcoin instance.
67
68=over 4
69
70=item C<< new( %args ) >>
71
72Constructor. %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
77Call a method. If successful returns the result; otherwise returns undef.
78
79B<< Caveat: >> The protocol used to communicate with the Bitcoin daemon
80is JSON-RPC based. JSON differentiates between numbers and strings:
81C<< "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
83a parameter (i.e. an item in C<< @params >>) is supposed to be a number
84or a string. If it guesses incorrectly, this may result in the wrong
85JSON getting sent to the Bitcoin daemon, and the daemon thus returning
86an error. To persuade L<JSON> to encode a value as a number, add zero to
87it; to persuade L<JSON> to encode a value as a string, interpolate it.
88For 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
100Get/set the endpoint URL.
101
102=item C<< jsonrpc >>
103
104Retrieve a reference to the L<JSON::RPC::Legacy::Client> object being used. In particular
105C<< $api->jsonrpc->ua >> can be useful if you need to alter timeouts or HTTP proxy
106settings.
107
108=item C<< error >>
109
110Returns the error message (if any) that resulted from the last C<call>.
111
112=back
113
114=head1 BUGS
115
116Please report any bugs to L<http://rt.cpan.org/>.
117
118=head1 SEE ALSO
119
120L<Finance::Bitcoin>.
121
122L<http://www.bitcoin.org/>.
123
124=head1 AUTHOR
125
126Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
127
128=head1 COPYRIGHT
129
130Copyright 2010, 2011, 2013, 2014 Toby Inkster
131
132This library is free software; you can redistribute it and/or modify it
133under the same terms as Perl itself.
134
135=head1 DISCLAIMER OF WARRANTIES
136
137THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
138WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
139MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
140