NAME

Finance::FXCM::Simple - A synchronous wrapper to the FXCM ForexConnect API which is simple to use.

SYNOPSIS

        my $ff = Finance::FXCM::Simple->new(
                        $ENV{FXCM_USER},
                        $ENV{FXCM_PASSWORD},
                        "Demo",
                        "http://www.fxcorporate.com/Hosts.jsp");

        # Don't receive data updates to EUR/CAD
        $ff->setSubscriptionStatus('EUR/CAD', 'D');

        # Receive data updates to EUR/USD
        $ff->setSubscriptionStatus('EUR/USD', 'T');

        # Hash of data subscription status keyed on instrument
        my $offers_hash = $ff->getOffersHash();

        # Get current ask price for instrument
        $ff->getAsk("EUR/USD");

        # Get current bid price for instrument
        $ff->getBid("EUR/USD");

        # Get current account balance
        $ff->getBalance();

        # The minimum size that can be traded in instrument
        $ff->getBaseUnitSize("XAU/USD");

        # Open long position in instrument at current market price
        $ff->openMarket("EUR/USD", "B", 10000);

        # Open short position in instrument at current market price
        $ff->openMarket("EUR/GBP", "S", 10000);

        # Get list of open positions
        my $trades = $ff->getTrades();
        foreach my $trade(@$trades) {
            # Close existing open position at current market price
            $ff->closeMarket($trade->{id}, $trade->{size});
        }

        # Fetch 100 bars of 5 minute historical data for instrument EUR/USD and save to /tmp/EURUSD
        $ff->saveHistoricalDataToFile("/tmp/EURUSD", "EUR/USD", "m5", 100);

DESCRIPTION

Simple wrapper to FXCM's ForexConnect API, allows you to open/close/query positions in both real or demo FXCM trading accounts, as well as download historical price data for instruments supported by FXCM.

COMPILING

This module depends on FXCM's ForexConnect library which is available in binary form only.

By default, only a small subset of tests run. To run the full test suite, you can optionally create a FXCM demo account.

    curl http://fxcodebase.com/bin/forexconnect/1.3.2/ForexConnectAPI-1.3.2-Linux-x86_64.tar.gz | tar zxf - -C ~
    sudo cp -R ~/ForexConnectAPI-1.3.2-Linux-x86_64/include/* /usr/include/.
    sudo cp -R ~/ForexConnectAPI-1.3.2-Linux-x86_64/lib/* /usr/lib64/.

    FXCONNECT_HOME=~/ForexConnectAPI-1.3.2-Linux-x86_64
    FXCM_USER=DEMO_USERNAME # Optional, only required to run full test suite
    FXCM_PASSWORD=DEMO_PWD  # Optional, only required to run full test suite
    perl Makefile.PL
    make
    make test
    sudo make install

METHODS

new($username, $password, $type, $url)
$username

Your FXCM account username

$password

Your FXCM account password

$type

The account type the login credentials apply to. Either 'Demo' or 'Real'.

$url

The url to connect to, typically this will be 'http://www.fxcorporate.com/Hosts.jsp'

getAsk($instrument)

Get current ask price of instrument. This is the price you can buy at. Subscription status must be set, see "setSubscriptionStatus($instrument, $status)"

$instrument

The instrument to fetch ask price for.

getBid($instrument)

Get current bid price of instrument. This is the price you can sell at. Subscription status must be set, see "setSubscriptionStatus($instrument, $status)"

$instrument

The instrument to fetch bid price for.

openMarket($instrument, $direction, amount)

Opens a position at current market price.

$instrument

The instrument to open a market position in.

$direction

Use 'B' for Buy (long) or 'S' for Sell (short).

$amount

An integer representing the size of the position being opened. This must be a multiple of getBaseUnitSize

closeMarket($tradeID, $amount)

Close an existing position at current market prices

$tradeID

Unique identifier representing a trade. This can be obtained by calling getTrades.

$amount

An integer representing the size of the position to be closed. This can either be partial or the full position. Must be a multiple of getBaseUnitSize.

getTrades()

Returns a reference to a list of currently opened trades. Each element in the list is a reference to an hash with the following keys:

direction

Either "long" or "short".

symbol
openPrice
openDate
pl

Current profit/loss of the position, expressed in the account base currency.

id

Unique trade identifier. This is necessary to close the position with closeMarket.

size
getBalance()

Current account balance, expressed in the account base currency.

getBaseUnitSize($instrument)

Returns an integer representing the base position size for $instrument. Positions opened in $instrument must have a size which is a multiple of this value.

$instrument

The instrument to fetch base unit size for.

saveHistoricalDataToFile($filename, $instrument, $tf, $numberOfItems)

Fetches historical data for instrument in a given timeframe and saves it to a file on disk.

$filename

Filename where to save data to.

$instrument

Instrument for which to fetch data.

$tf

Timeframe which to fetch data in. This can be one of:

m1

One minute

m5

Five minutes

m15

Fifteen minutes

m30

Thirty minutes

H1

Hourly

D1

Daily

W1

Weekly

$numberOfItems

An integer representing number of items of historical data to download.

getOffersHash()

Returns a reference to an hash where the key is an instrument code and the value is that code's current subscription status. You can only call getBid and getAsk on currently subscribed instruments.

setSubscriptionStatus($instrument, $status)
$instrument

Instrument to set subscription status for

$status

Value indicating wether subscription should be set or unset. Use 'T' to subscribe, 'D' to ubsubscribe.

SOURCE CODE

https://github.com/joaocosta/Finance-FXCM-Simple

CI

https://travis-ci.org/joaocosta/Finance-FXCM-Simple

AUTHOR

João Costa <joaocosta@zonalivre.org>

COPYRIGHT AND LICENSE

 This software is Copyright (c) 2016 by João Costa.

 This is free software, licensed under:

   The MIT (X11) License

SEE ALSO

ForexConnect API documentation