A ruby client for the Uphold API.
Add this line to your application's Gemfile:
gem 'uphold'
And then execute:
$ bundle
Or install it yourself as:
$ gem install uphold
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
Uphold has a sandbox version for testing purposes:
- Sandbox site: https://sandbox.uphold.com
- Sandbox API: https://api-sandbox.uphold.com
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.
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']
)
In order to make most of the API calls, you will need to authenticate your client. Here's how you can do that.
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.
Pass the token to the constructor:
Uphold::Client.new(token: 'your-access-token')
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
This is a comprehensive list of all the mappings between this wrapper and the Uphold's API.
Uphold documentation on authentication
NOT SUPPORTED BY UPHOLD YET
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).
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')
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')
Uphold documentation on transactions
You can interact with both the authenticated user's and 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')
Create a transaction:
client.create_transaction(card_id: 'a6d35fcd-xxxx-9c9d1dda6d57', currency:
'BTC', amount: 0.1, destination: 'foo@bar.com')
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: 'foo@bar.com')
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
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: ['support@larsmoisturefarm.com')
Return the details of the user:
client.me
Return the list of phone numbers associated with the user:
client.phones
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
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
- Fork it ( https://github.com/subvisual/uphold-ruby/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Copyright (c) 2019 Subvisual. See LICENSE.txt for further details.