The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Finance::GDAX::API::Order - Perl interface to the GDAX Order API

SYNOPSIS

  use Finance::GDAX::API::Order;

  $order = Finance::GDAX::API::Order->new;
  $order->side('buy');
  $order->type('market');
  $order->product_id('BTC-USD');
  $order->funds(500.00);
  $response = $order->initiate;
  if ($order->error) { die "Error: ".$order->error };
  

DESCRIPTION

Basic interface to the GDAX API for orders. PLEASE USE A NEW ORDER OBJECT FOR EACH ORDER, otherwise unexpected things can happen.

The API shows the response should look something like this for orders intiated:

  {
    "id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
    "price": "0.10000000",
    "size": "0.01000000",
    "product_id": "BTC-USD",
    "side": "buy",
    "stp": "dc",
    "type": "limit",
    "time_in_force": "GTC",
    "post_only": false,
    "created_at": "2016-12-08T20:02:28.53864Z",
    "fill_fees": "0.0000000000000000",
    "filled_size": "0.00000000",
    "executed_value": "0.0000000000000000",
    "status": "pending",
    "settled": false
  }

ATTRIBUTES (common to all order types)

client_oid

[optional] Order ID selected by you to identify your order

The optional client_oid field must be a UUID generated by your trading application. This field value will be broadcast in the public feed for received messages. You can use this field to identify your orders in the public feed.

The client_oid is different than the server-assigned order id. If you are consuming the public feed and see a received message with your client_oid, you should record the server-assigned order_id as it will be used for future order status updates. The client_oid will NOT be used after the received message is sent.

The server-assigned order id is also returned as the id field to this HTTP POST request.

type

[optional] limit, market, or stop (default is limit)

limit orders are both the default and basic order type. A limit order requires specifying a price and size. The size is the number of bitcoin to buy or sell, and the price is the price per bitcoin. The limit order will be filled at the price specified or better. A sell order can be filled at the specified price per bitcoin or a higher price per bitcoin and a buy order can be filled at the specified price or a lower price depending on market conditions. If market conditions cannot fill the limit order immediately, then the limit order will become part of the open order book until filled by another incoming order or canceled by the user.

market orders differ from limit orders in that they provide no pricing guarantees. They however do provide a way to buy or sell specific amounts of bitcoin or fiat without having to specify the price. Market orders execute immediately and no part of the market order will go on the open order book. Market orders are always considered takers and incur taker fees. When placing a market order you can specify funds and/or size. Funds will limit how much of your quote currency account balance is used and size will limit the bitcoin amount transacted.

stop orders become active and wait to trigger based on the movement of the last trade price. There are two types of stop orders, sell stop and buy stop.

side

buy or sell

side: 'sell': Place a sell stop order, which triggers when the last trade price changes to a value at or below the price.

side: 'buy': Place a buy stop order, which triggers when the last trade price changes to a value at or above price.

product_id

A valid product id

The product_id must match a valid product. The products list is available via the /products endpoint.

stp

[optional] Self-trade prevention flag

Self-trading is not allowed on GDAX. Two orders from the same user will not be allowed to match with one another. To change the self-trade behavior, specify the stp flag.

  Flag  Name
  dc    Decrease and Cancel (default)
  co    Cancel oldest
  cn    Cancel newest
  cb    Cancel both

ATTRIBUTES (limit orders)

price

Price per bitcoin

The price must be specified in quote_increment product units. The quote increment is the smallest unit of price. For the BTC-USD product, the quote increment is 0.01 or 1 penny. Prices less than 1 penny will not be accepted, and no fractional penny prices will be accepted. Not required for market orders.

size

Amount of BTC to buy or sell

The size must be greater than the base_min_size for the product and no larger than the base_max_size. The size can be in any increment of the base currency (BTC for the BTC-USD product), which includes satoshi units. size indicates the amount of BTC (or base currency) to buy or sell.

time_in_force

[optional] GTC, GTT, IOC, or FOK (default is GTC)

cancel_after

[optional] min, hour, day

Requires time_in_force to be GTT

Time in force policies provide guarantees about the lifetime of an order. There are four policies: good till canceled GTC, good till time GTT, immediate or cancel IOC, and fill or kill FOK.

