++ed by:
SANKO

1 PAUSE user
1 non-PAUSE user.

Sanko Robinson

NAME

Finance::Robinhood::Order - Order to Buy or Sell a Security

SYNOPSIS

    use Finance::Robinhood;

    my $rh    = Finance::Robinhood->new( token => ... );
    my $acct  = $rh->accounts()->{results}[0]; # Account list is paginated
    my $bill  = $rh->instrument('MSFT');
    my $order = Finance::Robinhood::Order->new(
        account       => $acct,
        instrument    => $bill,
        side          => 'buy',
        type          => 'market',
        trigger       => 'on_close',
        time_in_force => 'gfd',
        quantity      => 300
    );
    $order->cancel(); # Oh, wait!

DESCRIPTION

This class represents a single buy or sell order. These are returned by the locate_order( ... ) and list_orders( ... ) methods of Finance::Robinhood.

Of course, you may place new orders with the new( ... ) constructor of this class.

METHODS

This class has several getters and a few methods as follows...

new( ... )

The main event! Odds are, this is what you installed Finance::Robinhood to do: buy and sell securities without commissions.

Please note that if the call to new( ... ) fails for any reason (not enough buying power, etc.) this will confess( ... ) so it's probably a good idea to wrap it in an eval or something.

There are some keys that are required for all orders and then there are some that only apply for certain types of orders. Different type and trigger combinations can make trading a lot less risky so please check out the order cheat sheet below for easy stop loss and stop limit orders.

These are the required keys for all orders:

account

A Finance::Robinhood::Account object. You can get a list of these with the accounts( ) method found in Finance::Robinhood.

instrument

A Finance::Robinhood::Instrument. The easiest way to get these is to use the instrument( ) method found in Finance::Robinhood.

type

This is a string which may be one of the following:

market
limit
trigger

Which may be one of the following:

immediate

The order is executed immediately.

stop

The order depends on a defined stop_price and then automatically converts into whatever type you provided.

on_close

The order executes as close to the end of the day as possible.

Please note that there are certain timing rules placed on Market On Close (MOC) and Limit On Close (LOC) orders. All (MOC) orders must be submitted by 3:45pm on the NYSE and by 3:50pm EST on the Nasdaq. Neither exchange allows for the modification or cancellation of MOC orders after those times.

time_in_force

Which may be one of the following:

gfd

Good For Day - The order is automatically canceled at the end of the trading day. This can lead to partial executions.

gtc

Good 'Till Canceled - The order will never cancel automatically. You must do so manually.

fok

Fill or Kill - When triggered, the entire order must execute in full immediately or the entire order is canceled.

Note that FOK orders are no longer used on the NYSE.

ioc

Immediate or Cancel - When triggered, the order must execute or the order is canceled. IOC orders allow for partial executions unlike FOK.

opg

Opening - The order is executed at or as close to when the market opens.

Note that OPG orders are not used on Nasdaq.

side

This indicates whether you would like to...

buy
sell
quantity

Is the number of shares this order covers. How many you would like to buy or sell.

In addition to the above, there are some situational values you may need to pass. These include:

price

This is used in limit, stop limit, and stop loss orders where the order will only execute when the going rate hits the given price.

Please note that the API wants prices to be at most 4 decimal places. It is your responsibility to make sure of that. Google Rule 612.

stop_price

This is used in stop limit and stop loss orders where the trigger is stop and the order is automatically converted when the price hits the given stop_price. I obviously would not modify your orders to comply!

Please note that the API wants prices including stop_price to be at most 4 decimal places. It is your responsibility to make sure of that.

override_dtbp_checks

This tells Robinhood's API servers to accept the order even if it violates the Day-Trade Bying Power limits.

extended_hours

This tells the API server to accept the order after the markets are closed. If you'd like these to execute after hours, you must set the type to 'limit' and have a Robinhood Gold subscription.

override_day_trade_checks

This overrides the API's Pattern Day Trade Protection warnings.

account( )

    my $acct = $order->account();

Returns the Finance::Robinhood::Account object related to this order.

executions( )

Returns order executions as a list of hashes which contain the following keys:

    price              The exact price per share
    quantity           The number of shares transfered in this execution
    settlement_date    Date on which the funds of this transaction will settle
    timestamp          When this execution took place

cancel( )

    $order->cancel( ); # Nm! I want to keep these!

If the order can be canceled (has not be executed in completion, etc.), you may cancel it with this.

refresh( )

    $order->refresh( ); # Check for changes

As time passes, an order may change (be executed, etc.). To stay up to date, you could periodically refresh the data.

