=begin pod

=head1 NAME

WebService::Justcoin - Interface to Justcoin Bitcoin marketplace.

=head1 SYNOPSIS

        use WebService::Justcoin;

        my $j = WebService::Justcoin.new(:url-get(&ugly-curl-get)); 
        
        say $j.markets(id => "BTCNOK");
        # ("id" => "BTCNOK", "last" => "2800.000", "high" => "2950.123", "low" => "2751.020", "bid" => "2800.000", "ask" => "2867.446", "volume" => "21.00230", "scale" => 3).hash

        $j = WebService::Justcoin.new(
                :api-keys("my-api-key"),
                :url-get(&ugly-curl-get)); 
        say $j.orders();
        # ({"id" => 2524406, "market" => "BTCNOK", "type" => "bid", "price" => "2833.723", "amount" => "0.00352", "remaining" => "0.00352", "matched" => "0.00000", "cancelled" => "0.00000", "createdAt" => DateTime.new(year => 2014, month => 4, day => 8, hour => 9, minute => 51, second => 10)},).list}

=head1 DESCRIPTION

Justcoin is a Norwegian Bitcoin marketplace. C<WebService::Justcoin> implements the documented parts[1] of its API and some of its undocumented parts[2].

This module is alpha quality. Use this module at own risk!

[1] Justcoin API documentation: http://docs.justcoin.apiary.io/
[2] Justcoin API source code: https://github.com/justcoin/snow/tree/master/api/v1

Perl6 is awesome, and bitcoins are neat too. This module let's you combine the two worlds. I, the author, use this module to buy a small amount of BTC every day in a cron job.

=head1 METHODS

I recommend taking a look at the unittests to see how to use the API, and what return values to expect. There are also samples in /samples

=head2 new(:api-key, :url-get, :url-post, :url-delete)

The constructor. API key is required for most methods (C<markets()> is one exception). Your API key can be found on the justcoin.com website under your account settings.

Since Perl6 does not at the moment (AFAIK) have a module for accessing https urls, you will need to provide them yourself as url-get, url-post and url-delete parameters. This module does however provide you with an ugly implementation of those that use the C<curl> executable. Here is how to use them:

        my $j = WebService::Justcoin.new(
                        :url-get(&ugly-curl-get),
                        :url-post(&ugly-curl-post),
                        :url-delete(&ugly-curl-delete),
                        :api-key("your api key"));

=head2 markets(:$id?)

Get current market summary. If you provide market ID, you will only get summary for that market.

=head2 market-depth(Str $market-id)

Market depth for given market (all asks and bids).

=head2 currencies
Currencies supported by Justcoin.

=head3 orders()
List of your current (unmatched) orders.

=head3 create-orders(:market, :amount, :type, :price?)
Create a C<:type> order in C<:market> for C<:amount> of currency at C<:price>.

C<type> can be either "ask" or "bid". C<price> is optional and your order will be placed as market order if not provided.

=head3 cancel-order(Int $id)
Cancel order with given ID.

=head3 balances(Str :$currency?)
Lists your balances for all currencies.

If C<currency> is provided, only your balance for that currency will be returned.

=head3 withdraws()
Lists all your withdraws.

=head3 create-withdraw-btc(Str :$address, Rat :$amount)
Withdraw C<$amount> of BTC to address C<$address>.