search

coinbase / coinbase-exchange-ruby

DEPRECATED — Official Ruby library for the GDAX API
Apache License 2.0
123 stars 100 forks source link

readme

Coinbase Pro Ruby library

Note: This library isn't actively maintained. Please refer to the Node.js client library for an up-to-date client implementation.

REST Client

We provide an exchange client that is a thin wrapper over the exchange API. The purpose of this Readme is to provide context for using the gem effectively. For a detailed overview of the information that's available through the API, we recommend consulting the official documentation.

We provide a synchronous and asynchronous client. The only functional difference between the two clients is that the asynchronous client must be started inside the Eventmachine reactor loop.

Synchronous Client

require 'coinbase/exchange'

rest_api = Coinbase::Exchange::Client.new(api_key, api_secret, api_pass)
while true
  sleep 10
  rest_api.last_trade(product_id: "BTC-GBP") do |resp|
    p "Spot Rate: £ %.2f" % resp.price
  end
end

Asynchronous Client

require 'coinbase/exchange'
require 'eventmachine'

rest_api = Coinbase::Exchange::AsyncClient.new(api_key, api_secret, api_pass)
EM.run {
  EM.add_periodic_timer(10) {
    rest_api.last_trade(product_id: "BTC-GBP") do |resp|
      p "Spot Rate: £ %.2f" % resp.price
    end
  }
}

Usage

Installation

$ gem install coinbase-exchange

Initialization

To initialize the client, simply pass in an API Key, API Secret, and API Passphrase which you generate on the web interface:

rest_api = Coinbase::Exchange::Client.new(api_key, api_secret, api_pass)
rest_api = Coinbase::Exchange::AsyncClient.new(api_key, api_secret, api_pass)

Default Product

Coinbase Pro supports trading bitcoin in several currencies. If you wish to trade a different currency, you can specify an alternative default currency.

gbp_client = Coinbase::Exchange::Client.new(api_key, api_secret, api_pass,
                                            product_id: "BTC-GBP")

Sandbox

You can initialize a connection to the sandbox by specifying an alternative api endpoint.

sandbox = Coinbase::Exchange::Client.new(api_key, api_secret, api_pass,
                                          api_url: "https://api-public.sandbox.pro.coinbase.com")

Methods

The default representation of return data is an unmodified hash from the JSON blob returned in the body of the API response. The response should be accessed in a block like this.

rest_api.last_trade do |resp|
  p "Spot Rate: $ %.2f" % BigDecimal(resp['price'])
end

Note, the synchronous client will also return the same data. However, this is discouraged since it will make porting code to an asynchronous client more difficult. Here is an example of what that might look like.

resp = rest_api.last_trade
p "Spot Rate: $ %.2f" % BigDecimal(resp['price'])

Parameters

The gem will automatically encode any additional parameters you pass to method calls. For instance to get the full orderbook, you must explicitly set the level parameter to 3.

rest_api.orderbook(level: 3) do |resp|
  p "There are #{resp['bids'].count} open bids on the orderbook"
  p "There are #{resp['asks'].count} open asks on the orderbook"
end

Return Values

Data format is a sensitive issue when writing financial software. The exchange API represents monetary data in string format. This is a good intermediary data format for the user to apply their own data format, but is not especially useful on its own.