position( )

Returns a Finance::Robinhood::Position object related to this order's security.

average_price( )

Average price paid for all shares executed in this order.

id( )

    my $id = $order->id();
    # ...later...
    my $order = $rh->order( $id );

The order ID for this particular order. Use this for locating the order again.

fees( )

Total amount of fees related to this order.

price( )

Total current value of the order.

quantity( )

Total number of shares ordered or put up for sale.

cumulative_quantity( )

Total number of shares which have executed so far.

reject_reason( )

If the order was rejected (see state( )), the reason will be here.

side( )

Indicates which side of the deal you were on: buy or sell.

state( )

The current state of the order. For example, completely executed orders have a filled state. The current state may be any of the following: queued, unconfirmed, confirmed, partially_filled, filled, rejected, canceled, failed.

stop_price( )

Stop limit and stop loss orders will have a defined stop price.

time_in_force( )

This may be one of the following:

    gfd     Good For Day
    gtc     Good Til Canceled
    fok     Fill or Kill
    ioc     Immediate or Cancel
    opg

trigger( )

May be one of the following: immediate, on_close, stop

Note: Support for opg orders may indicate support for loo and moo triggers but I have yet to test it.

type( )

May be one of the following: market or limit.

created_at( )

The timestamp when the order was placed.

last_transaction_at( )

The timestamp of the most recent execution.

upated_at( )

Timestamp of the last change made to this order.

override_dtbp_checks( )

True if the Day-Trading Buying Power checks are turned off.

extended_hours( )

Returns true if the order is set to execute after hours.

override_day_trade_checks( )

Returns true if the Pattern Day Trade checks are disabled.

Order Cheat Sheet

This is a little cheat sheet for creating certain types of orders:

Market Sell

A best case market sell gets you whatever the current ask price is at the exact moment of execution.

    my $order = Finance::Robinhood::Order->new(
        type    => 'market',
        trigger => 'immediate',
        side    => 'sell',
        ...
    );

Limit Sell

Limit sells allow you specify the minimum amount you're willing to receive per share.

    my $order = Finance::Robinhood::Order->new(
        type    => 'limit',
        trigger => 'immediate',
        price   => 200.45,
        side    => 'sell',
        ...
    );

Stop Loss Sell

When the bid price drops below the stop price, the order is converted to a market order.

    my $order = Finance::Robinhood::Order->new(
        type       => 'market',
        trigger    => 'stop',
        stop_price => 200.45,
        side       => 'sell',
        ...
    );

Stop Limit Sell

When the bid price drops below the stop price, the order is converted to a limit order at the given price. In the following example, when the price reaches $200.45, the order is converted into a limit order at $199.5 a share.

    my $order = Finance::Robinhood::Order->new(
        type       => 'limit',
        trigger    => 'stop',
        stop_price => 200.45,
        price      => 199.5
        side       => 'sell',
        ...
    );

Market Buy

When triggered, this attempts to execute at the best current price. This may, in fact, be above both the current bid and ask price.

    my $order = Finance::Robinhood::Order->new(
        type       => 'market',
        trigger    => 'immediate',
        side       => 'buy',
        ...
    );

Limit Buy

You may set the maximum amount you're willing to pay per share with a limit buy.

    my $order = Finance::Robinhood::Order->new(
        type       => 'limit',
        trigger    => 'immediate',
        price      => 2.65,
        side       => 'buy',
        ...
    );

Stop Loss Buy

This order type allows you to set a price at which your order converts to a simple market order. In the following example, when the price rises above $2.30/share, the order is converted to a market order and executed at the best available price.

    my $order = Finance::Robinhood::Order->new(
        type       => 'market',
        trigger    => 'stop',
        stop_price => 2.30,
        side       => 'buy',
        ...
    );

Stop Limit Buy

This order type allows you to set a price that converts your order to a limit order. In this example, when the price hits $6/share, the order turns into a limit buy with a stop_price of $6.15/share.

    my $order = Finance::Robinhood::Order->new(
        type       => 'limit',
        trigger    => 'stop',
        price      => 6.15,
        stop_price => 6,
        side       => 'buy',
        ...
    );

LEGAL

This is a simple wrapper around the API used in the official apps. The author provides no investment, legal, or tax advice and is not responsible for any damages incurred while using this software. Neither this software nor its author are affiliated with Robinhood Financial LLC in any way.

For Robinhood's terms and disclosures, please see their website at http://robinhood.com/

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. Please refer to the LEGAL section.

AUTHOR

Sanko Robinson <sanko@cpan.org>