wealthica-sdk-js
v0.0.16
Published
Official Wealthica JS SDK for the Browser & NodeJS
Downloads
3,069
Maintainers
Readme
Official Wealthica JS SDK for the Browser & NodeJS
What is Wealthica Connect?
Wealthica is an API for connecting with Canadian financial bands and brokerages platforms.
We believe teams and developers should focus on building great products, not worry about the fragmented landscape of exchange APIs and blockchain protocols.
For our updated list of integrations, check out our list of Wealthica Integrations.
Wealthica API Javascript (JS) SDK
This is the Official Wealthica JS SDK for the Browser & NodeJS.
The Wealthica Connect SDK provides convenient access to the Wealthica API from applications written in browser and server-side JavaScript. Please note that you must register and request your API keys to use in your application.
Documentation
Refer to the Wealthica API Documentation for more details.
Bugs, requests or suggestions
Get in touch at [email protected] for bug reports, requests or suggestions.
Getting started
import Wealthica from 'wealthica-sdk-js';
(async () => {
// Create a Wealthica Connect SDK instance
const wealthica = Wealthica.init({
clientId: 'YOUR_CLIENT_ID',
secret: 'YOUR_CLIENT_SECRET',
});
// Call the API helper methods
const providers = await wealthica.providers.getList();
const team = await wealthica.getTeam();
// Alternately, pass a loginName to return a Wealthica Connect SDK User instance in order to call
// user-specific endpoints
const user = Wealthica.init({
clientId: 'YOUR_CLIENT_ID',
secret: 'YOUR_CLIENT_SECRET',
// Optional, only if you need to work with user data API, such as `wealthica.institutions.getOne(id)`,
// or `wealthica.transactions.getList()` etc.
loginName: 'YOUR_USERNAME_OR_ID',
});
// Call the user-specific API methods
const institution = await user.institutions.getOne('INSTITUTION_ID');
})();
APIs
General APIs
These methods are SDK-specific and do not have a corresponding Wealthica API endpoint.
wealthica.login(loginName)
This method logs a user in and returns a Wealthica Connect SDK User instance so you can call user-specific APIs.
From server
loginName
is required
// Create a Wealthica Connect SDK instance
const wealthica = Wealthica.init({
clientId: 'YOUR_CLIENT_ID',
secret: 'YOUR_CLIENT_SECRET',
});
// Log user(s) in
const user1 = wealthica.login('USER_ID_1');
const user2 = wealthica.login('USER_ID_2');
// Call user APIs
const user1Institution = await user1.institutions.getOne('INSTITUTION_ID_1');
const user2Institution = await user2.institutions.getOne('INSTITUTION_ID_2');
From client (browser/ReactNative)
loginName
is optional. Authentication is done either via an authEndpoint
or a custom authorizer
callback passed to Wealthica.init()
// Create a Wealthica Connect SDK instance
const wealthica = Wealthica.init({
clientId: 'YOUR_CLIENT_ID',
// POST to `authEndpoint` on your server, expecting a JSON { token: 'USER_TOKEN' }
authEndpoint: '/wealthica/auth', // default value
// Optional parameters for `authEndpoint` to authenticate your user
auth: {
params: {}, // custom `authEndpoint` body
headers: { Authorization: `Bearer ${yourAppsUserToken}` }, // custom `authEndpoint` headers
},
// Optional authorization method to use instead of `authEndpoint`
authorizer: async (callback) => {
try {
const token = await getUserTokenFromYourServer();
callback(null, { token });
} catch (error) {
callback(error);
}
}
});
// Log in to create a Wealthica User instance
const user = wealthica.login();
// Call user APIs
const institution = await user.institutions.getOne('INSTITUTION_ID_1');
Example server implementation for authEndpoint
:
const wealthica = Wealthica.init({
clientId: 'YOUR_CLIENT_ID',
secret: 'YOUR_CLIENT_SECRET',
});
router.post('/wealthica/auth', async function(req, res) {
const user = wealthica.login(req.user.id);
res.json({ token: await user.getToken() });
});
user.fetchToken()
This method fetches and returns a new user token.
NOTE
- User token has a maximum lifetime duration. Current default is 20 minutes.
- All User API methods automatically fetch a new token if the old one expires so this is rarely needed.
const token = await user.fetchToken();
user.getToken()
This method returns an existing user token or fetch a new one if the existing token has less than a specified amount of duration (default 10 seconds).
const wealthica = Wealthica.init({
clientId: 'YOUR_CLIENT_ID',
secret: 'YOUR_CLIENT_SECRET',
});
const user = wealthica.login('YOUR_USERNAME_OR_ID');
let token = await user.getToken(); // returns the user token, 20 minutes lifetime
// After 10 minutes
token = await user.getToken(); // returns the same token
// After 19 minutes 51 seconds
token = await user.getToken(); // fetches and returns a new token
// After > another 10 minutes
token = await user.getToken({ minimumLifeTime: 600 }); // fetches and returns another new token
user.getConnectData({ provider, redirectURI, state, lang, theme, providersPerLine })
This method returns a Wealthica Connect URL and authentication token for user to connect an institution.
Wealthica Connect URL must be called via POST method and pass token in the form data.
User token has a 10 minutes session timeout.
const { url, token } = await user.getConnectData({
provider: 'coinbase', // optional
// required for server-side, optional for client (browser, ReactNative) or if already passed to `Wealthica.init()`.
// Must be a registered URI.
redirectURI: 'YOUR_REDIRECT_URI',
// required for Wealthica Connect drop-in widget, but already handled by the SDK when calling
// `user.connect()` (defaults to `window.location.origin`).
// https://wealthica.com/docs/#connect-url-parameters
institutionId: 'INSTITUTION_ID',
// Pass institutionId to re-connect an existing institution that has expired/revoked credentials
origin: 'YOUR_SITE_ORIGIN',
state: 'YOUR_APP_STATE', // optional
lang: 'en', // optional (en | es | fr | it), 'en' by default
providers: ['wise', 'stockchase'], // optional, ignored if `provider` is also passed in.
providerGroups: ['core', 'thirdparty'], // optional, ['core'] by default
theme: 'light', // optional (light | dark), 'light' by default
providersPerLine: 1, // optional (1 | 2), 2 by default
features: 'feature1,feature2', // optional, a comma-separated list of features. undefined by default
});
// {
// url: "https://connect.wealthica.com/connect/coinbase?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&origin=YOUR_SITE_ORIGIN&state=YOUR_APP_STATE&lang=en&theme=light&providersPerLine=2",
// token: "USER_TOKEN"
// }
// POST Wealthica Connect URL from client (browser/ReactNative) example:
const form = document.createElement("form");
form.method = "POST";
form.action = url;
const input = document.createElement("input");
input.type = "hidden";
input.name = "token";
input.value = token;
form.appendChild(input);
document.body.appendChild(form);
form.submit();
// Alternatively, pass redirectURI once to `Wealthica.init()`
const wealthica = Wealthica.init({
clientId: 'YOUR_CLIENT_ID',
secret: 'YOUR_CLIENT_SECRET',
redirectURI: 'YOUR_REDIRECT_URI',
});
const user1 = wealthica.login('USER_ID_1');
const { url: url1, token } = await user1.getConnectData();
const user2 = wealthica.login('USER_ID_2');
const { url: url2, token } = await user2.getConnectData();
user.connect({ provider, providers, institutionId, lang, theme, providersPerLine, features, origin })
This method starts the Wealthica Connect process inside your webpage/app for user to connect their institution.
Connection response are provided via callbacks.
This method accepts the same parameters as user.getConnectData()
except for redirectURI
and state
user.connect({
// additional options
}).onConnection((institution, data) => {
console.log('provider', data.provider);
// Send the institution to your server
sendToServer('/some-route', institution);
}).onError(error => {
console.error('institution connection error:', error)
}).onEvent((name, data) => {
console.log('institution connection event:', name, data);
});
user.reconnect(institutionId)
This method starts the Wealthica Connect process to re-connect an existing institution that has expired/revoked credentials.
Connection response are provided via callbacks.
user.reconnect('INSTITUTION_ID', {
// additional options
}).onConnection(((institution, data) => {
console.log('provider', data.provider);
// Send the institution to your server
sendToServer('/some-route', institution);
}).onError(error => {
console.error('institution connection error:', error)
}).onEvent((name, data) => {
console.log('institution connection event:', name, data);
});
User APIs
These methods return user data and thus require a Wealthica Connect SDK User instance. They automatically fetch a new token if necessary so you would not be bothered with tokens logic.
user.institutions.getList()
This method retrieves the list of institutions for a user.
const institutions = await user.institutions.getList();
todo: add response example
user.institutions.getOne(id)
This method retrieves a single institution.
const institution = await user.institutions.getOne('603522490d2b02001233a5d6');
todo: add response example
user.institutions.sync(id)
This method triggers an institution sync.
const institution = await user.institutions.sync('603522490d2b02001233a5d6');
user.institutions.remove(id)
This method removes a single institution from the user.
await user.institutions.remove('603522490d2b02001233a5d6');
user.history.getList({ institutions, from, to, investments })
This method retrieves the balance history for an institution.
Returns data within the last 1 year by default.
const history = await user.history.getList({
institutions: ['603522490d2b02001233a5d6'],
from: '2021-01-01',
to: '2021-09-09',
investments: ['bitcoin:cash:usd'],
});
todo: add response example
user.transactions.getList({ institutionId, ticker, from, to, investments, last, limit })
This method retrieves the list of transactions for an institution.
Returns data within the last 1 year by default.
const transactions = await user.transactions.getList({
institutions: ['603522490d2b02001233a5d6'],
from: '2020-08-31', // optional
to: '2021-08-31', // optional
investment: 'wise:cash:usd', // optional
last: '603522490d2b02001233a5d6', // optional, blank string is allowed
limit: 10, // optional
institutionId: '603522490d2b02001233a5d6', // Deprecated, use institutions prop
});
todo: add response example
user.transactions.getOne({ txId })
This method retrieves a single transaction.
const transaction = await user.transactions.getOne({
txId: '603522490d2b02001233a5d6'
});
todo: add response example
user.positions.getList({ institutions })
This method retrieves user positions.
const positions = await user.positions.getList({
institutions: ['603522490d2b02001233a5d6']
});
todo: add response example
Data APIs
These methods provide general Wealthica information and do not require logging in a user.
const wealthica = Wealthica.init({
clientId: 'YOUR_CLIENT_ID',
secret: 'YOUR_CLIENT_SECRET',
});
const providers = await wealthica.providers.getList();
wealthica.providers.getList()
This method retrieves the list of Wealthica supported providers.
const providers = await wealthica.providers.getList();
todo: add response example
wealthica.providers.getOne(id)
This method retrieves a single provider.
const provider = await wealthica.providers.getOne('coinbase');
todo: add response example
Development
Install
yarn install
Build
yarn build
Test
yarn build
yarn test
Use GET method in Connect URL instead of POST
Pass additional flag connectionType: 'GET'
to use GET method in Connect URL instead of POST:
connect({ connectionType: 'GET' })
reconnect(accountId, { connectionType: 'GET' })
That's useful for developing Connect URL when vite local server used. Token exposed in URL when GET method used what is not secure so this feature should be used only for development goals.
Release
npm version patch # or minor/major
git push && git push --tags
# wait until merged then
npm publish