Uphold

Gem Version Build Status Code Climate Test Coverage

A ruby client for the Uphold API.

Installation

Add this line to your application's Gemfile:

gem 'uphold'

And then execute:

$ bundle

Or install it yourself as:

$ gem install uphold

Contents

Usage

To use the gem, you have to instantiate a client. All API calls are made from there. Here's a minimal working example:

require 'uphold'

client = Uphold::Client.new
puts client.all_tickers

Sandbox mode

Uphold has a sandbox version for testing purposes:

You can set Uphold.sandbox = true to enable sandboxing mode to set the global base URL to point to the sandbox API instead of the production one.

Options

This is a summary of the supported options when instantiating a new client, and their default values:

Uphold::Client.new(
  # bearer_token for OAuth authentication
  token: ENV['UPHOLD_AUTH_TOKEN']
)

Creating an authenticated client

In order to make most of the API calls, you will need to authenticate your client. Here's how you can do that.

Personal Access Token

If you don't have a PAT, learn how to generate one here.

If you already have a token, you can use it by setting an environment variable, or by passing it when instantiating the client.

Via argument

Pass the token to the constructor:

Uphold::Client.new(token: 'your-access-token')

Via environment variable

Set the environment variable using dotenv, or by exporting it in your shell:

$ export UPHOLD_AUTH_TOKEN="your-access-token"

Then instantiate the client:

Uphold::Client.new

Endpoints

This is a comprehensive list of all the mappings between this wrapper and the Uphold's API.

Authentication

Uphold documentation on authentication

OAuth2

NOT SUPPORTED BY UPHOLD YET

Basic Authentication

Bireserve documentation on basic authentication

The only thing you need, in order to use basic authentication is a Personal Access Token, everything else is transparent to you. If you already have a token, see how to use it here.

client.generate_access_token(username: 'your-uphold-username', password:
'your-uphold-password', otp: 'a-valid-uphold-otp')

To generate a valid OTP you can install Authy, follow it's set up process and choose uphold. You should be prompted with a set of numbers, which is your OTP (it only lasts 30 seconds, so you have to be quick).

Tickers

Uphold documentation on tickers

Return the current rates on Uphold for all currency pairs:

client.all_tickers

Return the current rates on Uphold for a specific currency:

client.find_ticker(currency: 'EUR')

Cards

Uphold documentation on cards

Return all the user's cards:

client.all_cards

Return the details for a specific card associated with the user:

client.find_card(id: '37e002a7-8508-4268-a18c-7335a6ddf24b')

Create a card for the user:

client.create_card(label: 'My label', currency: 'BTC')

Transactions

Uphold documentation on transactions

You can interact with both the authenticated user's and public transactions.

Public Transactions

Return the public view of all transactions in the reserve (supports Pagination):

client.all_public_transactions

Return the public view of a specific transaction (supports Pagination):

client.find_public_transactions(id: 'a97bb994-6e24-4a89-b653-e0a6d0bcf634')

Private Transactions

Create a transaction:

client.create_transaction(card_id: 'a6d35fcd-xxxx-9c9d1dda6d57', currency:
'BTC', amount: 0.1, destination: '[email protected]')

Commit a transaction:

client.commit_transaction(card_id: 'a6d35fcd-xxxx-9c9d1dda6d57', transaction_id:
'd51b4e4e-9827-40fb-8763-e0ea2880085b')

Create and commit a transaction in a single request:

client.create_and_commit_transaction(card_id: 'a6d35fcd-xxxx-9c9d1dda6d57', currency:
'BTC', amount: 0.1, destination: '[email protected]')

Cancel a transaction:

client.cancel_transaction(card_id: 'a6d35fcd-xxxx-9c9d1dda6d57', transaction_id:
'd51b4e4e-9827-40fb-8763-e0ea2880085b')

Resend a transaction:

client.resend_transaction(card_id: 'a6d35fcd-xxxx-9c9d1dda6d57', transaction_id:
'd51b4e4e-9827-40fb-8763-e0ea2880085b')

Return all transactions associated with the user (supports Pagination):

client.all_user_transactions

Return all transactions associated with a card:

client.all_card_transactions

Contacts

Uphold documentation on contacts

Return all the user's contacts:

client.all_contacts

Return the details for a specific contact associated with the user:

client.find_contact(id: '9fae84eb-712d-4b6a-9b2c-764bdde4c079')

Create a contact for the user:

client.create_contact(first_name: 'Luke', last_name: 'Skywalker', company: 'Lars
Moisture Farm Inc', emails: ['[email protected]')

Users

Uphold documentation on users

Return the details of the user:

client.me

Return the list of phone numbers associated with the user:

client.phones

Transparency

Uphold documentation on the reserve status

Return a summary of all obligations and assets:

client.statistics

Uphold documentation on the reserve ledger

Return a detailed record of all obligations and assets flowing into the network:

client.ledger

Pagination

Uphold documentation on pagination

All endpoints that support pagination take a range attribute, in which you can specify the first and last indexes for the items you wish to retrieve.

The response will look exactly like an Array, but with a method called total_items, that returns the total number of items of that type that Uphold knows of.

client = Uphold::Client.new token: 'XXX'
client.all_public_transactions.size # 5
client.all_public_transactions.total_size # 21110
client.all_public_transactions(range: (5..20)).size # 16

Contributing

  1. Fork it ( https://github.com/subvisual/uphold-ruby/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Copyright

Copyright (c) 2015 Group Buddies. See LICENSE.txt for further details.