For representing monetary data in ruby, we recommend using the [BigDecimal] (http://ruby-doc.org/stdlib-2.1.1/libdoc/bigdecimal/rdoc/BigDecimal.html) library. If you access data by calling response items as though they were methods on the response itself. If you access data this way, any numerical data will be converted to BigDecimal format.

rest_api.orders(before: Time.now - 60*60) do |resp|
  resp.each do |order|
    p sprintf "#{order.side} ฿ %.8f for $ %.2f", order.size, order.price
  end
end

Errors

The gem will throw an error if it detects an exception. The possible errors are:

Error Description
APIError Parent class for all errors.
BadRequestError Server returned status 400.
NotAuthorizedError Server returned status 401.
ForbiddenError Server returned status 403.
NotFoundError Server returned status 404.
RateLimitError Server returned status 429.
InternalServerError Server returned status 500.

Metadata

You may need more fine-grained access to API response than just the body. We additionally provide access to the response headers, status, and the raw response as represented by the underlying library.

rest_api.last_trade do |resp|
  p "Status: #{resp.response_status}"
  p "Headers: #{resp.response_headers}"
  p "Response: #{resp.raw}"
end

Endpoints

[Market Data] (https://docs.pro.coinbase.com/#market-data)

Coinbase supports trading in multiple currencies. When interacting with market data, you can get information about a product other than your default by setting the product_id parameter.

rest_api.last_trade(product_id: 'BTC-GBP') do |resp|
  p "The spot rate is £ %.2f" % resp.price
end

currencies

Fetches a list of currencies we support.

rest_api.currencies do |resp|
  resp.each do |currency|
    p "The symbol for #{currency.name} is #{currency.id}"
  end
end

products

Fetches a list of products we offer.

rest_api.products do |resp|
  resp.each do |product|
    p "The most #{product.base_currency} you can buy with #{product.quote_currency} is %f" % product.base_max_size
  end
end

orderbook

Downloads a list of all open orders on our exchange.

rest_api.orderbook do |resp|
  p resp
end

If you wish to download a level 2 or level 3 orderbook, pass a level parameter to the method.

rest_api.orderbook(level: 3) do |resp|
  p "There are #{resp.bids.count} open bids on the orderbook"
  p "There are #{resp.asks.count} open asks on the orderbook"
end

last_trade

Downloads information about the last trade, which is exposed through the /ticker endpoint.

rest_api.last_trade do |resp|
  p "The spot rate is $ %.2f" %  resp.price
end

trade_history

Downloads recent trades. Please be aware that if you don't explicitly pass a before parameter this will recursively download every trade that's ever been placed.

rest_api.trade_history(before: Time.now - 10*60) do |resp|
  p "#{resp.count} trades have occurred in the past 10 minutes."
end

price_history

Downloads price history. We recommend setting a start parameter. You may also find the granularity parameter useful.

rest_api.price_history(start: Time.now - 60*60, granularity: 60) do |resp|
  p "In the past hour, the maximum price movement was $ %.2f" % resp.map { |candle| candle.high - candle.low }.max
end

daily_stats

Downloads price information over the past 24 hours.

rest_api.daily_stats do |resp|
  p "The highest price in in the past 24 hours was %.2f" % resp.high
  p "The lowest price in in the past 24 hours was %.2f" % resp.low
end

[Accounts] (https://docs.pro.coinbase.com/#accounts)

accounts

Downloads information about your accounts.

rest_api.accounts do |resp|
  resp.each do |account|
    p "#{account.id}: %.2f #{account.currency} available for trading" % account.available
  end
end

account

Downloads information about a single account. You must pass the account id as the first parameter.

rest_api.account(account_id) do |account|
  p "Account balance is %.2f #{account.currency}" % account.balance
end

account_history

Downloads a ledger of transfers, matches, and fees associated with an account. You must pass the account id as the first parameter.

rest_api.account_history(account_id) do |resp|
  p resp
end

account_holds

Holds are placed on an account for open orders. This will download a list of all account holds.

rest_api.account_holds(account_id) do |resp|
  p resp
end

[Orders] (https://docs.pro.coinbase.com/#orders)

bid

Places a buy order. Required parameters are amount and price.

rest_api.bid(0.25, 250) do |resp|
  p "Order ID is #{resp.id}"
end

buy

This is an alias for bid.

rest_api.buy(0.25, 250) do |resp|
  p "Order ID is #{resp.id}"
end

ask

Places a sell order. Required parameters are amount and price.

rest_api.ask(0.25, 250) do |resp|
  p "Order ID is #{resp.id}"
end

sell

This is an alias for ask.

rest_api.sell(0.25, 250) do |resp|
  p "Order ID is #{resp.id}"
end

cancel

Cancels an order. This returns no body, but you can still pass a block to execute on a successful return.

rest_api.cancel(order_id) do
  p "Order canceled successfully"
end

orders

Downloads a list of all your orders. Most likely, you'll only care about your open orders when using this.

rest_api.orders(status: "open") do |resp|
  p "You have #{resp.count} open orders."
end

order

Downloads information about a single order.

rest_api.order(order_id) do |resp|
  p "Order status is #{resp.status}"
end

fills

Downloads a list of fills.

rest_api.fills do |resp|
  p resp
end

[Transfers] (https://docs.pro.coinbase.com/#transfer-funds)

deposit

Deposit money from a Coinbase wallet.

rest_api.deposit(wallet_id, 10) do |resp|
  p "Deposited 10 BTC"
end

withdraw

Withdraw money for your Coinbase wallet.

rest_api.withdraw(wallet_id, 10) do |resp|
  p "Withdrew 10 BTC"
end

Other

server_time

Download the server time.

rest_api.server_time do |resp|
  p "The time on the server is #{resp}"
end

Websocket Client

We recommend reading the official websocket documentation before proceeding.

We provide a websocket interface in the gem for convenience. This is typically used to build a real-time orderbook, although it can also be used for simpler purposes such as tracking the market rate, or tracking when your orders fill. Like the asynchronous client, this depends Eventmachine for asynchronous processing.

Please consider setting the keepalive flag to true when initializing the websocket. This will cause the websocket to proactively refresh the connection whenever it closes.

websocket = Coinbase::Exchange::Websocket.new(keepalive: true)

Before starting the websocket, you should hook into whatever messages you're interested in by passing a block to the corresponding method. The methods you can use for access are open, match, change, done, and error. Additionally, you can use message to run a block on every websocket event.

require 'coinbase/exchange'
require 'eventmachine'

websocket = Coinbase::Exchange::Websocket.new(product_id: 'BTC-GBP',
                                              keepalive: true)
websocket.match do |resp|
  p "Spot Rate: £ %.2f" % resp.price
end

EM.run do
  websocket.start!
  EM.add_periodic_timer(1) {
    websocket.ping do
      p "Websocket is alive"
    end
  }
  EM.error_handler { |e|
    p "Websocket Error: #{e.message}"
  }
end

If started outside the reactor loop, the websocket client will use a very basic Eventmachine handler.

require 'coinbase/exchange'

websocket = Coinbase::Exchange::Websocket.new(product_id: 'BTC-GBP')
websocket.match do |resp|
  p "Spot Rate: £ %.2f" % resp.price
end
websocket.start!