uphold-sdk-node

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

Table of contents

• Getting Started
  • Installation
  • Authentication
  • Basic Usage
• Methods
  • buildAuthURL(scope, state)
  • createToken(code, callback)
  • addToken(token)
  • createPAT(username, password, description, otp, callback)
  • revokePAT(pat, callback)
  • addPAT(pat)
  • tickers(callback)
  • tickersForCurrency(currency, callback)
  • cards(callback)
  • card(id, callback)
  • createCard(label, currency, callback)
  • updateCard(label, settings, callback)
  • transactions(range, callback)
  • userTransactions(range, callback)
  • cardTransactions(card, range, callback)
  • transaction(id, callback)
  • prepareTransaction(card, currency, amount, destination, callback)
  • commitTransaction(card, transaction, message, callback)
  • createTransaction(options, callback)
  • cancelTransaction(card, transaction, callback)
  • resendTransaction(card, transaction, callback)
  • contacts(callback)
  • contact(id, callback)
  • createContact(options, callback)
  • user(callback)
  • userPhones(callback)
  • reserveStatistics(callback)
  • reserveLedger(range, callback)
• Contributing

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:

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

createToken(code, callback)

Exchange a temporary code for a bearer token.

addToken(token)

Add or overwrite the configs bearer property.

Note: this method is chain-able.

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

Create a Personal Access Token.

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

addPAT(pat)

Add or overwrite the configs pat property

Note: this method is chain-able.

tickers(callback)

Get all tickers

tickersForCurrency(currency, callback)

Get tickers for a currency

cards(callback)

Get all cards

card(id, callback)

Get details of a single card

createCard(label, currency, callback)

Create a card

updateCard(label, settings, callback)

Update a card

transactions(range, callback)

Requests the public view of all transactions

userTransactions(range, callback)

Requests a list of user transactions

cardTransactions(card, range, callback)

Requests a list of transactions for a card

transaction(id, callback)

Requests the public view of a single transaction

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

Prepare a transaction

commitTransaction(card, transaction, message, callback)

Commit a transaction

createTransaction(options, callback)

Create & commit a transaction at once

cancelTransaction(card, transaction, callback)

Cancel a transaction that has not yet been redeemed

resendTransaction(card, transaction, callback)

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

contacts(callback)

Get all contacts

contact(id, callback)

Get a single contact

createContact(options, callback)

Create a contact

user(callback)

Get the current user

userPhones(callback)

Get the current users phone numbers

reserveStatistics(callback)

Get statistics from the Uphold reserve

reserveLedger(range, callback)

Get entries for the Uphold reserve ledger

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