oanda_api 0.8.1 → 0.8.3

data/.gitignore

@@ -0,0 +1,38 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+.*.sw[a-z]
+
+## RubyMine and related
+.idea
+
+## PROJECT::GENERAL
+coverage
+rdoc
+doc
+pkg
+
+## PROJECT::SPECIFIC
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+tmp/*
+spec/reports
+*.rbc
+*.rbx
+.ruby-gemset
+.ruby-version
+.rubocop*
+.rvmrc
+.yardoc

data/.rspec_non_jruby

@@ -0,0 +1,2 @@
+--format Fuubar
+--color

data/.yardopts

@@ -0,0 +1,6 @@
+--readme README.md
+--title 'OandaAPI Documentation'
+--charset utf-8
+--markup markdown
+'lib/**/*.rb' - '*.md'
+LICENSE

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://www.rubygems.org"
+
+gemspec
+
+group :development do
+  gem "pry"
+  gem "guard"
+  gem "guard-rspec"
+  gem "fuubar"
+  gem "redcarpet"
+  gem "github-markup"
+  gem "rubocop", require: false
+end

data/Guardfile

@@ -0,0 +1,7 @@
+guard :rspec, cmd: "bundle exec rspec" do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch("spec/spec_helper.rb")  { "spec" }
+end
+
+clearing :on

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Dean Missikowski
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,218 @@
+# OandaAPI
+Access Oanda FX accounts, get market data, trade, build trading strategies using Ruby.
+## Synopsis 
+OandaAPI is a simple Ruby wrapper for the [Oanda REST API](http://developer.oanda.com/rest-live/introduction/).
+
+This style of API wrapper is typically called a [fluent](http://en.wikipedia.org/wiki/Fluent_interface) interface. The wrapper translates native Ruby objects to and from JSON representations that the API understands.
+
+For example,
+
+```ruby
+client = OandaAPI::Client::TokenClient.new(:practice, "practice_account_token") 
+account = client.account(12345).get 
+```
+
+returns an OandaAPI::Resource::Account, with method accessors for all of the [Account](http://developer.oanda.com/rest-live/accounts/) attributes defined by the Oanda API.
+
+
+## Features
+
+A simple native Ruby reflection of the underlying REST API using Ruby idioms where appropriate.
+
+Enable [Oanda's Best Practices](http://developer.oanda.com/rest-live/best-practices/) recommendations for accessing the API including:
+
+- Secure connections over SSL with always verified certificates
+- Persistent connections
+- Response compression
+- Request rate limiting
+
+
+Some Examples
+-------------
+
+### Getting price quotes
+```ruby
+require 'oanda_api'
+
+client = OandaAPI::Client::TokenClient.new(:practice, ENV["practice_account_token"])
+
+prices = client.prices(instruments: %w(EUR_USD USD_JPY)).get
+
+prices.each do |p|
+  p.instrument       # => "EUR_USD"
+  p.ask              # => 1.13781
+  p.bid              # => 1.13759
+  p.time             # => 2015-01-27 21:01:13 UTC
+end
+```
+
+### Getting candle information
+```ruby
+require 'oanda_api'
+
+client = OandaAPI::Client::TokenClient.new(:practice, ENV["practice_account_token"])
+
+candles = client.candles( instrument: "EUR_USD",
+                         granularity: "M1",
+                       candle_format: "midpoint",
+                               start: (Time.now - 3600).utc.to_datetime.rfc3339)
+                .get
+
+candles.size         # => 57
+candles.granularity  # => "M1"
+candles.instrument   # => "EUR_USD"
+
+candles.each do |c|
+  c.complete?        # => true
+  c.open_mid         # => 1.137155
+  c.close_mid        # => 1.137185
+  c.high_mid         # => 1.13729
+  c.low_mid          # => 1.137155
+  c.time             # => 2015-01-27 20:26:00 UTC
+  c.volume           # => 25
+end
+```
+
+
+### Creating a market order
+```ruby
+require 'oanda_api'
+
+client = OandaAPI::Client::TokenClient.new(:practice, ENV["practice_account_token"])
+
+order = client.account(12345)
+              .order(instrument: "USD_JPY", 
+                           type: "market",
+                           side: "buy",
+                          units: 10_000)
+              .create
+
+order.price            # => 114.887
+order.time             # => 2014-12-20 21:25:57 UTC
+order.trade_opened.id  # => 175491416                         
+```
+
+### Closing a position
+```ruby
+require 'oanda_api'
+
+client = OandaAPI::Client::TokenClient.new(:practice, ENV["practice_account_token"])
+
+account = client.account(12345)             # => OandaAPI::NamespaceProxy
+position = account.position("USD_JPY").get  # => OandaAPI::Resource::Position
+
+position.ave_price  # => 114.898
+position.side       # => "buy"
+position.units      # => 30_000 
+
+# Close out the 30_000 long position
+closed_position = account.position("USD_JPY").close  # => OandaAPI::Resource::Position
+
+closed_position.price        # => 114.858
+closed_position.total_units  # => 30_000
+closed_position.ids          # => [175490804, 175491421, 175491416]
+
+transaction = account.transaction(175490804).get    # => OandaAPI::Resource::Transaction
+transaction.instrument  # => "USD_JPY"
+transaction.time        # => 2014-12-19 03:29:48 UTC
+transaction.type        # => "MARKET_ORDER_CREATE"
+```
+
+Documentation
+-------------
+
+Please see the [Oanda Developer Wiki](http://developer.oanda.com/rest-live/introduction/)
+for detailed documentation and API usage notes.
+
+
+| Ruby                       |  Oanda REST API      | 
+|:---------------------------|:---------------------|
+| client.accounts.get        | GET /v1/accounts     | 
+| client.account(123).get    | GET /v1/accounts/123 |
+| client.account.create      | POST /v1/accounts    |
+| client.instruments.get     | GET /v1/instruments  |
+| client.prices(instruments: ["EUR_USD","USD_JPY"]).get | GET /v1/prices/?instruments=EUR_USD%2CUSD_JPY |
+| client.account(123).orders.get | GET /v1/accounts/123/orders
+| client.account(123).order(123).get | GET /v1/accounts/123/orders/123
+| client.account(123).order( *options* ).create | POST /v1/accounts/123/orders |
+| client.account(123).order(id:123, *options* ).update | PATCH /v1/accounts/123/orders/123 |
+| client.account(123).order(123).close | DELETE /v1/accounts/123/orders/123 |
+| client.account(123).positions.get | GET /v1/accounts/123/positions |
+| client.account(123).position("EUR_USD").get | GET /v1/accounts/123/positions/EUR_USD |
+| client.account(123).position("EUR_USD").close | DELETE /v1/accounts/123/positions/EUR_USD |
+| client.account(123).trades.get | GET /v1/accounts/123/trades |
+| client.account(123).trade(123).get | GET /v1/accounts/123/trades/123 |
+| client.account(123).trade(id:123, *options* ).update | PATCH /v1/accounts/123/trades/123 |
+| client.account(123).trade(123).close | DELETE /v1/accounts/123/trades/123 |
+| client.account(123).transactions.get | GET /v1/accounts/123/transactions |
+| client.account(123).transaction(123).get | GET /v1/accounts/123/transactions/123 |
+| client.account(123).alltransactions.get | GET /v1/accounts/123/alltransactions |
+
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    gem 'oanda_api'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install oanda_api
+
+Inside of your Ruby program, require oanda_api with:
+
+    require 'oanda_api'
+
+Configuration
+-------------
+
+Add a configuration block to your application to specify client settings such
+as whether or not to use compression, request rate limiting, or other options.
+See the RubyDoc [documentation](http://www.rubydoc.info/gems/oanda_api) for OandaAPI for more configuration settings.
+
+```ruby
+OandaAPI.configure do |config|
+  config.use_compression = true
+  config.use_request_rate_throttling = true
+  config.max_requests_per_second = 10
+end
+```
+
+Supported Platforms
+-------------------
+
+OandaAPI works with Ruby 2.0 and higher.
+
+Tested on:
+
+* MRI 2.1, 2.2
+* JRuby 1.7, 9.0.0.0.pre
+* Rubinius 2.4, 2.5
+
+Contributing
+------------
+
+If you'd like to contribute code or modify this gem, you can run the test suite with:
+
+```ruby
+gem install oanda_api --dev
+bundle exec rspec # or just 'rspec' may work
+```
+When you're ready to code:
+
+1. Fork this repository on github.
+2. Make your changes.
+3. Add tests where applicable and run the existing tests with `rspec` to make sure they all pass.
+4. Add new documentation where appropriate using [YARD](http://yardoc.org/) formatting.
+5. Create a new pull request and submit it to me.
+
+License
+-------
+
+Copyright (c) 2014 Dean Missikowski. Distributed under the MIT License. See
+[LICENSE](LICENSE) for further details.

data/Rakefile

@@ -0,0 +1,23 @@
+require 'bundler/gem_tasks'
+
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec) do |task|
+    task.rspec_opts = ["--color", "--format", "doc"]
+  end
+  task :default => :spec
+  task :test    => :spec
+rescue LoadError
+  # no rspec available
+end
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new do |task|
+    task.files   = ["lib/**/*.rb"]
+  end
+rescue LoadError
+  # no yard available
+end

data/lib/oanda_api.rb

@@ -0,0 +1,25 @@
+# The module that contains everything OandaAPI-related:
+require 'httparty'
+require 'persistent_httparty'
+require 'http/exceptions'
+require 'time'
+
+require_relative 'oanda_api/configuration'
+require_relative 'oanda_api/client/client'
+require_relative 'oanda_api/client/namespace_proxy'
+require_relative 'oanda_api/client/resource_descriptor'
+require_relative 'oanda_api/client/token_client'
+require_relative 'oanda_api/client/username_client'
+require_relative 'oanda_api/errors'
+require_relative 'oanda_api/resource_base'
+require_relative 'oanda_api/resource_collection'
+require_relative 'oanda_api/resource/account'
+require_relative 'oanda_api/resource/instrument'
+require_relative 'oanda_api/resource/candle'
+require_relative 'oanda_api/resource/order'
+require_relative 'oanda_api/resource/position'
+require_relative 'oanda_api/resource/price'
+require_relative 'oanda_api/resource/trade'
+require_relative 'oanda_api/resource/transaction'
+require_relative 'oanda_api/utils/utils'
+require_relative 'oanda_api/version'

data/lib/oanda_api/client/client.rb

@@ -0,0 +1,175 @@
+require 'httparty'
+require 'http/exceptions'
+
+module OandaAPI
+  # List of valid subdomains clients can access.
+  DOMAINS = [:live, :practice, :sandbox]
+
+  # Provides everything needed for accessing the API.
+  #
+  # - Uses persistant http connections.
+  # - Uses +OpenSSL::SSL::VERIFY_PEER+ to always validate SSL certificates.
+  # - Uses compression if enabled (see {Configuration#use_compression}).
+  # - Uses request rate limiting if enabled (see {Configuration#use_request_throttling}).
+  module Client
+    include HTTParty
+    persistent_connection_adapter idle_timeout: 10,
+                                  keep_alive: 30,
+                                  pool_size: 2
+
+    # Resource URI templates
+    BASE_URI = {
+      live:     "https://api-fxtrade.oanda.com/[API_VERSION]",
+      practice: "https://api-fxpractice.oanda.com/[API_VERSION]",
+      sandbox:  "http://api-sandbox.oanda.com/[API_VERSION]"
+    }
+
+    # @private
+    # Camelizes keys and transforms array values into comma-delimited strings.
+    #
+    # @return [String] a url encoded query string.
+    query_string_normalizer proc { |hash|
+      Array(hash).sort_by { |key, _value| key.to_s }.map do |key, value|
+        if value.nil?
+          Utils.camelize(key.to_s)
+        elsif value.respond_to?(:to_ary)
+          serialized = URI.encode value.join(","),
+                                  Regexp.new("[^#{URI::PATTERN::UNRESERVED}]")
+          "#{Utils.camelize(key)}=#{serialized}"
+        else
+          HashConversions.to_params Utils.camelize(key) => value
+        end
+      end.flatten.join("&")
+    }
+
+    # Returns an absolute URI for a resource request.
+    #
+    # @param [String] path the path portion of the URI.
+    #
+    # @return [String] a URI.
+    def api_uri(path)
+      uri = "#{BASE_URI[domain]}#{path}"
+      uri.sub "[API_VERSION]", OandaAPI.configuration.rest_api_version
+    end
+
+    # @private
+    # Executes an http request.
+    #
+    # @param [Symbol] method a request action. See {Client.map_method_to_http_verb}.
+    #
+    # @param [String] path the path of an Oanda resource request.
+    #
+    # @param [Hash] conditions optional parameters that are converted into
+    #   either a query string or url form encoded parameters.
+    #
+    # @return [OandaAPI::ResourceBase] if the API request returns a singular
+    #   resource. See {OandaAPI::Resource} for a list of resource types that
+    #   can be returned.
+    #
+    # @return [OandaAPI::ResourceCollection] if the API request returns a
+    #   collection of resources.
+    #
+    # @raise [OandaAPI::RequestError] if the API return code is not 2xx.
+    def execute_request(method, path, conditions = {})
+      response = Http::Exceptions.wrap_and_check do
+        method = Client.map_method_to_http_verb(method)
+        params_key = [:post, :patch, :put].include?(method) ? :body : :query
+        Client.throttle_request_rate
+        Client.send method,
+                    api_uri(path),
+                    params_key    => Utils.stringify_keys(conditions.merge(default_params)),
+                    :headers      => OandaAPI.configuration.headers.merge(headers),
+                    :open_timeout => OandaAPI.configuration.open_timeout,
+                    :read_timeout => OandaAPI.configuration.read_timeout
+      end
+
+      handle_response response, ResourceDescriptor.new(path, method)
+      rescue Http::Exceptions::HttpException => e
+        raise OandaAPI::RequestError, e.message
+    end
+
+    # @private
+    # Maps An API _action_ to a corresponding http verb.
+    #
+    # @param [Symbol] method an API action. Supported actions are:
+    #  +:create+, +:close+, +:delete+, +:get+, +:update+.
+    #
+    # @return [Symbol] an http verb.
+    def self.map_method_to_http_verb(method)
+      case method
+      when :create
+        :post
+      when :close
+        :delete
+      when :update
+        :patch
+      else
+        method
+      end
+    end
+
+    # @private
+    # Limits the execution rate of consecutive requests. Specified by
+    # {OandaAPI::Configuration#max_requests_per_second}. Only enforced
+    # if {OandaAPI::Configuration#use_request_throttling?} is enabled.
+    #
+    # @return [void]
+    def self.throttle_request_rate
+      now = Time.now
+      Thread.current[:oanda_api_last_request_at] ||= now
+      delta = now - Thread.current[:oanda_api_last_request_at]
+      _throttle(now) if delta < OandaAPI.configuration.min_request_interval &&
+                        OandaAPI.configuration.use_request_throttling?
+      Thread.current[:oanda_api_last_request_at] = Time.now
+    end
+
+    # @private
+    # The local time of the most recently throttled request.
+    #
+    # @return [Time] if any request has been throttled, the most recent time when
+    #   one was temporarily suspended.
+    #
+    # @return [nil] if a request has never been throttled.
+    def self.last_throttled_at
+      Thread.current[:oanda_api_throttled_at]
+    end
+
+    private
+
+    # @private
+    # Sleeps for the minimal amount of time required to honour the
+    # {OandaAPI::Configuration#max_requests_per_second} limit.
+    #
+    # @param [Time] time The time that the throttle was requested.
+    #
+    # @return [void]
+    def self._throttle(time)
+      Thread.current[:oanda_api_throttled_at] = time
+      sleep OandaAPI.configuration.min_request_interval
+    end
+
+    # @private
+    # Formats the response from the Oanda API into a resource object.
+    #
+    # @param [#each_pair] response a hash-like object returned by
+    #   the internal http client.
+    #
+    # @param [OandaAPI::Client::ResourceDescriptor] resource_descriptor metadata
+    #   describing the requested resource.
+    # @return [OandaAPI::ResourceBase, OandaAPI::ResourceCollection] see {#execute_request}
+    def handle_response(response, resource_descriptor)
+      if resource_descriptor.is_collection?
+        ResourceCollection.new response, resource_descriptor
+      else
+        resource_descriptor.resource_klass.new response
+      end
+    end
+
+    # @private
+    # Enables method-chaining.
+    # @return [Namespace]
+    def method_missing(sym, *args)
+      NamespaceProxy.new self, sym, args.first
+    end
+  end
+end