localbitcoins 0.0.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: f32b2111b3e627e2cdadc083e665f9d9af54d4c8
-  data.tar.gz: aaa3523f0a7c6cbb944d6047f361df38261bbbb0
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MTcyMzNjNTJjYWU2OTM0YmJhNjZlNGViM2RiYmM5ODk4ZjkxZTQ5OQ==
+  data.tar.gz: !binary |-
+    OTA5Mzk3ZGQ3MTdmYTg0ZGYxNmM2ZTU2OTYyMDI1Mjk5MDgwZjY4Ng==
 SHA512:
-  metadata.gz: f1b20d3836f2eb810bbccf0eca763dd88ee929bd456bbd25e95386b76c00fac5cdb4bb94a8149a4916f31ae47cea52de87623bf8b46f88433cabc4879d1bdc6d
-  data.tar.gz: d4e2c991028a547274adeb72c636fd1f764fcfc312f28f57a82a21e0fc07722bcf53ace2750f50a29ac5257b0f4f01323b21c482a5ce72f62eb885ad586cb656
+  metadata.gz: !binary |-
+    NzI4ZWZhMWI4YWFiNTdlYzk2Y2UwMDcxYWE4Nzc1MmE5N2NhYTU2M2Y4NTEx
+    MTQ4YjIyNThiNzVjMzY5OTFmYzFhNjM4NzBjYjBiODE1YmYxNWJhOWFiNTQ5
+    NTNjY2VhMjExYzU2MWJhMDYwZGQyNzVjZWZkOTViOTgwYTAxNWE=
+  data.tar.gz: !binary |-
+    MzYzODlmZWUyY2U3Mjg2MWFlMmI4ODRmMzE0NjhhNzc1OTRmZjMyMmE0NGVi
+    MmU0MjQyM2IxNzYzODhhZDU3YWU2ZmI2ZWEwNGE1Y2UzNGVjMTEwNGMwODc0
+    ZTU0MmJmMmIwOWYzYzgyNzM3NDdhYmIyOTdjOTc4ZTNiNDgzMjk=

data/.gitignore

@@ -23,3 +23,5 @@ doc/
 
 # Gems
 *.gem
+
+.idea/

data/Gemfile.lock

@@ -5,36 +5,33 @@ PATH
       activesupport (~> 3)
       hashie (~> 2.0.2)
       json (~> 1.8.0)
-      oauth2 (~> 0.9.2)
+      oauth2 (~> 0.9.4)
       rest-client (~> 1.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (3.2.13)
-      i18n (= 0.6.1)
+    activesupport (3.2.18)
+      i18n (~> 0.6, >= 0.6.4)
       multi_json (~> 1.0)
     addressable (2.3.5)
     crack (0.4.0)
       safe_yaml (~> 0.9.0)
     diff-lcs (1.2.4)
-    faraday (0.8.7)
-      multipart-post (~> 1.1)
+    faraday (0.9.0)
+      multipart-post (>= 1.2, < 3)
     hashie (2.0.5)
-    httpauth (0.2.0)
-    i18n (0.6.1)
-    json (1.8.0)
-    jwt (0.1.8)
-      multi_json (>= 1.5)
-    mime-types (1.23)
-    multi_json (1.7.7)
-    multi_xml (0.5.4)
-    multipart-post (1.2.0)
-    oauth2 (0.9.2)
-      faraday (~> 0.8)
-      httpauth (~> 0.2)
-      jwt (~> 0.1.4)
-      multi_json (~> 1.0)
+    i18n (0.6.9)
+    json (1.8.1)
+    jwt (1.0.0)
+    mime-types (2.3)
+    multi_json (1.10.1)
+    multi_xml (0.5.5)
+    multipart-post (2.0.0)
+    oauth2 (0.9.4)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 1.0)
+      multi_json (~> 1.3)
       multi_xml (~> 0.5)
       rack (~> 1.2)
     rack (1.5.2)

data/README.md

