NAME

Finance::Alpaca::Cookbook - Simple Examples to Get You Started

Account Examples

View Account Information

You can see various information about your account, such as the amount of buying power available or whether or not it has a PDT flag.

    my $account = $alpaca->account;
    print 'Account is currently restricted from trading. ' if $account->trading_blocked;
    printf '$%f is available as buying power', $account->buying_power;

View Gain/Loss of Portfolio

You can use the information from the account endpoint to do things like calculating the daily profit or loss of your account.

    my $account        = $alpaca->account;
    my $balance_change = $account->equity - $account->last_equity;
    printf q[Today's portfolio balance change: $%.4f], $balance_change;

Assets Examples

Listed instruments can be gathered en mass or individually.

Get a List of Assets

The assets( ) method will return a list of US equities.

    # Get a list of all active assets.
    my @active_assets = $alpaca->assets( status => 'active' );

    # Filter the assets down to just those that are NASDAQ listed.
    my @nasdaq_assets = grep { $_->exchange eq 'NASDAQ' } @active_assets;

See If a Particular Asset is Tradable on Alpaca

    my $asset = $alpaca->asset('AAPL');
    say $asset->tradable ? 'We can trade AAPL' : 'Asset not found for AAPL';

Check Market Hours

As important as price data, knowing when and if the market is open is basic info to consider.

See if the Market is Open

You can check if the market is open now, or view what times the market will be open or closed on a particular date.

    # Check if the market is open now
    my $clock = $alpaca->clock;
    CORE::say 'The market is ' . ( $clock->is_open ? 'open!' : 'closed.' );

    # Check when the market was open on Dec. 1, 2018
    my $date = Time::Moment->new( year => 2018, month => 12, day => 1 );
    my ($day) = $alpaca->calendar( start => $date, end => $date );
    CORE::say sprintf 'The market opened at %s and closed at %s on %s.', $day->open, $day->close,
        $day->date;

Market Data Examples

Alpaca provides market data from various sources.

Get Historical Price and Volume Data

Using the bars( ) method, you can see what a stock price was at a particular time.

    # Get daily price data for AAPL over the last 5 trading days.
    my %bars = $alpaca->bars(
        symbol    => 'AAPL',
        timeframe => '1Min',
        start     => Time::Moment->now->with_hour(9)->minus_days(7),
        end       => Time::Moment->now->minus_minutes(20),
        limit     => 5
    );

    # See how much AAPL moved in that timeframe
    my $start_price    = $bars{AAPL}[0]->open;
    my $end_price      = $bars{AAPL}[-1]->close;
    my $percent_change = ( $end_price - $start_price ) / $start_price * 100;
    CORE::say sprintf 'AAPL moved %f%% over the last 5 days.', $percent_change;

Order Examples

This section contains examples of some of the things you can do with order objects through our API. For additional help understanding different types of orders and how they behave once they’re placed, please see the order page.

Place New Orders

Submit a market order to buy 1 share of Apple at market price.

    $alpaca->create_order(
        symbol => 'AAPL',
        qty    => 1,
        side   => 'buy',
        type   => 'market',
        time_in_force => 'day'
    );

Submit a limit order to attempt to sell 1 share of AMD at a particular price ($20.50) when the market opens.

    $alpaca->create_order(
        symbol => 'AMD',
        qty    => 1,
        side   => 'sell',
        type   => 'limit',
        time_in_force => 'opg',
        limit_price => 20.50,
    );

Submit Short Orders

Short orders can also be placed for securities which you do not hold an open long position in.

Submit a market order to open a short position of one share.

    $alpaca->create_order(
        symbol => 'TSLA',
        qty    => 1,
        side   => 'sell',
        type   => 'market',
        time_in_force => 'day'
    );

Submit a limit order to attempt to grow our short position.

    # First, get an up-to-date price for our symbol...
    my $symbol = 'TSLA';
    my $time   = Time::Moment->now;
    my %symbol_bars = $alpaca->bars(
        symbol    => $symbol,
        timeframe => '1Min',
        limit     => 1,
        end       => $time,
        start     => $time->minus_minutes(5)
    );

    # Submit an order for one share at that price
    my $order = $alpaca->create_order(
        symbol        => $symbol,
        qty           => 1,
        side          => 'sell',
        type          => 'limit',
        time_in_force => 'day',
        limit_price   => $symbol_bars{$symbol}[0]->close
    );

    # Wait a second for our orders to fill...
    sleep 1;

    # Check on our position
    my $position = $alpaca->position($symbol);
    say 'Short position open for ' . $symbol if $position->qty < 0;

Use Client Order IDs

Client Order IDs can be used to organize and track specific orders in your client program.

    # Submit a market order and assign it a Client Order ID
    $alpaca->create_order(
        symbol          => 'AAPL',
        qty             => 1,
        side            => 'buy',
        type            => 'market',
        time_in_force   => 'day',
        client_order_id => 'my_first_order'
    );

    # Get our order using its Client Order ID
    my $order = $alpaca->order_by_client_id('my_first_order');
    CORE::say 'Got order ' . $order->id;

Submit Bracket Orders

Bracket orders allow you to create a chain of orders that react to execution and stock price. For more details, go to Bracket Order Overview

    my $symbol = 'AAPL';
    my $time   = Time::Moment->now;
    $time = Time::Moment->now->minus_days(1);
    my %symbol_bars = $alpaca->bars(
        symbol    => $symbol,
        timeframe => '1Min',
        limit     => 1,
        end       => $time,
        start     => $time->minus_minutes(5)
    );
    my $symbol_price = $symbol_bars{$symbol}[0]->close;

    # We could buy a position and add a stop-loss and a take-profit of 5 %
    $alpaca->create_order(
        symbol        => $symbol,
        qty           => 1,
        side          => 'buy',
        type          => 'market',
        time_in_force => 'gtc',
        order_class   => 'bracket',
        stop_loss   => { stop_price  => $symbol_price * 0.95, limit_price => $symbol_price * 0.94 },
        take_profit => { limit_price => $symbol_price * 1.05 }
    );

    # We could buy a position and just add a stop loss of 5 % (OTO Orders)
    $alpaca->create_order(
        symbol        => $symbol,
        qty           => 1,
        side          => 'buy',
        type          => 'market',
        time_in_force => 'gtc',
        order_class   => 'oto',
        stop_loss     => { stop_price => $symbol_price * 0.95 }
    );

    # We could split it to 2 orders. first buy a stock,
    # and then add the stop/profit prices (OCO Orders)
    $alpaca->create_order(
        symbol        => $symbol,
        qty           => 1,
        side          => 'buy',
        type          => 'limit',
        time_in_force => 'day',
        limit_price   => $symbol_price
    );

    # wait for it to execute and then
    $alpaca->create_order(
        symbol        => $symbol,
        qty           => 1,
        side          => 'sell',
        type          => 'limit',
        time_in_force => 'gtc',
        order_class   => 'oco',
        stop_loss     => { stop_price  => $symbol_price * 0.95 },
        take_profit   => { limit_price => $symbol_price * 1.05 }
    );

Submit Trailing Stop Orders

Trailing stop orders allow you to create a stop order that automatically changes the stop price allowing you to maximize your profits while still protecting your position with a stop price. For more details, go to Trailing Stop Order Overview

    # Submit a market order to buy 1 share of Apple at market price
    $alpaca->create_order(
        symbol        => 'AAPL',
        qty           => 1,
        side          => 'buy',
        type          => 'market',
        time_in_force => 'gtc'
    );

    # Submit a trailing stop order to sell 1 share of Apple at a
    # trailing stop of
    $alpaca->create_order(
        symbol        => 'AAPL',
        qty           => 1,
        side          => 'sell',
        type          => 'trailing_stop',
        trail_price   => 0.9900, # stop price will be hwm - 0.9900
        time_in_force => 'gtc'
    );

    # Alternatively, you could use trail_percent:
    $alpaca->create_order(
        symbol        => 'AAPL',
        qty           => 1,
        side          => 'sell',
        type          => 'trailing_stop',
        trail_percent => 1.0, # stop price will be hwm * 0.99
        time_in_force => 'gtc'
    );

Get a List of Existing Orders

If you’d like to see a list of your existing orders, you can send a get request for that!

    my @closed_orders = $alpaca->orders(
        status => 'closed',
        limit  => 100,
        nested => 1
    );
    my @closed_aapl_orders = grep { $_->symbol eq 'AAPL' } @closed_orders;

Listen for Updates to Orders

You can use Websockets to receive real-time updates about the status of your orders as they change.

    my $client_order_id = 'my_client_order_id#' . time();
    my $stream          = $alpaca->trade_stream(
        sub ($packet) {
            CORE::say sprintf '[%s] Order %s @ $%f', $packet->order->symbol,
                $packet->order->status, $packet->order->filled_avg_price,
                if $packet->order->client_order_id eq $client_order_id && $packet->event eq 'fill';
        }
    );
    Mojo::IOLoop->timer(
        5 => sub {
            my $order = $alpaca->create_order(
                symbol          => 'MSFT',
                qty             => .1,
                side            => 'buy',
                type            => 'market',
                time_in_force   => 'day',
                client_order_id => $client_order_id
            );
        }
    );

Portfolio Examples

You can view the positions in your portfolio with the following example.

View Open Positions in Your Portfolio

You can view the positions in your portfolio with the following code. If you specify a symbol, you'll see only your position for the associated stock.

    for my $position ( $camelid->positions ) {
        say sprintf '%f shares of %s', $position->qty, $position->symbol;
    }

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson <sanko@cpan.org>