coinbase 0.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: fd20c87743ea6c8d95575db35841ffd10b1dc87376d9d1e2e08803998b8322e8
-  data.tar.gz: 475ac4213ae2e15c5ea5002441302faa908524ccb067e7a0ce99194d15c5b049
+SHA1:
+  metadata.gz: 1f6f837948954a200e21988327ab19e83bacde78
+  data.tar.gz: e15a00800ff4529c813ceb1a981195d4e5d3fd1b
 SHA512:
-  metadata.gz: 94fadca140def76fb428a824eca188f3eaa77388963f59ec04d70adfc1c1ccf2002c8af791bfc84bb7d83b07753b83fc755cec3af149e6c4549d51c594490ba6
-  data.tar.gz: 8d04ee71428ee01611445c71f7642a205493e4a12f365826726132fc5fc783015e7aaa7e98e3813da924c914336bc51592198b6e0b3cc77b4e7e0d2226fdc655
+  metadata.gz: def938226ec7c66dbd960c38a2bd12a8a07230bb68d26e97d17c35342e3000e9eeafaf6c1949f6df8e0be15e6547ca6dfdd636fdc0d8cae50484bf1d9dec1bd9
+  data.tar.gz: 4445e6a817be9f527da079471a9c1afeab4a141750834f9aa30fa0fc24ac4361d23462787b3a374b2061386b306a7dd6330c5410c53b12fe03da906c0ca6e1c3

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+test/tmp
+test/version_tmp
+tmp
+.tddium*

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - jruby-19mode
+  - rbx-19mode

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in coinbase-ruby.gemspec 
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Coinbase
+
+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,330 @@
+# Coinbase
+
+An easy way to buy, send, and accept [bitcoin](http://en.wikipedia.org/wiki/Bitcoin) through the [Coinbase API](https://coinbase.com/docs/api/overview).
+
+This gem is a wrapper around the [Coinbase JSON API](https://coinbase.com/api/doc). It supports both the the [api key + secret authentication method](https://coinbase.com/docs/api/authentication) as well as OAuth 2.0 for performing actions on other people's account.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'coinbase'
+
+Then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install coinbase
+
+## Usage
+
+### HMAC Authentication (for accessing your own account)
+
+Start by [enabling an API Key on your account](https://coinbase.com/settings/api)
+
+Next, create an instance of the client and pass it your API Key + Secret as parameters.
+
+```ruby
+coinbase = Coinbase::Client.new(ENV['COINBASE_API_KEY'], ENV['COINBASE_API_SECRET'])
+```
+
+### OAuth 2.0 Authentication (for accessing others' accounts)
+
+Start by [creating a new OAuth 2.0 application](https://coinbase.com/oauth/applications)
+
+```ruby
+# Obtaining the OAuth credentials is outside the scope of this gem
+user_credentials = {
+	:access_token => 'access_token',
+	:refresh_token => 'refresh_token',
+	:expires_at => Time.now + 1.day
+}
+coinbase = Coinbase::OAuthClient.new(ENV['COINBASE_CLIENT_ID'], ENV['COINBASE_CLIENT_SECRET'], user_credentials)
+```
+
+Notice here that we did not hard code the API keys into our codebase, but set it in an environment variable instead. This is just one example, but keeping your credentials separate from your code base is a good [security practice](https://coinbase.com/docs/api/authentication#security).
+
+Now you can call methods on `coinbase` similar to the ones described in the [api reference](https://coinbase.com/api/doc).  For example:
+
+```ruby
+coinbase.balance
+=> #<Money fractional:20035300000 currency:BTC>
+coinbase.balance.format
+=> "200.35300000 BTC"
+coinbase.balance.to_d
+=> #<BigDecimal:7ff36b091670,'0.200353E3',18(54)>
+coinbase.balance.to_s
+=> 200.35300000 # BTC amount
+```
+
+[Money objects](https://github.com/RubyMoney/money) are returned for most amounts dealing with currency.  You can call `to_d`, `format`, or perform math operations on money objects.
+
+## Examples
+
+### Check your balance
+
+```ruby
+coinbase.balance.to_s
+=> "200.35300000" # BTC amount
+```
+
+### Send bitcoin
+
+```ruby
+r = coinbase.send_money 'user@example.com', 1.23
+r.success?
+=> true
+r.transaction.status
+=> 'pending' # this will change to 'complete' in a few seconds if you are sending coinbase-to-coinbase, otherwise it will take about 1 hour, 'complete' means it cannot be reversed or canceled
+r.transaction.id
+=> '501a1791f8182b2071000087'
+r.transaction.recipient.email
+=> 'user@example.com'
+r.to_hash
+=> ... # raw hash response
+```
+
+You can also send money in [a number of currencies](https://github.com/coinbase/coinbase-ruby/blob/master/supported_currencies.json).  The amount will be automatically converted to the correct BTC amount using the current exchange rate.
+
+```ruby
+r = coinbase.send_money 'user@example.com', 1.23.to_money('AUS')
+r.transaction.amount.format
+=> "0.06713955 BTC"
+```
+
+The first parameter can also be a bitcoin address and the third parameter can be a note or description of the transaction.  Descriptions are only visible on Coinbase (not on the general bitcoin network).
+
+```ruby
+r = coinbase.send_money 'mpJKwdmJKYjiyfNo26eRp4j6qGwuUUnw9x', 2.23.to_money("USD"), "thanks for the coffee!"
+r.transaction.recipient_address
+=> "mpJKwdmJKYjiyfNo26eRp4j6qGwuUUnw9x"
+r.transaction.notes
+=> "thanks for the coffee!"
+```
+
+### Request bitcoin
+
+This will send an email to the recipient, requesting payment, and give them an easy way to pay.
+
+```ruby
+r = coinbase.request_money 'client@example.com', 50, "contractor hours in January (website redesign for 50 BTC)"
+r.transaction.request?
+=> true
+r.transaction.id
+=> '501a3554f8182b2754000003'
+r = coinbase.resend_request '501a3554f8182b2754000003'
+r.success?
+=> true
+r = coinbase.cancel_request '501a3554f8182b2754000003'
+r.success?
+=> true
+# from the other account
+r = coinbase.complete_request '501a3554f8182b2754000003'
+r.success?
+=> true
+```
+
+### List your current transactions
+
+Sorted in descending order by timestamp, 30 per page.  You can pass an integer as the first param to page through results, for example `coinbase.transactions(2)`.
+
+```ruby
+r = coinbase.transactions
+r.current_page
+=> 1
+r.num_pages
+=> 7
+r.transactions.collect{|t| t.transaction.id }
+=> ["5018f833f8182b129c00002f", "5018f833f8182b129c00002e", ...]
+r.transactions.collect{|t| t.transaction.amount.format }
+=> ["-1.10000000 BTC", "42.73120000 BTC", ...]
+```
+
+Transactions will always have an `id` attribute which is the primary way to identity them through the Coinbase api.  They will also have a `hsh` (bitcoin hash) attribute once they've been broadcast to the network (usually within a few seconds).
+
+### Get transaction details
+
+This will fetch the details/status of a transaction that was made within Coinbase or outside of Coinbase
+
+```ruby
+r = coinbase.transaction '5011f33df8182b142400000e'
+r.transaction.status
+=> 'pending'
+r.transaction.recipient_address
+=> 'mpJKwdmJKYjiyfNo26eRp4j6qGwuUUnw9x'
+```
+
+### Check bitcoin prices
+
+Check the buy or sell price by passing a `quantity` of bitcoin that you'd like to buy or sell. This price includes Coinbase's fee of 1% and the bank transfer fee of $0.15.
+
+The `buy_price` and `sell_price` per Bitcoin will increase and decrease respectively as `quantity` increases. This [slippage](http://en.wikipedia.org/wiki/Slippage_(finance)) is normal and is influenced by the [market depth](http://en.wikipedia.org/wiki/Market_depth) on the exchanges we use.
+
+```ruby
+coinbase.buy_price(1).format
+=> "$17.95"
+coinbase.buy_price(30).format
+=> "$539.70"
+```
+
+
+```ruby
+coinbase.sell_price(1).format
+=> "$17.93"
+coinbase.sell_price(30).format
+=> "$534.60"
+```
+
+Check the spot price of Bitcoin in a given `currency`. This is usually somewhere in between the buy and sell price, current to within a few minutes and does not include any Coinbase or bank transfer fees. The default currency is USD.
+
+```ruby
+coinbase.spot_price.format
+=> "$431.42"
+coinbase.spot_price('EUR').format
+=> "€307,40"
+```
+
+### Buy or Sell bitcoin
+
+Buying and selling bitcoin requires you to [add a payment method](https://coinbase.com/buys) through the web app first.
+
+Then you can call `buy!` or `sell!` and pass a `quantity` of bitcoin you want to buy (as a float or integer).
+
+```ruby
+r = coinbase.buy!(1)
+r.transfer.code
+=> '6H7GYLXZ'
+r.transfer.btc.format
+=> "1.00000000 BTC"
+r.transfer.total.format
+=> "$17.95"
+r.transfer.payout_date
+=> 2013-02-01 18:00:00 -0800
+```
+
+
+```ruby
+r = coinbase.sell!(1)
+r.transfer.code
+=> 'RD2OC8AL'
+r.transfer.btc.format
+=> "1.00000000 BTC"
+r.transfer.total.format
+=> "$17.93"
+r.transfer.payout_date
+=> 2013-02-01 18:00:00 -0800
+```
+
+### Listing Buy/Sell History
+
+You can use `transfers` to view past buys and sells.
+
+```ruby
+r = coinbase.transfers
+r.current_page
+ => 1 
+r.total_count
+ => 7 
+r.transfers.collect{|t| t.transfer.type }
+=> ["Buy", "Buy", ...] 
+r.transfers.collect{|t| t.transfer.btc.amount }
+=> [0.01, 0.01, ...] 
+r.transfers.collect{|t| t.transfer.total.amount }
+=> [5.72, 8.35, ...] 
+```
+
+### Create a payment button
+
+This will create the code for a payment button (and modal window) that you can use to accept bitcoin on your website.  You can read [more about payment buttons here and try a demo](https://coinbase.com/docs/merchant_tools/payment_buttons).
+
+The method signature is `def create_button name, price, description=nil, custom=nil, options={}`.  The `custom` param will get passed through in [callbacks](https://coinbase.com/docs/merchant_tools/callbacks) to your site.  The list of valid `options` [are described here](https://coinbase.com/api/doc/1.0/buttons/create.html).
+
+```ruby
+r = coinbase.create_button "Your Order #1234", 42.95.to_money('EUR'), "1 widget at €42.95", "my custom tracking code for this order"
+r.button.code
+=> "93865b9cae83706ae59220c013bc0afd"
+r.embed_html
+=> "<div class=\"coinbase-button\" data-code=\"93865b9cae83706ae59220c013bc0afd\"></div><script src=\"https://coinbase.com/assets/button.js\" type=\"text/javascript\"></script>"
+```
+
+### Create an order for a button
+
+This will generate an order associated with a button. You can read [more about creating an order for a button here](https://coinbase.com/api/doc/1.0/buttons/create_order.html).
+
+```ruby
+r = coinbase.create_order_for_button "93865b9cae83706ae59220c013bc0afd"
+=> "{\"success\"=>true, \"order\"=>{\"id\"=>\"ASXTKPZM\", \"created_at\"=>\"2013-12-13T01:36:47-08:00\", \"status\"=>\"new\", \"total_btc\"=>{\"cents\"=>6859115, \"currency_iso\"=>\"BTC\"}, \"total_native\"=>{\"cents\"=>4295, \"currency_iso\"=>\"EUR\"}, \"custom\"=>\"my custom tracking code for this order\", \"receive_address\"=>\"mpJKwdmJKYjiyfNo26eRp4j6qGwuUUnw9x\", \"button\"=>{\"type\"=>\"buy_now\", \"name\"=>\"Your Order #1234\", \"description\"=>\"1 widget at 42.95\", \"id\"=>\"93865b9cae83706ae59220c013bc0afd\"}, \"transaction\"=>nil}}"
+```
+
+### Create a new user
+
+```ruby
+r = coinbase.create_user "newuser@example.com", "some password"
+r.user.email
+=> "newuser@example.com"
+r.receive_address
+=> "mpJKwdmJKYjiyfNo26eRp4j6qGwuUUnw9x"
+```
+
+A receive address is returned also in case you need to send the new user a payment right away.
+
+You can optionally pass in a client_id parameter that corresponds to your OAuth2 application and an array of permissions. When these are provided, the generated user will automatically have the permissions you’ve specified granted for your application. See the [API Reference](https://coinbase.com/api/doc/1.0/users/create.html) for more details.
+
+```ruby
+r = coinbase.create_user "newuser@example.com", "some password", client_id, ['transactions', 'buy', 'sell']
+r.user.email
+=> "newuser@example.com"
+r.receive_address
+=> "mpJKwdmJKYjiyfNo26eRp4j6qGwuUUnw9x"
+r.oauth.access_token
+=> "93865b9cae83706ae59220c013bc0afd93865b9cae83706ae59220c013bc0afd"
+```
+
+## Adding new methods
+
+You can see a [list of method calls here](https://github.com/coinbase/coinbase-ruby/blob/master/lib/coinbase/client.rb) and how they are implemented.  They are a wrapper around the [Coinbase JSON API](https://coinbase.com/api/doc).
+
+If there are any methods listed in the [API Reference](https://coinbase.com/api/doc) that haven't been added to the gem yet, you can also call `get`, `post`, `put`, or `delete` with a `path` and optional `params` hash for a quick implementation.  The raw response will be returned. For example:
+
+```ruby
+coinbase.get('/account/balance').to_hash
+=> {"amount"=>"50.00000000", "currency"=>"BTC"}
+```
+
+Or feel free to add a new wrapper method and submit a pull request.
+
+## Security Notes
+
+If someone gains access to your API Key they will have complete control of your Coinbase account.  This includes the abillity to send all of your bitcoins elsewhere.
+
+For this reason, API access is disabled on all Coinbase accounts by default.  If you decide to enable API key access you should take precautions to store your API key securely in your application.  How to do this is application specific, but it's something you should [research](http://programmers.stackexchange.com/questions/65601/is-it-smart-to-store-application-keys-ids-etc-directly-inside-an-application) if you have never done this before.
+
+## Decimal precision
+
+This gem relies on the [Money](https://github.com/RubyMoney/money) gem, which by default uses the [BigDecimal](www.ruby-doc.org/stdlib-2.0/libdoc/bigdecimal/rdoc/BigDecimal.html) class for arithmetic to maintain decimal precision for all values returned.
+
+When working with currency values in your application, it's important to remember that floating point arithmetic is prone to [rounding errors](http://en.wikipedia.org/wiki/Round-off_error). 
+
+For this reason, we provide examples which use BigDecimal as the preferred way to perform arithmetic:
+
+```coinbase.balance.to_d
+=> #<BigDecimal:7ff36b091670,'0.200353E3',18(54)>
+```
+
+## Testing
+
+If you'd like to contribute code or modify this gem, you can run the test suite with:
+
+```ruby
+gem install coinbase --dev
+bundle exec rspec # or just 'rspec' may work
+```
+
+## Contributing
+
+1. Fork this repo and make changes in your own copy
+2. Add a test if applicable and run the existing tests with `rspec` to make sure they pass
+3. Commit your changes and push to your fork `git push origin master`
+4. Create a new pull request and submit it back to us!

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/coinbase.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'coinbase/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "coinbase"
+  gem.version       = Coinbase::VERSION
+  gem.authors       = ["Brian Armstrong"]
+  gem.email         = [""]
+  gem.description   = ["An easy way to buy, send, and accept bitcoin."]
+  gem.summary       = ["An easy way to buy, send, and accept bitcoin."]
+  gem.homepage      = "https://coinbase.com/api/doc"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+
+  # Gems that must be intalled for sift to compile and build
+  gem.add_development_dependency "rspec", "~> 2.12"
+  gem.add_development_dependency "fakeweb", "~> 1.3.0"
+  gem.add_development_dependency "rake"
+
+  # Gems that must be intalled for sift to work
+  gem.add_dependency "httparty", ">= 0.8.3"
+  gem.add_dependency "multi_json", ">= 1.3.4"
+  gem.add_dependency "money", "~> 6.0"
+  gem.add_dependency "monetize", "~> 0.3.0"
+  gem.add_dependency "hashie", ">= 1.2.0"
+  gem.add_dependency "oauth2", "~> 0.9"
+end