/uphold-sdk-node

An SDK for the Uphold API

Primary LanguageJavaScript

uphold-sdk-node

Travis Codecov Version

The Node.js Uphold SDK provides an easy way to get started using the Uphold API with Node.

No longer maintained

This library is no longer maintained in favor of the official Uphold SDK

Table of contents

Getting Started

To begin follow the Uphold sandbox getting started guide to get your test Uphold account and application set up.

In order to learn more about the Uphold API, make sure you also look over the API documentation.

Installation

Make sure you have node & npm installed then run:

npm install uphold-sdk-node

Once this has finished installing the SDK may be initialized with this line of javascript:

var Uphold = require('uphold-sdk-node')(config);

The config object passed in here can contain any of the following properties:

Property Type Description
config.host string optional Uphold API domain, will default to "api.uphold.com"
config.version string optional Uphold API version, example: "v1". Will default to latest stable
config.key string application API key (Client ID)
config.secret string application secret
config.scope string comma separated list of permissions to request
config.bearer string Uphold API token
config.pat string Uphold API Personal Access Token, config.bearer will overwrite this.

Authentication

The Uphold Node SDK supports the Web Application Flow Oauth2 method of authentication which is the only recommended method of authentication for public facing web applications. For private scripts and tools Personal Access Token (PAT) authentication is also available.

Web Application Flow

To authenticate a user and retrieve a bearer token to access their account the user must first be redirected to the Uphold auth URL to accept the application permissions requested in scope. A bearer token can then be created using the code parameter provided by Uphold while redirecting the user back to your application. A simplified example of how you might do this with the Uphold Node SDK can be seen below:

var Uphold = require('uphold-sdk-node')({
    "key": "<your applications api key>",
    "secret": "<your applications secret>",
    "scope": "accounts:read,cards:read,cards:write,contacts:read,contacts:write,transactions:deposit,transactions:read,transactions:transfer:application,transactions:transfer:others,transactions:transfer:self,transactions:withdraw,user:read"
});

var auth = Uphold.buildAuthURL();
// store the state to validate against
var storedState = auth.state;
// redirect the user to the Uphold auth url
res.redirect(auth.url);

Once Upholds redirected the user back to your applications redirect url:

var Uphold = require('uphold-sdk-node')({
    "key": "<your applications api key>",
    "secret": "<your applications secret>"
});

// check the stored state equals the state returned
if(req.params.state!==storedState) return false;
// create the bearer token using the code param from the url
Uphold.createToken(req.params.code, function(err, token) {
    if(err) return customErrorHandler(err);
    // store the token for later use
    var storedBearer = token;
    // add the token to the current uphold-sdk-node configs bearer property and make authenticated calls
    Uphold.addToken(storedBearer.access_token).user(function(err, user) {
        if(err) return customErrorHandler(err);
        console.log(user);
    });
});

Personal Access Token (PAT)

Once created a PAT provides full access to your user account and bypasses Two Factor Authentication. An example of how to create and use a PAT with the Uphold Node SDK can be found below:

var Uphold = require('uphold-sdk-node');

Uphold.createPAT('username', 'password', 'PAT description', false, function(err, res) {
    if(err) return customErrorHandler(err);
    // if two factor authentication is enabled on the account a One Time Password (OTP) will be required
    // once retrieved this method can be called again with the OTP like so
    // Uphold.createPAT('username', 'password', 'PAT description', 'OTP', function(err, res) {});
    if(res.otp) return getOTP();

    // add the PAT to the current uphold-sdk-node configs pat property and make authenticated calls
    Uphold.addPAT(res.accessToken).user(function(err, user) {
        if(err) return customErrorHandler(err);
        console.log(user);
    });
});

Basic Usage

Once authenticated the Uphold bearer token can be passed into the config within the config.bearer property and API calls can be made using methods of the Uphold Node SDK as the example below. Alternatively a PAT can be passed into the config with the config.pat property:

var Uphold = require('uphold-sdk-node')({
    "host": "api-sandbox.uphold.com",
    "bearer": "<bearer token>"
});

Uphold.user(function(err, user) {
    if(err) return customErrorHandler(err);
    console.log(user);
});

Note: by making the config.host property equal to "api-sandbox.uphold.com" we will be using the Uphold sandbox environment, simply omit config.host to use the live environment instead.

Methods

buildAuthURL(scope, state)

Retrieve the auth URL where the user can give application permissions

Param Type Description
scope string comma separated list of permissions to request, will default to config.scope
state string a secure random string, will be automatically provided if none is given

createToken(code, callback)

Exchange a temporary code for a bearer token.

Param Type Description
code string code param provided from the Uphold auth URL
callback(err, token) callback responds with an object containing access_token

addToken(token)

Add or overwrite the configs bearer property.

Param Type Description
token string a bearer token

Note: this method is chain-able.

createPAT(username, password, description, otp, callback)

Create a Personal Access Token.

Param Type Description
username string account holders username
password string account holders password
description string a human-readable description of this PAT
otp string One Time Password, applicable if two factor authentication is enabled on the account
callback(err, token) callback responds with an object containing accessToken

