Aurum

Aurum is an Elixir Client for the Coinbase API.

If gold rusts, what then can iron do? ― Geoffrey Chaucer, The Canterbury Tales

Installation

Add aurum to your list of dependencies in mix.exs:

def deps do
  [
    {:aurum, "~> 0.2.0"}
  ]
end

Usage:

API Key/Secret

First, ensure that you have a coinbase API Key, and an API Secret. Details about how to obtain those can be found in the Coinbase Documentation.

Once you have obtained them, make sure that they are in the environment your module will be running in under the names COINBASE_KEY and COINBASE_SECRET:

$ export COINBASE_KEY=...
$ export COINBASE_SECRET=...

This will enable the client library to correctly sign your requests.

Making requests to the API:

To use the client, alias Coinbase into your module:

defmodule MyModule do
   alias Aurum.Coinbase

   ...

end

Basic Usage:

Once you have access to the Coinbase module, you can begin making any of the requests outlined in the documentation for V2 of the Coinbase API. All of the authentication steps should be completed automatically provided the COINBASE_KEY and COINBASE_SECRET are properly set. All calls to the API should follow the pathing scheme of /v2/<resource path>.

For example:

def fetch_btc_account do
  Coinbase.get("/v2/accounts/btc")
end

Sucessful responses are always in the form of:

%{
  "data" => %{
    ...
  },
  "warnings" => [ ## If any
    
  ]
}

And for any HTTP verbs that require a body (i.e. PUT/PATCH/POST), the body may be defined as a bare map:

Coinbase.post("/v2/...", %{amount: 10, currency: "USD"})

...or as a valid JSON string:

Coinbase.post("/v2/...", ~S({"amount": "10", "currency": "USD"}))

Example: Buy $10.00 worth of Ethereum

iex(1)> alias Aurum.Coinbase
Aurum.Coinbase
iex(2)> eth_account = Coinbase.get("/v2/accounts/eth")
%{
  "data" => %{
    "allow_deposits" => true,
    "allow_withdrawals" => true,
    "balance" => %{"amount" => "<amount>", "currency" => "ETH"},
    "created_at" => "...",
    "currency" => %{
      "address_regex" => "...",
      "asset_id" => "...",
      "code" => "ETH",
      "color" => "#627EEA",
      "exponent" => 8,
      "name" => "Ethereum",
      "slug" => "ethereum",
      "sort_index" => 102,
      "type" => "crypto"
    },
    "id" => "...",
    "name" => "ETH Wallet",
    "primary" => true,
    "resource" => "account",
    "resource_path" => "/v2/accounts/<account_id>",
    "type" => "wallet",
    "updated_at" => "2021-04-08T21:25:29Z"
  },
}
iex(3)> eth_resource = eth_account["data"]["resource_path"]
"/v2/accounts/<account_id>"
iex(4)> buy_string = eth_resource <> "/buys"
"/v2/accounts/<account_id>/buys"
iex(5)> Coinbase.post(buy_string, %{amount: 10, currency: "USD"})
%{
  "data" => %{
    "amount" => %{"amount" => "0.00248885", "currency" => "ETH"},
    "committed" => true,
    "created_at" => "2021-12-22T01:02:32Z",
    "fee" => %{"amount" => "0.99", "currency" => "USD"},
    "hold_days" => 3,
    "hold_until" => "2021-12-25T00:00:00Z",
    "id" => "...",
    "idem" => "...",
    "instant" => true,
    "is_first_buy" => false,
    "next_step" => nil,
    "payment_method" => %{
      "id" => "...",
      "resource" => "payment_method",
      "resource_path" => "/v2/payment-methods/..."
    },
    "payout_at" => "2021-12-22T01:02:32Z",
    "requires_completion_step" => false,
    "resource" => "buy",
    "resource_path" => "/v2/accounts/<account_id>/buys/<buy_id>",
    "status" => "created",
    "subtotal" => %{"amount" => "10.00", "currency" => "USD"},
    "total" => %{"amount" => "10.99", "currency" => "USD"},
    "transaction" => nil,
    "unit_price" => %{"amount" => "4017.92", "currency" => "USD", "scale" => 2},
    "updated_at" => "2021-12-22T01:02:33Z",
    "user_reference" => "..."
  },
}

Known issues:

You may see this warning pop up from time to time:

17:55:32.021 [warn]  Description: 'Authenticity is not established by certificate path validation'
     Reason: 'Option {verify, verify_peer} and cacertfile/cacerts is missing'

This is due to some configuration problems with the underlying HTTP client, and will be adressed in a future update.

Disclaimer:

Thanks for using this library! Pull requests and contributions are always welcome. Until this library is published as >= 1.0.0 it should be considered public beta. You are welcome to use it in any of your projects, but until it is fully published please do not consider the API stable.

It is my sincerest wish as the creator and maintainer of this repo to produce software that is as high quality as possible. That being said, this is a project I maintain in my free time and since there is potential to mis-use this library in ways that may cost you real money, I feel the need to re-iterate this portion of the license:

EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

I am not responsible for any financial loss you incur while using this library to trade cryptocurrency. May the odds be ever in your favor.

Documentation:

Docs can be found at https://hexdocs.pm/aurum.