This library is under development, and is not yet ready for production use.
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 the api key + secret authentication method as well as OAuth 2.0 for performing actions on other people's account.
Add the following dependency to your Maven pom.xml:
<dependency>
<groupId>com.coinbase.api</groupId>
<artifactId>coinbase-java</artifactId>
<version>1.0.0</version>
</dependency>
Start by enabling an API Key on your account
Next, build an instance of the client buy passing your API Key + Secret to a CoinbaseBuilder object.
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 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.
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(); // user@example.com
Joda Money objects are returned for most amounts dealing with currency. You can call getAmount
, toString
, or perform math operations on money objects.
Transaction t = new Transaction();
t.setTo("user2@example.com");
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("user2@example.com");
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);
This will send an email to the recipient, requesting payment, and give them an easy way to pay.
Transaction t = new Transaction();
t.setFrom("customer@example.com");
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);
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 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).
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"
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);
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"
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());
// ...
}
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"
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"
User userParams = new User();
userParams.setEmail("newuser@example.com");
userParams.setPassword("correct horse battery staple");
User newUser = cb.createUser(userParams);
newUser.getEmail(); // "newuser@example.com"
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("newuser@example.com");
userParams.setPassword("correct horse battery staple");
User newUser = cb.createUser(userParams, "oauth_client_id_here", "user merchant");
newUser.getEmail(); // "newuser@example.com"
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
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.
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.
If you'd like to contribute code or modify this library, you can run the test suite with:
mvn clean test
- Fork this repo and make changes in your own copy
- Add a test if applicable and run the existing tests with
mvn clean test
to make sure they pass - Commit your changes and push to your fork
git push origin master
- Create a new pull request and submit it back to us!