Note: this will respond with { otp: true } if OTP is not provided but two factor authentication is enabled on the account.

revokePAT(pat, callback)

Revoke a Personal Access Token

Param Type Description
pat string the PAT to revoke
callback(err, res) callback

addPAT(pat)

Add or overwrite the configs pat property

Param Type Description
pat string a Personal Access Token

Note: this method is chain-able.

tickers(callback)

Get all tickers

Param Type Description
callback(err, tickers) callback responds with an array containing the current rates Uphold has on record for all currency pairs

tickersForCurrency(currency, callback)

Get tickers for a currency

Param Type Description
currency string currency to return rates for
callback(err, tickers) callback responds with an array containing the current rates Uphold has on record for the currency specified

cards(callback)

Get all cards

Param Type Description
callback(err, cards) callback responds with an array of the current user’s cards

card(id, callback)

Get details of a single card

Param Type Description
id string card ID or its bitcoin address
callback(err, card) callback responds with an object containing details of the card

createCard(label, currency, callback)

Create a card

Param Type Description
label string display name of the card
currency string the cards currency
callback(err, card) callback responds with an object containing details of the card created

updateCard(label, settings, callback)

Update a card

Param Type Description
label string display name of the card
settings object an optional object with the card’s position and whether it is starred
callback(err, card) callback responds with an object containing details of the updated card

transactions(range, callback)

Requests the public view of all transactions

Param Type Description
range string optional how many items to retrieve example: 0-5
callback(err, transactions) callback responds with an array of transactions

userTransactions(range, callback)

Requests a list of user transactions

Param Type Description
range string optional how many items to retrieve example: 0-5
callback(err, transactions) callback responds with an array of transactions

cardTransactions(card, range, callback)

Requests a list of transactions for a card

Param Type Description
card string the id of the card to transfer value from
range string optional how many items to retrieve example: 0-5
callback(err, transactions) callback responds with an array of transactions

transaction(id, callback)

Requests the public view of a single transaction

Param Type Description
id string the id of the card to transfer value from
callback(err, transaction) callback responds with a transaction object

prepareTransaction(card, currency, amount, destination, callback)

Prepare a transaction

Param Type Description
card string the id of the card to transfer value from
currency string the currency to denominate the transaction by
amount string the amount of value to send in the denominated currency
destination string a card id, bitcoin address, email address or Uphold username
callback(err, transaction) callback responds with an object containing details of the transaction

commitTransaction(card, transaction, message, callback)

Commit a transaction

Param Type Description
card string the id of the card to transfer value from
transaction string the id of the transaction that is going to be committed
message string an optional custom message for the transaction
callback(err, transaction) callback responds with an object containing details of the transaction

createTransaction(options, callback)

Create & commit a transaction at once

Param Type Description
options.card string the id of the card to transfer value from
options.currency string the currency to denominate the transaction by
options.amount string the amount of value to send in the denominated currency
options.destination string a card id, bitcoin address, email address or Uphold username
options.message string an optional custom message for the transaction
callback(err, transaction) callback responds with an object containing details of the transaction

cancelTransaction(card, transaction, callback)

Cancel a transaction that has not yet been redeemed

Param Type Description
card string the id of the card the transaction was created for
transaction string the id of the transaction that is going to be cancelled
callback(err, transaction) callback responds with an object containing details of the transaction

resendTransaction(card, transaction, callback)

Triggers a reminder for a transaction that hasn’t been redeemed yet

Param Type Description
card string the id of the card the transaction was created for
transaction string the id of the transaction that is going to be resent
callback(err, transaction) callback responds with an object containing details of the transaction

contacts(callback)

Get all contacts

Param Type Description
callback(err, contacts) callback responds with an array of contacts objects

contact(id, callback)

Get a single contact

Param Type Description
id string the id of the contact to be retrieved
callback(err, contact) callback responds with a contact object

createContact(options, callback)

Create a contact

Param Type Description
options.firstName string contact’s first name (max: 255 chars)
options.lastName string contact’s last name (max: 255 chars)
options.company string optional contact’s company name (max: 255 chars)
options.emails array list of email addresses
options.addresses array optional list of bitcoin addresses
callback(err, contact) callback responds with a contact object

user(callback)

Get the current user

Param Type Description
callback(err, user) callback responds with a user object

userPhones(callback)

Get the current users phone numbers

Param Type Description
callback(err, phones) callback responds with an array of phone number objects

reserveStatistics(callback)

Get statistics from the Uphold reserve

Param Type Description
callback(err, statistics) callback responds with an array of statistic objects

reserveLedger(range, callback)

Get entries for the Uphold reserve ledger

Param Type Description
range string optional how many items to retrieve example: 0-5
callback(err, statistics) callback responds with an array of ledger entry objects

Contributing

All submissions are welcome. To submit a change, fork this repo, make your changes, run the tests (npm run test:single), commit your changes (npm run commit), and send a pull request.

Alternatively if you've found a bug that doesn't already have an issue or just want to suggest something that hasn't already been suggested submit an issue