The Node.js Uphold SDK provides an easy way to get started using the Uphold API with Node.
- Getting Started
- Methods
- buildAuthURL(scope, state)
- createToken(code, callback)
- addToken(token)
- 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
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.
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 |
The Uphold Node SDK only supports the Web Application Flow Oauth2 method of authentication currently which is the only recommended method of authentication for public facing web applications.
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": "cards:read,cards:write,contacts:read,contacts:write,transactions:read,transactions:write,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);
});
});
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 like so:
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.
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 |
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 |
Add or overwrite the configs bearer property.
Param | Type | Description |
token | string |
a bearer token |
Note: this method is chain-able.
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 |
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 |
Get all cards
Param | Type | Description |
callback(err, cards) | callback |
responds with an array of the current user’s cards |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
Get all contacts
Param | Type | Description |
callback(err, contacts) | callback |
responds with an array of contacts objects |
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 |
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 |
Get the current user
Param | Type | Description |
callback(err, user) | callback |
responds with a user object |
Get the current users phone numbers
Param | Type | Description |
callback(err, phones) | callback |
responds with an array of phone number objects |
Get statistics from the Uphold reserve
Param | Type | Description |
callback(err, statistics) | callback |
responds with an array of statistic objects |
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 |
All submissions are welcome. To submit a change, fork this repo, make your changes, run the tests (npm run test:single
), commit your changes, 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