coinbase-java

An easy way to buy, sell, send, and accept bitcoin through the Coinbase API.

This library is a wrapper around the Coinbase JSON API. It supports both the api key + secret authentication method as well as OAuth 2.0 for performing actions on other people's account.

Installation

Using Maven

Add the following dependency to your project's Maven pom.xml:

<dependency>
	<groupId>com.coinbase.api</groupId>
	<artifactId>coinbase-java</artifactId>
	<version>1.10.0</version>
</dependency>

The library will automatically be pulled from Maven Central.

Manual

You can copy this library jar and all its dependency jars to a folder as follows:

git clone [email protected]:coinbase/coinbase-java.git
cd coinbase-java
mvn dependency:copy-dependencies -DincludeScope=runtime -DoutputDirectory=$YOUR_JAR_DIRECTORY
mvn package
cp target/coinbase-java-1.10.0.jar $YOUR_JAR_DIRECTORY

Usage

HMAC Authentication (for accessing your own account)

Start by enabling an API Key on your account

Next, build an instance of the client by passing your API Key + Secret to a CoinbaseBuilder object.

import com.coinbase.api.Coinbase;
import com.coinbase.api.CoinbaseBuilder;

Coinbase cb = new CoinbaseBuilder()
                      .withApiKey(System.getenv("COINBASE_API_KEY"), System.getenv("COINBASE_API_SECRET"))
                      .build();

Notice here that we did not hard code the API keys into our codebase, but set them in environment variables instead. This is just one example, but keeping your credentials separate from your code base is a good security practice.