@@ -1,8 +1,8 @@
-# LocalBitcoins API Gem 0.0.3
+# LocalBitcoins API Gem 1.0.0
 
 This gem provides a simple, extensible Ruby wrapper to access the [LocalBitcoins API](https://localbitcoins.com/api-docs/).
 
-## Installation
+## Installation & Setup 
 
 Install the gem:
 ```
@@ -11,22 +11,36 @@ gem install localbitcoins
 
 Or include it in your Gemfile:
 ```
-gem 'openlibrary'
+gem 'localbitcoins'
 ```
 
-## Setting Up Your OAuth Client 
+You can use the gem with or without OAuth2 for authentication. Without authentication the API only allows access to the public endpoints documented [here (Ad Listings)](https://localbitcoins.com/api-docs/public/) and [here (Market Data)](https://localbitcoins.com/api-docs/#toc7)
 
-First, you need to [register your application](https://localbitcoins.com/accounts/api/) with LocalBitcoins to get your API keys. You will get a Client ID and a Client Secret, which you will use to get your OAuth access token. An OAuth access token is required for all requests to the LocalBitcoins API. 
+### Setting Up The Client 
 
-There are a number of ways to implement OAuth, and it is largely left up to you to decide how to do it. If you've never used OAuth before, reading [this tutorial](http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified) is a good place to start!
+For authenticated requests to the LocalBitcoins API, you must [register your application](https://localbitcoins.com/accounts/api/) and get your API credentials. Use the Client ID and Client Secret to receive an access token via OAuth2. There are a number of ways to implement OAuth2, and it is largely left up to you to decide how to do it. If you've never used OAuth2 before, reading [this tutorial](http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified) is a good place to start!
 
-Once you have your token, you can set up your client with the following code:
+Once you have your token, you can get to setting up the LocalBitcoins client.
 
 ``` ruby
+# Authenticated
+
 # long version
-client = LocalBitcoins::Client.new(oauth_token: 'OAUTH_TOKEN')
-# short version
-client = LocalBitcoins.new(oauth_token: 'OAUTH_TOKEN')
+client = LocalBitcoins::Client.new(
+  client_id:     'CLIENT_ID',
+  client_secret: 'CLIENT_SECRET',
+  oauth_token:   'OAUTH_TOKEN'
+)
+# slightly shorter version
+client = LocalBitcoins.new(
+  client_id:     'CLIENT_ID',
+  client_secret: 'CLIENT_SECRET',
+  oauth_token:   'OAUTH_TOKEN'
+)
+
+# Unauthenticated
+client = LocalBitcoins.new
+
 ```
 
 ### Global Configuration
@@ -36,12 +50,12 @@ To make things easier, you can define your client credentials at a global level:
 ``` ruby
 # Set the configuration
 LocalBitcoins.configure(
-  client_id: 'ID',
-  client_secret: 'SECRET'
+  client_id: 'CLIENT_ID',
+  client_secret: 'CLIENT_SECRET'
 )
 
 # Get the configuration
-LocalBitcoins.configuration # => { client_id => 'ID', client_secret => 'SECRET' }
+LocalBitcoins.configuration # => { client_id => 'CLIENT_ID', client_secret => 'CLIENT_SECRET' }
 
 # Reset the configuration
 LocalBitcoins.reset_configuration
@@ -55,47 +69,317 @@ There are several ways to solve the problem of keeping your credentials secret.
 
 ## Usage
 
-You can get a list of the token owner's releaseable escrows through the OAuth client. You can also use the client to release an escrow.
+Nearly every endpoint found in both the [logged in](https://localbitcoins.com/api-docs) and [public](https://localbitcoins.com/api-docs/public/) documentation is supported by this gem.
+
+### Ads
 
-### View Releaseable Escrows
+Return a list of the token owner's ads with the following method:
 
 ``` ruby
-escrows = client.escrows
+ads = client.ads
 
-escrows.escrow_list.each do |e|
-  e.data.created_at     # => UTC datetime escrow was created at
-  e.data.buyer_username # => username of the buyer
-  e.data.reference_code # => reference code for the escrow
-  
-  e.actions.release_url # => url to release to escrow
+ads.ad_list.each do |a|
+  a.data.visible    # => boolean value of the ad's visibility
+  a.data.email      # => valid e-mail string or null
+  a.data.location_string # => human-readable location
+  # and many more pieces of data!
 end
 ```
+Create a new ad for the token owner:
+
+``` ruby
+# - Required fields -
+# min_amount                - minimum amount for sale in fiat [string]
+# max_amount                - maximum amount for sale in fiat [string]
+# price_equation            - price using price equation operators [string]
+# lat                       - latitude of location [float]
+# lon                       - longitude of location [float]
+# city                      - city of listing [string]
+# location_string           - text representation of location [string]
+# countrycode               - two letter countrycode [string]
+# account_info              - [string]
+# bank_name                 - [string]
+# sms_verification_required - only receive contacts with verified phone numbers [boolean]
+# track_max_amount          - decrease max sell amount in relation to liquidity [boolean]
+# trusted_required          - only allow trusted contacts [boolean]
+# currency                  - three letter fiat representation [string]
+#
+# pass a hash of the above fields
+# returns a message on success
+client.create_ad(params)
+```
 
-Use the release_url from `escrows` method in the `escrow_release` method below:
+Update existing ad for the token owner.
 
-### Release An Escrow
+``` ruby
+# - Required Fields -
+# id             - id of the ad you want to update
+# visibility     - the ad's visibility [boolean]
+# price_equation - equation to calculate price [string]
+#
+# NOTE 1: Setting min_amount or max_amount to nil will unset them.
+# NOTE 2: "Floating price" must be false in you ad's edit form for price_equation to go through
+#
+# pass a hash of the above fields, plus any other editable fields
+# returns a message on success
+client.update_ad(id,params)
+``` 
+
+List of ads from a comma separated string of ids
+``` ruby
+# pass a comma separated string of ids
+ads = client.ad_list("12345,123456,1234567")
+``` 
+Gets a single ad from its id
+
+``` ruby
+ad = client.ad(12345)
+```
+### Escrows
+
+View token owner's releasable escrows
+NOTE: This endpoint is not documented by LocalBitcoins and may or may not work.
+``` ruby
+escrows = client.escrows
+# escrows are listed in escrows.escrow_list
+```
+Release an escrow
 
 ``` ruby
+# pass the id of the contact which the escrow is associated with
 # returns a complimentary message if the escrow successfully released
-release = client.escrow_release(release_url)
+release = client.escrow_release(contact_id)
 ```
 
-### List Ads
+### Contacts
 
-You can get a list of the token owner's ads with the following method:
+List of active contacts
+``` ruby
+# This method can filter contacts by contact_type, which can be "buyer" or "seller"
+#
+# buyers and sellers
+contacts = client.active_contacts
+# buyers only
+contacts = client.active_contacts('buyer')
+# sellers only 
+contacts = client.active_contacts('seller')
+```
 
+Released, canceled, and closed contacts have their own methods as well, which can be filtered the same as above.
 ``` ruby
-ads = client.ads
+released = client.released_contacts
+closed = client.closed_contacts
+canceled = client.canceled_contacts
+``` 
 
-ads.ad_list.each do |a|
-  a.data.visible    # => boolean value of the ad's visibility
-  a.data.email      # => valid e-mail string or null
-  a.data.location_string # => human-readable location
-  # and many more pieces of data!
-end
+Get a contact based on the id
+``` ruby
+released = client.released_contacts
+closed = client.closed_contacts
+canceled = client.canceled_contacts
+``` 
+
+Get a contact based on the id
+``` ruby
+contact = client.contact_info(1234)
+```
+
+Get a list of contacts from a comma separated string of ids
+``` ruby
+contacts = client.contacts_info("1234,12345,1234567")
+# access list at contacts.contact_list
 ```
 
-For a full list of info you can get with this method, view the [API documentation](https://localbitcoins.com/api-docs/).
+Create a new contact for the token owner
+``` ruby
+client.create_contact(ad_id, amount, message)
+```
+
+Fund an active contact for the token owner
+``` ruby
+client.fund_contact(contact_id)
+```
+
+Cancel an active contact for the token owner
+``` ruby
+client.cancel_contact(contact_id)
+```
+
+Initiate a dispute with on a contact for the token owner
+``` ruby
+client.dispute_contact(contact_id)
+```
+
+Send a message to a contact for the token owner
+``` ruby
+client.message_contact(contact_id, message)
+```
+
+Return all messages from a contact
+``` ruby
+messages = client.messages_from_contact(contact_id)
+```
+
+Mark a contact as paid for the token owner
+``` ruby
+client.mark_contact_as_paid(contact_id)
+```
+
+### Users
+
+Return info on the token owner
+``` ruby
+myself = client.myself
+```
+
+Return an account based on the username.
+``` ruby
+user = client.account_info(username)
+```
+
+Immediately expire the currently authorized access_token.
+NOTE: This method may not work. We're looking into it.
+``` ruby
+client.logout
+```
+
+### Wallet
+
+Return info on the token owner's wallet
+``` ruby
+wallet = client.wallet
+```
+
+Return the token owner's wallet balance
+``` ruby
+balance = client.wallet_balance
+```
+
+Return the address of the token owner's wallet
+``` ruby
+address = client.wallet_addr
+```
+
+Send bitcoin from the token owner's wallet
+``` ruby
+# returns message on success
+client.wallet_send(address, amount)
+```
+NOTE: The LocalBitcoins documentation does not specify where pins can be acquired, though use of a pin requires the 'money_pin' token scope.
+
+Send bitcoin from token owner's wallet using pin code
+``` ruby
+#returns message no success
+client.wallet_pin_send(address, amount, pin)
+```
+
+Check if a pin is valid
+``` ruby
+client.valid_pin?(pin)
+```
+
+## Public API
+
+### Markets
+Return a ticker of bitcoin prices in various currencies.
+``` ruby
+ticker = client.ticker
+```
+
+Return a batch of 500 trades in the specifed currency
+``` ruby
+# currency is the 3 letter currency code
+trades = client.trades(currency)
+
+# since is an optional trade id - will return the next 500 trades after the specifed id
+trades = client.trades(currency, 12345) 
+```
+
+Return the LocalBitcoins online orderbook ( Bids and Asks ) in a specified currency
+``` ruby
+# currency is the 3 letter currency code
+orderbook = client.orderbook(currency)
+```
+
+### Ad Listings
+
+Return a list of online buy ads pertaining to specified parameters
+``` ruby
+# Accepts a hash of parameters, with a valid subset of the following keys: countrycode, currency, country_name, payment_method
+#
+# Valid API endpoints include:
+# /buy-bitcoins-online/{countrycode}/{country_name}/{payment_method}/.json
+# /buy-bitcoins-online/{countrycode}/{country_name}/.json
+# /buy-bitcoins-online/{currency}/{payment_method}/.json
+# /buy-bitcoins-online/{currency}/.json
+# /buy-bitcoins-online/{payment_method}/.json
+# /buy-bitcoins-online/.json
+#
+# NOTE: countrycode must be 2 characters and currency must be 3 characters
+online_buy_ads_lookup = client.online_buy_ads_lookup(params)
+```
+
+Return a list of online sell ads pertaining to specified parameters
+``` ruby
+# Accepts a hash of parameters, with a valid subset of the following keys: countrycode, currency, country_name, payment_method
+#
+# NOTE: see valid API endpoints in online_buy_ads_lookup method above
+online_sell_ads_lookup = client.online_sell_ads_lookup(params)
+```
+
+Returns a list of local buy ads in a certain place
+``` ruby
+# - Required fields -
+# location_id               - id for location found using places method
+# location_slug             - slug name for location found using places method
+#
+# - Optional fields -
+# lat                       - latitude of location [float]
+# lon                       - longitude of location [float]
+#
+# pass a hash of the above fields
+local_buy_ad = client.local_buy_ad(params)
+```
+
+Return a list of local sell ads in a certain place
+``` ruby
+# pass a hash with the same fields as local_buy_ad
+local_sell_ad = client.local_sell_ad(params)
+```
+
+### Additional Public Methods
+
+Return all payment methods accepted on LocalBitcoins, with an option to limit the search to a specific country
+``` ruby
+# countrycode is the 2 character countrycode
+payment_methods = client.payment_methods(countrycode)
+```
+
+Return all currencies accepted by the LocalBitcoins platform
+``` ruby
+currencies = client.currencies
+```
+
+Return information about the place at or near a specified latitude and longitude
+``` ruby
+# - Required fields -
+# lat                       - latitude of location [float]
+# lon                       - longitude of location [float]
+#
+# - Optional fields -
+# countrycode               - 2 letter countrycode
+# location_string           - location name in string form
+#
+# pass a hash of the above fields
+places = client.places(params)
+```
+
+## Contributors
+
+* [John Shutt](http://shutt.in)
+* [Will Newman](http://willnewman.me)
+* [Albert Brown](https://www.linkedin.com/pub/albert-brown/36/515/a2)
+* [Coincove](https://coincove.co)
 
 ## License
 

data/Rakefile

@@ -2,7 +2,7 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new('spec')
 
-RSpec::Core::RakeTask.new(:test) do |t|
+  RSpec::Core::RakeTask.new(:test) do |t|
   t.pattern = 'spec/*_spec.rb'
   t.verbose = false
 end

data/lib/localbitcoins/client/ads.rb

@@ -1,24 +1,60 @@
 module LocalBitcoins
   module Ads
     # Get a list of the token owner's ads
-    #
-    def ads()
-      data = oauth_request(:get, '/api/ads')
-      Hashie::Mash.new(data['ad_list'])
+    def ads
+      oauth_request(:get, '/api/ads/').data
     end
 
     # Update one of the token owner's ads
     #
     # id             - id of the ad you want to update
     # visibility     - the ad's visibility [boolean]
-    # min_amount     - minimum selling price [string or nil]
-    # max_amount     - maximum buying price [string or nil]
+    # min_amount     - minimum selling price [string]
+    # max_amount     - maximum buying price [string]
     # price_equation - equation to calculate price [string]
     #
-    # NOTE: Omitting min_amount or max_amount will unset them.
+    # NOTE 1: Setting min_amount or max_amount to nil will unset them.
+    # NOTE 2: "Floating price" must be false in you ad's edit form for price_equation to go through
+    #
+    def update_ad(id, params={})
+      old_ad = ad(id).data
+      updated_params = {
+          :min_amount => old_ad.min_amount,
+          :max_amount => old_ad.max_amount,
+          :visible    => old_ad.visible
+      }.merge(params)
+      oauth_request(:post, "/api/ad/#{id}/", updated_params).data
+    end
+
+    # Create a new ad for the token owner
+    #
+    # - Required fields -
+    # min_amount                - minimum amount for sale in fiat [string]
+    # max_amount                - maximum amount for sale in fiat [string]
+    # price_equation            - price using price equation operators [string]
+    # lat                       - latitude of location [float]
+    # lon                       - longitude of location [float]
+    # city                      - city of listing [string]
+    # location_string           - text representation of location [string]
+    # countrycode               - two letter countrycode [string]
+    # account_info              - [string]
+    # bank_name                 - [string]
+    # sms_verification_required - only receive contacts with verified phone numbers [boolean]
+    # track_max_amount          - decrease max sell amount in relation to liquidity [boolean]
+    # trusted_required          - only allow trusted contacts [boolean]
+    # currency                  - three letter fiat representation [string]
     #
-    def update_ad(id, visibility, min_amount, max_amount, price_equation)
-      # Can't use this method until the Ads API is complete!
+    def create_ad(params={})
+      oauth_request(:post, '/api/ad-create/', params).data
+    end
+
+    # ads - comma separated list of ad ids [string]
+    def ad_list(ads)
+      oauth_request(:get, "/api/ad-get/", {:ads=>ads}).data
+    end
+
+    def ad(ad_id)
+      oauth_request(:get, "/api/ad-get/#{ad_id}/").data.ad_list[0]
     end
   end
 end

data/lib/localbitcoins/client/contacts.rb

@@ -0,0 +1,66 @@
+module LocalBitcoins
+  module Contacts
+    # Contact interaction endpoints
+    # contact_id - id number associated with the contact
+
+    def mark_contact_as_paid(contact_id)
+      oauth_request(:post, "/api/contact_mark_as_paid/#{contact_id}/")
+    end
+
+    def messages_from_contact(contact_id)
+      oauth_request(:get, "/api/contact_messages/#{contact_id}/").data
+    end
+
+    def message_contact(contact_id, msg)
+      oauth_request(:post, "/api/contact_message_post/#{contact_id}/", {:msg=>msg}).data
+    end
+
+    def dispute_contact(contact_id)
+      oauth_request(:post, "/api/contact_dispute/#{contact_id}/")
+    end
+
+    def cancel_contact(contact_id)
+      oauth_request(:post, "/api/contact_cancel/#{contact_id}/").data
+    end
+
+    def fund_contact(contact_id)
+      oauth_request(:post, "/api/contact_fund/#{contact_id}/")
+    end
+
+    def create_contact(ad_id, amount, message=nil)
+      oauth_request(:post, "/api/contact_create/#{ad_id}/", {:amount=>amount, :message=>message})
+    end
+
+    def contact_info(contact_id)
+      oauth_request(:get, "/api/contact_info/#{contact_id}/")
+    end
+
+    # contacts - comma separated list of contact ids [string]
+    def contacts_info(contacts)
+      oauth_request(:get, '/api/contact_info/', {:contacts=>contacts}).data
+    end
+
+    # Dashboard contact endpoints
+    # contact_type - optional filter 'buyer' or 'seller' [string]
+    #
+    def active_contacts(contact_type = nil)
+      contact_type<<'/' unless contact_type.nil?
+      oauth_request(:get, "/api/dashboard/#{contact_type}").data
+    end
+
+    def released_contacts(contact_type = nil)
+      contact_type<<'/' unless contact_type.nil?
+      oauth_request(:get, "/api/dashboard/released/#{contact_type}").data
+    end
+
+    def canceled_contacts(contact_type = nil)
+      contact_type<<'/' unless contact_type.nil?
+      oauth_request(:get, "/api/dashboard/canceled/#{contact_type}").data
+    end
+
+    def closed_contacts(contact_type = nil)
+      contact_type<<'/' unless contact_type.nil?
+      oauth_request(:get, "/api/dashboard/closed/#{contact_type}").data
+    end
+  end
+end

data/lib/localbitcoins/client/escrows.rb

@@ -1,21 +1,17 @@
 module LocalBitcoins
   module Escrows
     # Get a list of the token owner's releaseable escrows 
-    #
-    def escrows()
-      data = oauth_request(:get, '/api/escrows')
-      Hashie::Mash.new(data)
+    # NOTE: This endpoint is not documented so it may or may not work
+    def escrows
+      oauth_request(:get, '/api/escrows/').data
     end
 
     # Release an escrow
-    #
-    # release_url => the url of the escrow you want to release, 
-    #                probably found by running the `escrows`
-    #                method above
-    #
-    def escrow_release(release_url)
-      data = oauth_request(:post, release_url)
-      data['data']['message']
+    # id - the contact number
+    # NOTE: LocalBitcoins documentation calls this the "escrow_id",
+    # it is actually just the contact number the escrow is associated with
+    def escrow_release(id)
+      oauth_request(:post, "/api/escrow_release/#{id}/").data
     end
   end
 end