NAME

Finance::Nadex - Interact with the North American Derivatives Exchange

VERSION

Version 0.07

SYNOPSIS

Easily create orders, cancel orders, retrieve orders and retrieve positions on the North American Derivatives Exchange

    use Finance::Nadex;

    # connects to the live platform when called as Finance::Nadex->new(); as an alternative
    # it is possible to connect to the demo platform with Finance::Nadex->new(platform => 'demo')
    my $client = Finance::Nadex->new();

    # must login to perform any actions, including simply querying market info
    $client->login(username => 'yourusername', password => 'yourpassword');
    
    # get the available balance in the account
    my $balance = $client->balance();
    
    # get a quote for GBP/USD
    my $quote = $client->get_quote('instrument' => 'GBP/USD');

    # $quote may now be (for example), 1.5010
    
    # retrieve the epic (Nadex-assigned contract unique identifier) for the
    # Daily, 3pm, GBP/USD > 1.5120 contract
    my $epic = $client->get_epic( period => 'Daily', market => 'Forex (Binaries)', time => '3pm', instrument => 'GBP/USD', strike => '1.5120');
    
    # suppose $epic now contains 'NB.D.GBP-USD.OPT-23-17-23Jan15.IP';
    # create an order to buy 3 of those contracts for $34.50 each
    my $order_id = $client->create_order( price => '34.50', direction => 'buy', epic => $epic, size => 3 );
    
    # check the status of the order using the order id returned by the exchange;
    # this call will return undef if the order doesn't exist; the order may not exist
    # because the order was rejected by the exchange or because it was filled immediately
    # and therefore is no longer a working order
    my $order = $client->retrieve_order( id => $order_id );
    
    # let's assume the order was created and is still a working (or pending) order;
    # get the details of the order using the accessor methods provided by Finance::Nadex::Order
    print join(" ", $order->direction, $order->size, $order->contract, $order->price), "\n";

    # suppose the order has now been filled; this means we have one open position;
    # get the open positions
    my @positions = $client->retrieve_positions();
    
    # @positions now has 1 element which is a Finance::Nadex::Position; get its details
    print join(" ", $positions[0]->id, $positions[0]->direction(), $positions[0]->size(), $positions[0]->contract(), $positions[0]->price), "\n";
    
    # get the current best bid (the price at which we could sell the contract back immediately)
    my $bid = $positions[0]->bid();
    
    # suppose $bid is now $64.50 (we bought at $34.50, so we have a profit of $30);
    # sell to close the position at $64.50
    my $sell_to_close_order_id = $client->create_order( price => $bid, direction => 'sell', epic => $positions[0]->epic, size => $positions[0]->size() );

    # get all the time series (trading periods for contracts) currently
    # available for GBP/USD binaries; the list of currently available markets
    # can be obtained via a call to get_markets()
    my @series = $client->get_time_series( market => 'Forex (Binaries)', instrument => 'GBP/USD' );
    
    # elements of @series are simply strings, such as '2pm-4pm' or 'Daily (3pm)';
    # suppose one of the elements of series is '8pm-10pm'; get a list of
    # contracts available for trading within that market
    my @contracts = $client->get_contracts( market => 'Forex (Binaries)', instrument => 'GBP/USD', series => 'Daily (3pm)' );
    
    # @contracts now has a list in which each element is a Finance::Nadex::Contract; get
    # the details of the available contracts using the accessors of Finance::Nadex::Contract
    # including the current best bid and offer available on the exchange
    foreach my $contract (@contracts) {
          print join(" ", $contract->epic(), $contract->contract(), $contract->expirydate(), $contract->bid(), $contract->offer());
    }
    

    # cancel any remaining open orders
    $client->cancel_all_orders();

    

SUBROUTINES/METHODS

balance

Retrieves the available account balance

balance()

Returns a number representing the available account balance

cancel_all_orders

Cancels all pending orders

cancel_all_orders()

Returns nothing

cancel_order

Cancels the order with the specified order id

cancel_order( id => 'NZ1234FGQ4AFFOPA12Z' )

Returns the reference id created by the exchange for the cancelled order

create_order

Creates an order on the exchange with the specified parameters

  create_order( price => '34.50', direction => 'buy', epic => 'NB.D.GBP-USD.OPT-23-17-23Jan15.IP', size => 2 )

        price : the amount at which to buy or sell; the decimal portion of the number, if provided, must be .50 or .00 for binaries

        direction : one of 'buy', 'sell', '+', '-'
        
        size : the number of contracts to buy or sell

        epic : the unique identifier for the contract to be bought or sold

Returns: the order id created by the exchange to identify the order

Note: '+' is an alias for 'buy'; '-' is an alias for 'sell'; the get_epic() method can be used to get the identifier for the contract of interest

get_contract