OAuth 2.0 Authentication (for accessing others' accounts)

Start by creating a new OAuth 2.0 application

// Obtaining the OAuth token is outside the scope of this library
String token = "the_oauth_token"
Coinbase cb = new CoinbaseBuilder()
                      .withAccessToken(token)
                      .build();

Now you can call methods on coinbase similar to the ones described in the api reference. For example:

cb.getUser().getEmail(); // [email protected]

Joda Money objects are returned for most amounts dealing with currency. You can call getAmount, toString, or perform math operations on money objects.

Examples

Send bitcoin

Transaction t = new Transaction();
t.setTo("[email protected]");
t.setAmount(Money.parse("BTC 0.10"));
Transaction r = cb.sendMoney(t);

You can also send money in a number of currencies. The amount will be automatically converted to the correct BTC amount using the current exchange rate.

Transaction t = new Transaction();
t.setTo("[email protected]");
t.setAmount(Money.parse("CAD 100"));
Transaction r = cb.sendMoney(t);

The to field can be a bitcoin address and notes can be attached to the money. Notes are only visible on Coinbase (not on the general bitcoin network).

Transaction t = new Transaction();
t.setTo("mpJKwdmJKYjiyfNo26eRp4j6qGwuUUnw9x");
t.setAmount(Money.parse("USD 2.23"));
t.setNotes("Thanks for the coffee!");
Transaction r = cb.sendMoney(t);

Request bitcoin

This will send an email to the recipient, requesting payment, and give them an easy way to pay.

Transaction t = new Transaction();
t.setFrom("[email protected]");
t.setAmount(Money.parse("USD 100"));
t.setNotes("Invoice for window cleaning");

Transaction r = cb.requestMoney(t);

cb.resendRequest(r.getId());

cb.cancelRequest(r.getId());

// From the other side

cb.completeRequest(requestId);

List your current transactions

Sorted in descending order by createdAt, 30 transactions per page

TransactionsResponse r = cb.getTransactions();

r.getTotalCount(); // 45
r.getCurrentPage(); // 1
r.getNumPages(); // 2

List<Transaction> txs = r.getTransactions();

txs.get(0).getId();

TransactionsResponse page_2 = cb.getTransactions(2);

Transactions will always have an id attribute which is the primary way to identify 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

Transaction t = cb.getTransaction("5011f33df8182b142400000e");
t.getStatus(); // Transaction.Status.PENDING
t.getRecipientAddress(); // "mpJKwdmJKYjiyfNo26eRp4j6qGwuUUnw9x"

Get quotes for buying or selling Bitcoin on Coinbase

This price includes Coinbase's fee of 1% and the bank transfer fee of $0.15.

The price to buy or sell per Bitcoin will increase and decrease respectively as the quantity increases. This slippage is normal and is influenced by the market depth on the exchanges we use.

Quote q = cb.getBuyQuote(Money.parse("BTC 2.2"));
Map<String, Money> fees = q.getFees();
q.getSubtotal();
q.getTotal();

Quote q = cb.getSellQuote(Money.parse("BTC 2.2"));
Map<String, Money> fees = q.getFees();
q.getSubtotal();
q.getTotal();

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.

Money spotPrice = cb.getSpotPrice(CurrencyUnit.EUR);

Buy or Sell bitcoin

Buying and selling bitcoin requires you to add a payment method through the web app first.

Then you can call buy or sell and pass a quantity of bitcoin you want to buy.

Transfer t = cb.buy(Money.parse("BTC 0.005"));
t.getCode(); // "6H7GYLXZ"
t.getTotal().toString(); // "USD 3"
t.getPayoutDate.toString(); // "2013-02-01T18:00:00-0800"

Transfer t = cb.sell(Money.parse("BTC 0.005"));
t.getCode(); // "6H7GYLXZ"
t.getTotal().toString(); // "USD 2.99"
t.getPayoutDate.toString(); // "2013-02-01T18:00:00-0800"

Listing Buy/Sell History

You can use getTransfers to view past buys and sells.

TransfersResponse r = cb.getTransfers();

r.getTotalCount(); // 30
r.getCurrentPage(); // 1
r.getNumPages(); // 2

List<Transfer> transfers = r.getTransfers();

for (Transfer t : transfers) {
	System.out.println(t.getCode());
	// ...
}

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.

The custom param will get passed through in callbacks to your site. The list of valid parameters are described here.

Button buttonParams = new Button();
buttonParams.setText("This is the text");
buttonParams.setDescription("This is the description");
buttonParams.setPrice(Money.parse("USD 1.23"));
buttonParams.setName("This is the name");
buttonParams.setCustom("Custom tracking code here");

Button button = cbMain.createButton(buttonParams);

button.getCode(); // "93865b9cae83706ae59220c013bc0afd"

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.

Order order = cb.createOrderForButton("93865b9cae83706ae59220c013bc0afd");
order.getReceiveAddress(); // "12mYY1z31J6mmYgzMXzRY8s8fAENiksWB8"

Create a new user

User userParams = new User();
userParams.setEmail("[email protected]");
userParams.setPassword("correct horse battery staple");
User newUser = cb.createUser(userParams);
newUser.getEmail(); // "[email protected]"

You can optionally pass in a client_id parameter that corresponds to your OAuth2 application and space separated list 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 for more details.

User userParams = new User();
userParams.setEmail("[email protected]");
userParams.setPassword("correct horse battery staple");
User newUser = cb.createUser(userParams, "oauth_client_id_here", "user merchant");
newUser.getEmail(); // "[email protected]"

Verifying merchant callbacks

String raw_http_post_body = ...;
String signature_header   = ...;
cb.verifyCallback(raw_http_post_body, signature_header); // true/false

Building an account specific client

Some API calls only apply to a single account and take an account_id parameter. To easily make account specific calls, build a client with an account id as follows:

Coinbase cb = new CoinbaseBuilder()
                      .withApiKey(System.getenv("COINBASE_API_KEY"), System.getenv("COINBASE_API_SECRET"))
                      .withAccountId("DESIRED_ACCOUNT_ID")
                      .build();

cb.getBalance(); // Gets the balance of desired account

Security Notes

When creating an API Key, make sure you only grant it the permissions necessary for your application to function.

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 if you have never done this before.

Decimal precision

This gem relies on the Joda Money library, based on the JDK BigDecimal 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.

Testing

If you'd like to contribute code or modify this library, you can run the test suite with:

mvn clean test

Contributing

1. Fork this repo and make changes in your own copy
2. Add a test if applicable and run the existing tests with mvn clean test 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!