vezgo-node

vezgo-node

Official Vezgo SDK for NodeJS

Getting started

import Vezgo from 'vezgo-node';

(async () => {
  // Create a Vezgo SDK instance
  const vezgo = Vezgo.init({
    clientId: 'YOUR_CLIENT_ID',
    secret: 'YOUR_CLIENT_SECRET',
  });

  // Call the API helper methods
  const providers = await vezgo.providers.getList();
  const team = await vezgo.getTeam();

  // Alternately, pass a loginName to return a Vezgo SDK User instance in order to call
  // user-specific endpoints
  const user = Vezgo.init({
    clientId: 'YOUR_CLIENT_ID',
    secret: 'YOUR_CLIENT_SECRET',
    // Optional, only if you need to work with user data API, such as `vezgo.accounts.getOne(id)`,
    // or `vezgo.transactions.getList()` etc.
    loginName: 'YOUR_USERNAME_OR_ID',
  });

  // Call the user-specific API methods
  const account = await user.accounts.getOne('ACCOUNT_ID');
})();

APIs

General APIs

These methods are SDK-specific and do not have a corresponding Vezgo API endpoint.

vezgo.login(loginName)

This method logs a user in and returns a Vezgo SDK User instance so you can call user-specific APIs.

From server

loginName is required

// Create a Vezgo SDK instance
const vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});

// Log user(s) in
const user1 = vezgo.login('USER_ID_1');
const user2 = vezgo.login('USER_ID_2');

// Call user APIs
const user1Account = await user1.accounts.getOne('ACCOUNT_ID_1');
const user2Account = await user2.accounts.getOne('ACCOUNT_ID_2');

From client (browser/ReactNative)

loginName is optional. Authentication is done either via an authEndpoint or a custom authorizer callback passed to Vezgo.init()

// Create a Vezgo SDK instance
const vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  // POST to `authEndpoint` on your server, expecting a JSON { token: 'USER_TOKEN' }
  authEndpoint: '/vezgo/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 Vezgo User instance
const user = vezgo.login();

// Call user APIs
const account = await user.accounts.getOne('ACCOUNT_ID_1');

Example server implementation for authEndpoint:

const vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});

router.post('/vezgo/auth', async function(req, res) {
  const user = vezgo.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 vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});

const user = vezgo.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.getConnectUrl({ provider, redirectURI, state, lang })

This method returns a Vezgo Connect URL for user to connect an account.

The URL has a 10 minute session timeout.

const url = await user.getConnectUrl({
  provider: 'coinbase', // optional
  // required for server-side, optional for client (browser, ReactNative) or if already passed to `Vezgo.init()`.
  // Must be a registered URI.
  redirectURI: 'YOUR_REDIRECT_URI',
  // required for Node & ReactNative, optional for browser (defaults to window.location.host)
  origin: 'YOUR_SITE_ORIGIN', // or com.your-bundle-id for ReactNative
  state: 'YOUR_APP_STATE', // optional
  lang: 'en', // optional (en | fr), 'en' by default
});
// https://connect.vezgo.com/connect/coinbase?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&origin=YOUR_SITE_ORIGIN&state=YOUR_APP_STATE&token=USER_TOKEN&lang=en

// Alternatively, pass redirectURI once to `Vezgo.init()`
const vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
  redirectURI: 'YOUR_REDIRECT_URI',
  origin: 'YOUR_SITE_ORIGIN',
});

const user1 = vezgo.login('USER_ID_1');
const url1 = await user1.getConnectUrl();

const user2 = vezgo.login('USER_ID_2');
const url2 = await user2.getConnectUrl();

(pending) user.connect({ provider })

This method starts the Vezgo Connect process inside your webpage/app for user to connect their account.

Connection response are provided via callbacks.

user.connect({
  provider: 'coinbase', // optional
}).onConnection(account => {
  // Send the account to your server
  sendToServer('/some-route', account);
}).onError(error => {
  console.error('account connection error:', error)
}).onEvent((name, data) => {
  console.log('account connection event:', name, data);
});

User APIs

These methods return user data and thus require a Vezgo SDK User instance. They automatically fetch a new token if necessary so you would not be bothered with tokens logic.

user.accounts.getList()

This method retrieves the list of accounts for a user.

const accounts = await user.accounts.getList();

[
  {
    "id": "603522490d2b02001233a5d6",
    "provider": {
      "name": "coinbase",
      "display_name": "Coinbase",
      "logo": "https://app.wealthica.com/images/institutions/coinbase.png",
      "type": "oauth",
      "scopes": [],
      "resource_type": "provider"
    },
    "balances": [
      {
        "ticker": "BTC",
        "provider_ticker": "BTC",
        "name": "Bitcoin",
        "asset_is_verified": null,
        "asset_type": "",
        "amount": "0.20210831",
        "decimals": 8,
        "fiat_ticker": "USD",
        "fiat_value": "2021.08",
        "fiat_asset_is_verified": null,
        "logo": "https://data.wealthica.com/api/securities/CRYPTO:BTC/logo",
        "updated_at": 1630412605283,
        "misc": null,
        "resource_type": "balance"
      }
    ],
    "blockchain": null,
    "created_at": 1630412605283,
    "updated_at": 1630412605283,
    "resource_type": "account",
  },
  {
    "id": "603522490d2b02001233a5d7",
    "provider": {
      "name": "bitcoin",
      "display_name": "Bitcoin Address",
      "logo": "https://app.wealthica.com/images/institutions/bitcoin.png",
      "type": "wallet",
      "scopes": [],
      "resource_type": "provider"
    },
    "balances": [],
    "blockchain": null,
    "created_at": 1630412605283,
    "updated_at": 1630412605283,
    "resource_type": "account",
  }
]

