Finance-Alpaca
view release on metacpan or search on metacpan
[](https://travis-ci.com/sanko/Finance-Alpaca) [](https://metacpan.org/release/Finance-Alpaca)
# 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3AAccount) 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3AClock) 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3ACalendar) 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 string
- `end` - 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3AAsset) 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` or `inactive`. By default, all statuses are included
- `asset_class` - Defaults to `us_equity`
## `asset( ... )`
my $msft = $camelid->asset('MSFT');
my $spy = $camelid->asset('b28f4066-5c6d-479b-a2af-85dc1a8f16fb');
Returns a [Finance::Alpaca::Struct::Asset](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3AAsset) 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3ABar) 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 required
- `start` - 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 required
- `end` - 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 required
- `limit` - Number of data points to return. Must be in range `1-10000`, defaults to `1000`
- `page_token` - Pagination token to continue from
- `timeframe` - Timeframe for the aggregation. Available values are: `1Min`, `1Hour`, and `1Day`; 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3AQuote) 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 required
- `start` - 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 required
- `end` - 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 required
- `limit` - Number of data points to return. Must be in range `1-10000`, defaults to `1000`
- `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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3ATrade) 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 required
- `start` - 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 required
- `end` - 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 required
- `limit` - Number of data points to return. Must be in range `1-10000`, defaults to `1000`
- `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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3ATradeStream) 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3ADataStream) object.
You are ready to receive real-time market data!
You can send one or more subscription messages (described in
[Finance::Alpaca::DataStream](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3ADataStream)) 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3AOrder) 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`, or `all`. Defaults to `open`.
- `limit` - The maximum number of orders in response. Defaults to `50` and max is `500`.
- `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` or `desc`. Defaults to `desc`.
- `nested` - Boolean value indicating whether the result will roll up multi-leg orders under the `legs( )` 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3AOrder) 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3AOrder) 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](https://metacpan.org/pod/Finance%3A%3AAlpaca%3A%3AStruct%3A%3AOrder) 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)
- `qty` - number of shares to trade. Can be fractionable for only `market` and `day` order types (Required)
- `notional` -dollar amount to trade. Cannot work with qty. Can only work for `market` order types and `day` for time in force (Required)
- `side` - `buy` or `sell` (Required)
- `type` - `market`, `limit`, `stop`, `stop_limit`, or `trailing_stop` (Required)
- `time_in_force` - `day`, `gtc`, `opg`, `cls`, `ioc`, `fok`. Please see [Understand Orders](https://alpaca.markets/docs/trading-on-alpaca/orders/#time-in-force) for more info (Required)
( run in 0.776 second using v1.01-cache-2.11-cpan-5a3173703d6 )