uphold-sdk-node

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
  • 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:

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