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