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

Getting Started
Methods
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

DanWebb/uphold-sdk-node