NAME
Finance::Alpaca - Perl Wrapper for Alpaca's Commission-free Stock Trading API
SYNOPSIS
use Finance::Alpaca;
my $alpaca = Finance::Alpaca->new(
paper => 1,
keys => [ ... ]
);
my $order = $alpaca->create_order(
symbol => 'MSFT',
qty => .1,
side => 'buy',
type => 'market',
time_in_force => 'day'
);
DESCRIPTION
Finance::Alpaca allows you to buy, sell, and short U.S. stocks with zero commissions with Alpaca, an API first, algo-friendly brokerage.
METHODS
new( ... )
my $camelid = Finance::Alpaca->new(
keys => [ 'MDJOHHAE5BDE2FAYAEQT',
'Xq9p6ovxaa5XKihaEDRgpMapjeWYd5gIM63iq5BL'
] );
Creates a new Finance::Alpaca object.
This constructor accepts the following parameters:
keys
-[ $APCA_API_KEY_ID, $APCA_API_SECRET_KEY ]
-
Every API call requires authentication. You must provide these keys which may be acquired in the developer web console and are only visible on creation.
paper
- Boolean value-
If you're attempting to use Alpaca's paper trading system, this must be a true value. Otherwise, you will be making live trades with real assets!
Note: This is a false value by default.
account( )
my $acct = $camelid->account( );
CORE::say sprintf 'I can%s short!', $acct->shorting_enabled ? '' : 'not';
Returns a Finance::Alpaca::Struct::Account object.
The account endpoint serves important information related to an account, including account status, funds available for trade, funds available for withdrawal, and various flags relevant to an account’s ability to trade.
clock( )
my $clock = $camelid->clock();
say sprintf
$clock->timestamp->strftime('It is %l:%M:%S %p on a %A and the market is %%sopen!'),
$clock->is_open ? '' : 'not ';
Returns a Finance::Alpaca::Struct::Clock object.
The clock endpoint serves the current market timestamp, whether or not the market is currently open, as well as the times of the next market open and close.
calendar( [...] )
my @days = $camelid->calendar(
start => Time::Moment->now,
end => Time::Moment->now->plus_days(14)
);
for my $day (@days) {
say sprintf '%s the market opens at %s Eastern',
$day->date, $day->open;
}
Returns a list of Finance::Alpaca::Struct::Calendar objects.
The calendar endpoint serves the full list of market days from 1970 to 2029.
The following parameters are accepted:
start
- The first date to retrieve data for (inclusive); Time::Moment object or RFC3339 stringend
- The last date to retrieve data for (inclusive); Time::Moment object or RFC3339 string
Both listed parameters are optional. If neither is provided, the calendar will begin on January 1st, 1970.
assets( [...] )
say $_->symbol
for sort { $a->symbol cmp $b->symbol } @{ $camelid->assets( status => 'active' ) };
Returns a list of Finance::Alpaca::Struct::Asset objects.
The assets endpoint serves as the master list of assets available for trade and data consumption from Alpaca.
The following parameters are accepted:
status
- e.g.active
orinactive
. By default, all statuses are includedasset_class
- Defaults tous_equity
asset( ... )
my $msft = $camelid->asset('MSFT');
my $spy = $camelid->asset('b28f4066-5c6d-479b-a2af-85dc1a8f16fb');
Returns a Finance::Alpaca::Struct::Asset object.
You may use either the asset's id
(UUID) or symbol
. If the asset is not found, an empty list is returned.
bars( ... )
my %bars = $camelid->bars(
symbol => 'MSFT',
timeframe => '1Min',
start => Time::Moment->now->with_hour(10),
end => Time::Moment->now->minus_minutes(20)
);
Returns a list of Finance::Alpaca::Struct::Bar objects along with other data.
The bar endpoint serves aggregate historical data for the requested securities.
The following parameters are accepted:
symbol
- The symbol to query for; this is requiredstart
- Filter data equal to or before this time in RFC-3339 format or a Time::Moment object. Fractions of a second are not accepted; this is requiredend
- Filter data equal to or before this time in RFC-3339 format or a Time::Moment object. Fractions of a second are not accepted; this is requiredlimit
- Number of data points to return. Must be in range1-10000
, defaults to1000
page_token
- Pagination token to continue fromtimeframe
- Timeframe for the aggregation. Available values are:1Min
,1Hour
, and1Day
; this is required
The method returns a hash reference with bar data included as a list under the symbol as well as a next_page_token
for pagination if applicable.
quotes( ... )
my %quotes = $camelid->quotes(
symbol => 'MSFT',
start => Time::Moment->now->with_hour(10),
end => Time::Moment->now->minus_minutes(20)
);
Returns a list of Finance::Alpaca::Struct::Quote objects along with other data.
The bar endpoint serves quote (NBBO) historical data for the requested security.
The following parameters are accepted:
symbol
- The symbol to query for; this is requiredstart
- Filter data equal to or before this time in RFC-3339 format or a Time::Moment object. Fractions of a second are not accepted; this is requiredend
- Filter data equal to or before this time in RFC-3339 format or a Time::Moment object. Fractions of a second are not accepted; this is requiredlimit
- Number of data points to return. Must be in range1-10000
, defaults to1000
page_token
- Pagination token to continue from
The method returns a hash reference with quote data included as a list under the symbol as well as a next_page_token
for pagination if applicable.
trades( ... )
my %trades = $camelid->trades(
symbol => 'MSFT',
start => Time::Moment->now->with_hour(10),
end => Time::Moment->now->minus_minutes(20)
);
Returns a list of Finance::Alpaca::Struct::Trade objects along with other data.
The bar endpoint serves historical trade data for a given ticker symbol on a specified date.
The following parameters are accepted:
symbol
- The symbol to query for; this is requiredstart
- Filter data equal to or before this time in RFC-3339 format or a Time::Moment object. Fractions of a second are not accepted; this is requiredend
- Filter data equal to or before this time in RFC-3339 format or a Time::Moment object. Fractions of a second are not accepted; this is requiredlimit
- Number of data points to return. Must be in range1-10000
, defaults to1000
page_token
- Pagination token to continue from
The method returns a hash reference with trade data included as a list under the symbol as well as a next_page_token
for pagination if applicable.
trade_stream( ... )
my $stream = $camelid->trade_stream( sub ($packet) { ... } );
Returns a new Finance::Alpaca::TradeStream object.
You are ready to receive real-time account and order data!
This method expects a code reference. This callback will receive all incoming data.
data_stream( ... )
my $stream = $camelid->data_stream( sub ($packet) { ... } );
$stream->subscribe(
trades => ['MSFT']
);
Returns a new Finance::Alpaca::DataStream object.
You are ready to receive real-time market data!
You can send one or more subscription messages (described in Finance::Alpaca::DataStream) and after confirmation you will receive the corresponding market data.
This method expects a code reference. This callback will receive all incoming data.
orders( [...] )
my @orders = $camelid->orders( status => 'open' );
Returns a list of Finance::Alpaca::Struct::Order objects.
The orders endpoint returns a list of orders for the account, filtered by the supplied parameters.
The following parameters are accepted:
status
- Order status to be queried.open
,closed
, orall
. Defaults toopen
.limit
- The maximum number of orders in response. Defaults to50
and max is500
.after
- The response will include only ones submitted after this timestamp (exclusive.)until
- The response will include only ones submitted until this timestamp (exclusive.)direction
- The chronological order of response based on the submission time.asc
ordesc
. Defaults todesc
.nested
- Boolean value indicating whether the result will roll up multi-leg orders under thelegs( )
field of the primary order.symbols
- A comma-separated list of symbols to filter by (ex.AAPL,TSLA,MSFT
).
order_by_id( ..., [...] )
my $order = $camelid->order_by_id('0f43d12c-8f13-4bff-8597-c665b66bace4');
Returns a Finance::Alpaca::Struct::Order object.
You must provide the order's id
(UUID). If the order is not found, an empty list is returned.
You may also provide a boolean value; if true, the result will roll up multi-leg orders under the legs( )
field in primary order.
my $order = $camelid->order_by_id('0f43d12c-8f13-4bff-8597-c665b66bace4', 1);
order_by_client_id( ... )
my $order = $camelid->order_by_client_id('17ff6b86-d330-4ac1-808b-846555b75b6e');
Returns a Finance::Alpaca::Struct::Order object.
You must provide the order's client_order_id
(UUID). If the order is not found, an empty list is returned.
create_order( ... )
my $order = $camelid->create_order(
symbol => 'MSFT',
qty => .1,
side => 'buy',
type => 'market',
time_in_force => 'day'
);
If the order is placed successfully, this method returns a Finance::Alpaca::Struct::Order object. Failures result in hash references with data from the API.
An order request may be rejected if the account is not authorized for trading, or if the tradable balance is insufficient to fill the order.
The following parameters are accepted:
symbol
- symbol or asset ID to identify the asset to trade (Required)notional
-dollar amount to trade. Cannot work with qty. Can only work formarket
order types andday
for time in force (Required)side
-buy
orsell
(Required)type
-market
,limit
,stop
,stop_limit
, ortrailing_stop
(Required)time_in_force
-day
,gtc
,opg
,cls
,ioc
,fok
. Please see Understand Orders for more info (Required)limit_price
- Required iftype
islimit
orstop_limit
stop_price
- Required iftype
isstop
orstop_limit
trail_price
- This ortrail_percent
is required iftype
istrailing_stop
trail_percent
- This ortrail_price
is required iftype
istrailing_stop
extended_hours
- If atrue
value, order will be eligible to execute in premarket/afterhours. Only works withtype
islimit
andtime_in_force
isday
client_order_id
- A unique identifier (UUID v4) for the order. Automatically generated by Alpaca if not sent.order_class
-simple
,bracket
,oco
oroto
. For details of non-simple order classes, please see Bracket Order Overviewtake_profit
- Additional parameters fortake_profit
leg of advanced ordersstop_loss
- Additional parameters for stop-loss leg of advanced orders
replace_order( ..., ... )
my $new_order = $camelid->replace_order(
$order->id,
qty => 1,
time_in_force => 'fok',
limit_price => 120
);
Replaces a single order with updated parameters. Each parameter overrides the corresponding attribute of the existing order. The other attributes remain the same as the existing order.
A success return code from a replaced order does NOT guarantee the existing open order has been replaced. If the existing open order is filled before the replacing (new) order reaches the execution venue, the replacing (new) order is rejected, and these events are sent in the trade_updates stream channel.
While an order is being replaced, buying power is reduced by the larger of the two orders that have been placed (the old order being replaced, and the newly placed order to replace it). If you are replacing a buy entry order with a higher limit price than the original order, the buying power is calculated based on the newly placed order. If you are replacing it with a lower limit price, the buying power is calculated based on the old order.
In addition to the original order's ID, this method expects the following parameters:
time_in_force
-day
,gtc
,opg
,cls
,ioc
,fok
. Please see Understand Orders for more infolimit_price
- required iftype
islimit
orstop_limit
stop_price
- required iftype
isstop
orstop_limit
trail
- the new value of thetrail_price
ortrail_percent
value (works only wheretype
istrailing_stop
)client_order_id
- A unique identifier (UUID v4) for the order. Automatically generated by Alpaca if not sent.
cancel_orders( )
$camelid->cancel_orders( );
Attempts to cancel all open orders.
On success, an array of hashes will be returned each with the following elements:
body
- Finance::Alpaca::Struct::Order objectid
- the order ID (UUID)status
- HTTP status code for the request
A response will be provided for each order that is attempted to be cancelled. If an order is no longer cancelable, the server will reject the request and and empty list will be returned.
cancel_order( ... )
$camelid->cancel_order( 'be07eebc-13f0-4072-aa4c-f67046081276' );
Attempts to cancel an open order. If the order is no longer cancelable (example: status
is filled
), the server will respond with status 422, reject the request, and an empty list will be returned. Upon acceptance of the cancel request, it returns status 204 and a true value.
positions( )
$camelid->positions( );
Retrieves a list of the account’s open positions and returns a list of Finance::Alpaca::Struct::Position objects.
position( ... )
my $elon = $camelid->position( 'TSLA' );
my $msft = $camelid->position( 'b6d1aa75-5c9c-4353-a305-9e2caa1925ab' );
Retreves the account's open position for the given symbol or asset ID and returns a Finance::Alpaca::Struct::Position object if found.
If not found, and empty list is returned.
close_all_positions( [...] )
my $panic = $camelid->close_all_positions( );
Closes (liquidates) all of the account’s open long and short positions.
$panic = $camelid->close_all_positions( 1 );
This method accepts one optional parameter which, if true, will cancel all open orders before liquidating all positions.
On success, an array of hashes will be returned each with the following elements:
body
- Finance::Alpaca::Struct::Order objectid
- the order ID (UUID)status
- HTTP status code for the request
A response will be provided for each position that is attempted to be closed.
close_position( ..., [...] )
my $order = $camelid->close_position('MSFT');
$order = $camelid->close_position( 'b6d1aa75-5c9c-4353-a305-9e2caa1925ab' );
Closes (liquidates) the account’s open position for the given symbol or asset ID and returns a Finance::Alpaca::Struct::Order object. Works for both long and short positions.
my $order = $camelid->close_position('MSFT', 0.5);
This method accepts a second, optional parameter which is the number of shares to liquidate.
portfolio_history( [...] )
$camelid->portfolio_history( );
The portfolio history API returns the timeseries data for equity and profit loss information of the account.
$camelid->portfolio_history( period => '2W' );
This method accepts the following optional parameters:
period
- The duration of the data in<number> + <unit>
, such as 1D, where <unit> can be D for day,W
for week,M
for month andA
for year. Defaults to1M
timeframe
- The resolution of time window.1Min
,5Min
,15Min
,1H
, or1D
. If omitted,1Min
for less than 7 days period,15Min
for less than 30 days, or otherwise1D
date_end
- The date the data is returned up to, inYYYY-MM-DD
format or as a Time::Moment object. Defaults to the current market date (rolls over at the market open ifextended_hours
is false, otherwise at 7am ET)extended_hours
Boolean value; if true, include extended hours in the result. This is effective only for timeframe less than1D
.
The returned data is in a hash ref with the following keys:
timestamp
- List of Time::Moment objects; the time of each data element, left-labeled (the beginning of the window)equity
- List of numbers; equity values of the account in dollar amounts as of the end of each time windowprofit_loss
- List of numbers; profit/loss in dollar from the base valueprofit_loss_pct
- List of numbers; profit/loss in percentage from the base valuebase_value
- basis in dollar of the profit loss calculationtimeframe
- time window size of each data element
watchlists( )
my @watchlists = $camelid->watchlists;
Returns the list of watchlists registered under the account as Finance::Alpaca::Struct::Watchlist objects.
create_watchlist( ..., [...] )
my $new_watchlist = $camelid->create_watchlist( 'Leveraged ETFs' );
my $tech_watchlist = $camelid->create_watchlist( 'FAANG', qw[FB AMZN AAPL NFLX GOOG] );
Create a new watchlist potentially with an initial set of assets. Only the first parameter is required and is the name of the user-defined new watchlist. This name must be a maximum of 64
characters. To add assets to the watchlist on create, include a list of ticker symbols.
On success, the related Finance::Alpaca::Struct::Watchlist object is returned.
delete_watchlist( ... )
$camelid->delete_watchlist( '88f0c1e1-58d4-42c5-b85b-864839045678' );
Delete a watchlist identified by the ID. This is a permanent deletion.
watchlist( ... )
$camelid->watchlist( '88f0c1e1-58d4-42c5-b85b-864839045678' );
Returns a watchlist identified by the ID.
update_watchlist( ... )
$camelid->update_watchlist( '88f0c1e1-58d4-42c5-b85b-864839045678', name => 'Low priority' );
$camelid->update_watchlist( '29d85812-b4a2-45da-ac6c-dcc0ad9c1cd3', symbols => [qw[MA V]] );
Update the name and/or content of watchlist. On success, a Finance::Alpaca::Struct::Watchlist object is returned.
add_to_watchlist( ... )
$camelid->add_to_watchlist( '88f0c1e1-58d4-42c5-b85b-864839045678', 'TSLA');
Append an asset for the symbol to the end of watchlist asset list. On success, a Finance::Alpaca::Struct::Watchlist object is returned.
remove_from_watchlist( ... )
$camelid->remove_from_watchlist( '88f0c1e1-58d4-42c5-b85b-864839045678', 'F');
Delete one entry for an asset by symbol name. On success, a Finance::Alpaca::Struct::Watchlist object is returned.
configuration( )
my $confs = $camelid->configuration( );
Returns the current account configuration values.
modify_configuration( )
$confs = $camelid->modify_configuration(
trade_confirm_email=> 'all'
);
Updates the account configuration values. On success, the modified configuration is returned.
activities( [...] )
my @activities = $camelid->activities();
Returns account activity entries for many types of activities.
@activities = $camelid->activities(activity_types => [qw[ACATC ACATS]]);
Returns account activity entries for a set of specific types of activity. See Finance::Alpaca::Struct::Activity for a list of activity types.
This method expects a combination of the following optional parameters:
activity_types
- A list of the activity types to include in the response. If unspecified, activities of all types will be returned.date
- The date for which you want to see activities as string or Time::Moment objectuntil
- The response will contain only activities submitted before this date. (Cannot be used withdate
.)after
- The response will contain only activities submitted after this date. (Cannot be used withdate
.)direction
-asc
ordesc
(default isdesc
if unspecified.)page_size
- The maximum number of entries to return in the responsepage_token
- The ID of the end of your current page of results
Paging of Results
When required, pagination is handled using the page_token
and page_size
parameters. page_token
represents the ID of the end of your current page of results. If specified with a direction of desc
, for example, the results will end before the activity with the specified ID. If specified with a direction of asc
, results will begin with the activity immediately after the one specified. page_size
is the maximum number of entries to return in the response. If date
is not specified, the default and maximum value is 100
. If date
is specified, the default behavior is to return all results, and there is no maximum page size.
See Also
https://alpaca.markets/docs/api-documentation/api-v2/
Note
I do not have a live trading account with Alpaca but this package has worked well with paper trading. YMMV.
LEGAL
This is a simple wrapper around the API as described in documentation. The author provides no investment, legal, or tax advice and is not responsible for any damages incurred while using this software. This software is not affiliated with Alpaca Securities LLC in any way.
For Alpaca's terms and disclosures, please see their website at https://alpaca.markets/disclosures
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>