NAME

Finance::Alpaca::DataStream - A Streaming, Real-time Data Object

SYNOPSIS

    use Finance::Alpaca;
    my $stream = Finance::Alpaca->new( ... )->data_stream(
        sub ($packet) { ...; }
    );
    $stream->subscribe(
        quotes => ['MSFT'], trades => ['MSFT'], bars => ['*']
    );
    Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

DESCRIPTION

Finance::Alpaca::DataStream receives real-time market data.

You can send one or more subscription messages (described below) and after confirmation you will receive the corresponding market data.

At any time you can subscribe to or unsubscribe from symbols. Please note that due to the internal buffering mentioned above for a short while you may receive data points for symbols you have recently unsubscribed from.

METHODS

subscribe( ... )

    $stream->subscribe(
        quotes => ['MSFT'], trades => ['MSFT'], bars => ['*']
    );

You can subscribe to trades, quotes and bars of a particular symbol (or * for every symbol in the case of bars). A subscribe message should contain what subscription you want to add to your current subscriptions in your session so you don’t have to send what you’re already subscribed to.

This method accepts the following parameters:

bars - List of ticker symbols
dailyBars - List of ticker symbols
quotes - List of ticker symbols
trades - List of ticker symbols or *

You can also omit either one of them (trades, quotes, or bars) if you don’t want to subscribe to any symbols in that category but be sure to include at least one of the three.

subscriptions( )

    my $current = $stream->subscriptions( );

After subscribing or unsubscribing, our websocket will receive a message that describes your current list of subscriptions. You may access this data with this method.

unsubscribe( ... )

    $stream->unsubscribe(
        quotes => ['MSFT']
    );

Much like subscribe you can also send an unsubscribe message that subtracts the list of subscriptions specified from your current set of subscriptions.

This method accepts the following parameters:

bars - List of ticker symbols
quotes - List of ticker symbols
trades - List of ticker symbols or *

You can also omit either one of them (trades, quotes, or bars) if you don’t want to subscribe to any symbols in that category but be sure to include at least one of the three.

Errors

Unhandled errors are passed directly to the callback. Possible errors include...

400
    { T => 'error', code => 400, msg => 'invalid syntax' }

The message you sent to the server did not follow the specification.

401
    { T => 'error', code => 401, msg => 'not authenticated' }

You have attempted to subscribe or unsubscribe before authentication.

402
    { T => 'error', code => 402, msg => 'auth failed' }

You have provided invalid authentication credentials.

403
    { T => 'error', code => 403, msg => 'already authenticated' }

You have already successfully authenticated during your current session.

404
    { T => 'error', code => 404, msg => 'auth timeout' }

You failed to successfully authenticate after connecting. You have a few seconds to authenticate after connecting.

405
    { T => 'error', code => 405, msg => 'symbol limit exceeded' }

The symbol subscription request you sent would put you over the limit set by your subscription package. If this happens your symbol subscriptions are the same as they were before you sent the request that failed.

406
    { T => 'error', code => 406, msg => 'connection limit exceeded' }

You already have an ongoing authenticated session.

407
    { T => 'error', code => 407, msg => 'slow client' }

You may receive this if you are too slow to process the messages sent by the server. Please note that this is not guaranteed to arrive before you are disconnected to avoid keeping slow connections active forever.

408
    { T => 'error', code => 408, msg => 'v2 not enabled' }

Your account does not have access to Data v2.

409
    { T => 'error', code => 409, msg => 'insufficient subscription' }

You have attempted to access a data source not available in your subscription package.

500
    { T => 'error', code => 500, msg => 'internal error' }

An unexpected error occurred on our end and Alpaca is investigating the issue.

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>