GTC Good till canceled orders remain open on the book until canceled. This is the default behavior if no policy is specified.

GTT Good till time orders remain open on the book until canceled or the allotted cancel_after is depleted on the matching engine. GTT orders are guaranteed to cancel before any other order is processed after the cancel_after timestamp which is returned by the API. A day is considered 24 hours.

IOC Immediate or cancel orders instantly cancel the remaining size of the limit order instead of opening it on the book.

FOK Fill or kill orders are rejected if the entire size cannot be matched.

* Note, match also refers to self trades.

post_only

[optional] Post only flag

Invalid when time_in_force is IOC or FOK

The post-only flag indicates that the order should only make liquidity. If any part of the order results in taking liquidity, the order will be rejected and no part of it will execute.

ATTRIBUTES (market orders)

size

[optional]* Desired amount in BTC

The size must be greater than the base_min_size for the product and no larger than the base_max_size. The size can be in any increment of the base currency (BTC for the BTC-USD product), which includes satoshi units. size indicates the amount of BTC (or base currency) to buy or sell.

* One of size or funds is required.

funds

[optional]* Desired amount of quote currency to use

The funds field is optionally used for market orders. When specified it indicates how much of the product quote currency to buy or sell. For example, a market buy for BTC-USD with funds specified as 150.00 will spend 150 USD to buy BTC (including any fees). If the funds field is not specified for a market buy order, size must be specified and GDAX will use available funds in your account to buy bitcoin.

A market sell order can also specify the funds. If funds is specified, it will limit the sell to the amount of funds specified. You can use funds with sell orders to limit the amount of quote currency funds received.

* One of size or funds is required.

ATTRIBUTES (stop order)

price

Desired price at which the stop order triggers

size

[optional]* Desired amount in BTC

funds

[optional]* Desired amount of quote currency to use

* One of size or funds is required.

ATTRIBUTES (margin parameters)

overdraft_enabled

* If true funding will be provided if the order's cost cannot be covered by the account's balance

funding_amount

* Amount of funding to be provided for the order

* Margin can be used to receive funding by specifying either overdraft_enabled or funding_amount.

METHODS

initiate

Initiates the REST order request and returns the result, according to the current API docs, like

  {
    "id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
    "price": "0.10000000",
    "size": "0.01000000",
    "product_id": "BTC-USD",
    "side": "buy",
    "stp": "dc",
    "type": "limit",
    "time_in_force": "GTC",
    "post_only": false,
    "created_at": "2016-12-08T20:02:28.53864Z",
    "fill_fees": "0.0000000000000000",
    "filled_size": "0.00000000",
    "executed_value": "0.0000000000000000",
    "status": "pending",
    "settled": false
  }

If $order->error exists, then it will contain the error message. PLEASE USE A NEW ORDER OBJECT FOR EACH ORDER, otherwise unexpected things can happen.

cancel $order_id

Cancels the $order_id, where $order_id is the server-assigned order_id and not the client-selected client_oid.

Probelms will be reported in ->error

cancel_all ($product_id)

Cancels all orders, or if $product_id is specified, cancels only orders within those prodcuts.

An array will be returned, according to current API docs:

  [
    "144c6f8e-713f-4682-8435-5280fbe8b2b4",
    "debe4907-95dc-442f-af3b-cec12f42ebda",
    "cf7aceee-7b08-4227-a76c-3858144323ab",
    "dfc5ae27-cadb-4c0c-beef-8994936fde8a",
    "34fecfbf-de33-4273-b2c6-baf8e8948be4"
  ]

list ($status, $product_id)

Returns a list of orders. You can limit the list by specifying order status and product_id. These are positional parameters, so status must come first even if undefined (or 0).

  $list = $order->list;

$status can be an arrayref, in which case it will list each of the given status.

  $list = $order->list(['open','settled'], 'BTC-USD');

To quote from the API:

    Orders which are no longer resting on the order book, will be marked with the done status. There is a small window between an order being done and settled. An order is settled when all of the fills have settled and the remaining holds (if any) have been removed.

By default open, pending and active orders are returned.

get $order_id

Returns a hash of the specified $order_id

AUTHOR

Mark Rushing <mark@orbislumen.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Home Grown Systems, SPC.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.