user.accounts.getOne(id)

This method retrieves a single account.

const account = await user.accounts.getOne('603522490d2b02001233a5d6');

{
  "id": "603522490d2b02001233a5d6",
  "provider": {
    "name": "coinbase",
    "display_name": "Coinbase",
    "logo": "https://app.wealthica.com/images/institutions/coinbase.png",
    "type": "oauth",
    "scopes": [],
    "resource_type": "provider"
  },
  "balances": [
    {
      "ticker": "BTC",
      "provider_ticker": "BTC",
      "name": "Bitcoin",
      "asset_is_verified": null,
      "asset_type": "",
      "amount": "0.20210831",
      "decimals": 8,
      "fiat_ticker": "USD",
      "fiat_value": "2021.08",
      "fiat_asset_is_verified": null,
      "logo": "https://data.wealthica.com/api/securities/CRYPTO:BTC/logo",
      "updated_at": 1630412605283,
      "misc": null,
      "resource_type": "balance"
    }
  ],
  "blockchain": null,
  "created_at": 1630412605283,
  "updated_at": 1630412605283,
  "resource_type": "account",
}

user.transactions.getList({ accountId, ticker, from, to })

This method retrieves the list of transactions for an account.

Returns data within the last 1 year by default.

const transactions = await user.transactions.getList({
  accountId: '603522490d2b02001233a5d6',
  ticker: 'BTC', // optional
  from: '2020-08-31', // optional
  to: '2021-08-31', // optional
});

[
  {
    "id": "603522490d2b02001233a5d6",
    "status": null,
    "transaction_type": "deposit",
    "parts": [
      {
        "direction": "received",
        "ticker": "BTC",
        "provider_ticker": "BTC",
        "amount": "1.20210831",
        "asset_is_verified": null,
        "fiat_ticker": "USD",
        "fiat_value": "1234567.8",
        "fiat_asset_is_verified": null,
        "other_parties": []
      }
    ],
    "fees": [
      {
        "type": null,
        "ticker": "USD",
        "provider_ticker": "USD",
        "amount": "0.5",
        "asset_is_verified": null,
        "fiat_ticker": "",
        "fiat_value": "",
        "fiat_asset_is_verified": null,
        "resource_type": "transaction_fee"
      }
    ],
    "misc": [],
    "fiat_calculated_at": 1630412605283,
    "initiated_at": 1630412605283,
    "confirmed_at": 1630412605283,
    "resource_type": "transaction"
  },
  {
    "id": "603522490d2b02001233a5d7",
    "status": null,
    "transaction_type": "deposit",
    "parts": [],
    "fees": [],
    "misc": [],
    "fiat_calculated_at": 1630412605283,
    "initiated_at": 1630412605283,
    "confirmed_at": 1630412605283,
    "resource_type": "transaction"
  }
]

user.transactions.getOne({ accountId, txId })

This method retrieves a single transaction.

const transaction = await user.transactions.getOne({
  accountId: '603522490d2b02001233a5d6',
  txId: '603522490d2b02001233a5d6'
});

{
  "id": "603522490d2b02001233a5d6",
  "status": null,
  "transaction_type": "deposit",
  "parts": [
    {
      "direction": "received",
      "ticker": "BTC",
      "provider_ticker": "BTC",
      "amount": "1.20210831",
      "asset_is_verified": null,
      "fiat_ticker": "USD",
      "fiat_value": "1234567.8",
      "fiat_asset_is_verified": null,
      "other_parties": []
    }
  ],
  "fees": [
    {
      "type": null,
      "ticker": "USD",
      "provider_ticker": "USD",
      "amount": "0.5",
      "asset_is_verified": null,
      "fiat_ticker": "",
      "fiat_value": "",
      "fiat_asset_is_verified": null,
      "resource_type": "transaction_fee"
    }
  ],
  "misc": [],
  "fiat_calculated_at": 1630412605283,
  "initiated_at": 1630412605283,
  "confirmed_at": 1630412605283,
  "resource_type": "transaction"
}

Data APIs

These methods provide general Vezgo information and do not require logging in a user.

const vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});

const providers = await vezgo.providers.getList();

vezgo.providers.getList()

This method retrieves the list of Vezgo supported providers.

const providers = await vezgo.providers.getList();

[
  {
    "name": "coinbase",
    "display_name": "Coinbase",
    "logo": "https://app.wealthica.com/images/institutions/coinbase.png",
    "auth_type": "oauth",
    "available_scopes": [],
    "available_currencies": null,
    "resource_type": "provider",
    "status": null,
    "is_beta": true,
    "connect_notice": "",
    "credentials": ["code"]
  },
  {
    "name": "bitcoin",
    "display_name": "Bitcoin Address",
    "logo": "https://app.wealthica.com/images/institutions/bitcoin.png",
    "auth_type": "wallet",
    "available_scopes": [],
    "available_currencies": null,
    "resource_type": "provider",
    "status": null,
    "is_beta": true,
    "connect_notice": "",
    "credentials": ["wallet"]
  }
]

vezgo.providers.getOne(id)

This method retrieves a single provider.

const provider = await vezgo.providers.getOne('coinbase');

{
    "name": "coinbase",
    "display_name": "Coinbase",
    "logo": "https://app.wealthica.com/images/institutions/coinbase.png",
    "auth_type": "oauth",
    "available_scopes": [],
    "available_currencies": null,
    "resource_type": "provider",
    "status": null,
    "is_beta": true,
    "connect_notice": "",
    "credentials": ["code"]
  }

Development

Install

yarn install

Build

yarn build

Test

yarn build
yarn test

Release

npm version patch # or minor/major
git push --tags
# wait until merged then
npm publish