Retrieves the contract specified by an epic

get_contract( epic => 'NB.D.GBP-USD.OPT-23-17-23Jan15.IP' )

   epic : the unique identifier created by the exchange for the contract

Returns a Finance::Nadex::Contract instance for the specified epic

get_contracts

Retrieves all the contracts available for trading within the given time series for the specified market and instrument

get_contracts( market => 'Forex (Binaries)', instrument => 'GBP/USD', series => 'Daily (3pm)' )

        market : the name of the market for which the contracts are to be retrieved
   
        instrument : the name of the instrument within the market for which contracts are to be retrieved; the 
                instrument specified must be one of the instruments currently available for trading on the exchange
                for the provided market; the list of valid instruments can be obtained via get_market_instruments()
                

Returns a list in which each element is a Finance::Nadex::Contract instance for each contract in the specified time series

get_epic

Retrieves the epic(unique identifier) for a contract with the specified parameters

  get_epic(period => 'daily', strike => '1.5080', time => '3pm', instrument => 'GBP/USD', market => 'Forex (Binaries)')

        retrieves the epic with the specified parameters
        
        period : specifies the frequency or period of the contract being searched for; one of 'daily', 'intraday', 'weekly', or 'event'
   
        time : specifies the time at which the contract being searched for expires (not required when retrieving an event epic)
   
        instrument : the asset type from which the contract being searched for derives value; an index, currency, or commodity
        
        market : the market in which the specified contract exists (e.g. 'Forex (Binaries)', 'Indices (Binaries)'); must be one of markets returned by get_markets()
        
        strike : the level of the underlying asset for the desired contract (e.g. 1.5010)
   

Returns the unique identifier of the contract

get_market_instruments

Retrieves the list of instruments associated with the specified market

get_market_instruments( name => 'Forex (Binaries)' )

        name : the name of the market for which instruments are to be retrieved; this must match one of the names returned by get_markets()
   

Returns a list in which each element is a string containing the name of an instrument available for trading in the markets

get_markets

Retrieves the list of available markets on the exchange; the list of market names returned can be used in a call to get_market_instruments() to get further information about the market

get_markets()

Returns a list in which each element is a string containing the name of a market in which instruments are traded

get_quote

Retrieves the current price level of the instrument specified as reported by the exchange (the Indicative Price)

get_quote( instrument => 'GBP/USD' );

        instrument : the name of the instrument within the market for which a quote is to be retrieved; the 
                instrument specified must be one of the instruments currently available for trading 
                on the exchange for the provided market; the list of valid instruments can be obtained 
                via get_market_instruments()
                

Returns the current price level or undef if it cannot be obtained

get_time_series

Retrieves the contract periods available for trading in the specified market for the given instrument

get_time_series( market => 'Forex (Binaries)', instrument => 'AUD/USD' )

        market : the name of the market for which a time series is to be retrieved
   
        instrument : the name of the instrument within the market for which a time series is to be retrieved; the 
                instrument specified must be one of the instruments currently available for trading on the exchange
                for the provided market; the list of valid instruments can be obtained via get_market_instruments()

In the case of the '5 Minute Binaries' and '20 Minute Binaries' markets, returns a list in which each element is a Finance::Nadex::Contract representing each contract available in the series; for all other markets, returns a string containing the name of a time series for the given market and instrument; a time series designates the period during which the contract is available for trading including the expiration time

login

Submits the specified username and password to the exchange for authorization

login( username => 'someusername', password => 'somepassword' );

        username : the username of the account
   
        password : the password of the account

Returns a true value on successful login; otherwise returns a false value

logged_in

Reports whether login was previously attempted and succeeded

logged_in()

Returns true if login was previously attempted and succeded; otherwise returns false

new

Creates an instance of a Finance::Nadex object

   new()
   

Returns a reference to a Finance::Nadex instance

retrieve_order

Gets the details of the pending order with the specified order id

retrieve_order( id => 'NZ1234FGQ4AFFOPA12Z' )

Returns an instance of Finance::Nadex::Order

retrieve_orders

Gets the details of all pending orders

retrieve_orders()

Returns a list in which each element is a Finance::Nadex::Order

retrieve_position

Retrieves the details of an individual open position

retrieve_position ( id => 'NA12DZ45BNVA12A9BQZ' )

Returns a Finance::Nadex::Position object corresponding to the specified position id

retrieve_positions

Retrieves the details of all the open positions

retrieve_positions()

Returns a list in which each element is a Finance::Nadex::Position

AUTHOR

mhandisi, <mhandisi at cpan.org>

BUGS

Please report any bugs or feature requests to bug-nadex-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Nadex-API. I will be notified, and then you will automatically be notified of progress on your bug as I make changes.

TODO

Add support for watchlists.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Finance::Nadex

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2015 mhandisi.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.