NAV
Vezgo Frontend JS Vezgo Backend JS REST

Getting started

Introduction

Welcome to Vezgo!

Vezgo is the easiest way for people to connect their crypto accounts to your app. It connects to any crypto exchange, wallet, protocol or account to retrieve balances, holdings and transactions.

To see a complete list of supported cryptocurrency exchanges and wallets, see our Dev Status page.

To sign up for Vezgo API, send an email to hello@vezgo.com.

After signing up, you will be provided with a Client ID and Client Secret for the API authentication.

Vezgo URLs

These are the base urls for making API requests, or composing a Vezgo Connect url for users to connect their accounts.

API Base URL

https://api.vezgo.com/v1

Connect Base URL

https://connect.vezgo.com/connect

Vezgo SDKs

We currently provide JS SDKs for the frontend (Web, ReactNative) and backend (NodeJS) to easily work with the Vezgo APIs. Both the frontend and backend SDK are based on the same source code, and have the same usage, except for a little difference in authentication.

Github: https://github.com/wealthica/vezgo-sdk-js

NPMJS: https://www.npmjs.com/package/vezgo-sdk-js

Browser build: https://unpkg.com/vezgo-sdk-js/dist/vezgo.js. IMPORTANT: This drop-in URL always points to the latest version, which may contain breaking changes. It is recommended to include the dist build in your frontend build system, or use a specific version url, for example https://unpkg.com/vezgo-sdk-js@1.0.3/dist/vezgo.js.

Vezgo Example project: https://github.com/wealthica/vezgo-sdk-js/tree/master/example

Mobile support

ReactNative example:

import { authorize } from 'react-native-app-auth';
import Vezgo from 'vezgo-sdk-js';
import {URL} from 'react-native-url-polyfill';

const clientId = 'YOUR_CLIENT_ID';
const redirectUrl = 'com.yourapp://vezgo'; // need to be registered

const vezgo = Vezgo.init({
  clientId,
  // Set authEndpoint or authorizer function similar to web app
  authEndpoint: '/vezgo/auth',
});

// On button click
const user = vezgo.login();
const token = await user.fetchToken();
// Or build connect URL via user.getConnectUrl()
const authorizeUrl = 'https://connect.vezgo.com/connect/coinbase';

// Now start the Vezgo Connect process
try {
  const result = await authorize({
    serviceConfiguration: {
      authorizationEndpoint: authorizeUrl,
      tokenEndpoint: authorizeUrl, // required by AppAuth
    },
    clientId,
    redirectUrl,
    additionalParameters: { token, lang: 'es' },
    skipCodeExchange: true,
  });

  const accountId = result.authorizationCode;
  sendToServer(accountId);
  const account = await user.accounts.getOne(accountId);
  displayAccount(account);
} catch (err) {
  if (err.message !== 'Connection closed by the user') showError(err);
}

Mobile applications are considered frontend clients, so most of the concepts and examples for Frontend Client can be applied.

The Vezgo SDK JS can be used in ReactNative apps mostly the same way it is used in web applications. The main difference is that the user.connect().onConnection() helper that opens the Vezgo Connect process is not available in ReactNative.

The Vezgo Connect process, however, is compatible with oAuth 2.0 Authorization Code flow (https://datatracker.ietf.org/doc/html/rfc6749#section-4.1). Therefore it can be easily added to your mobile application using readily available oAuth mobile libraries.

We recommend the AppAuth oAuth library for integrating Vezgo Connect (or any oAuth 2.0 services) to your mobile application.

iOS/Mac: https://github.com/openid/AppAuth-iOS

Android: https://github.com/openid/AppAuth-Android

ReactNative: https://github.com/FormidableLabs/react-native-app-auth

Quickstart example

The best way to get started with Vezgo API is via the Vezgo JS SDKs (Frontend and Backend). You can take a look at the Vezgo Example project or follow the steps below:

1. Import the SDK

You can import the distribution build directly in your webpage:

<!-- Import the specific version -->
<script src="https://unpkg.com/vezgo-sdk-js@1.0.3/dist/vezgo.js"></script>

<!-- Or import the latest version (may contain breaking changes) -->
<script src="https://unpkg.com/vezgo-sdk-js/dist/vezgo.js"></script>


Or install and import it in a JS build system / NodeJS.

The same package is used for both frontend (web, mobile or desktop app) and backend (NodeJS).

npm install --save vezgo-sdk-js



// commonjs
const Vezgo = require('vezgo-sdk-js');

// esX
import Vezgo from 'vezgo-sdk-js';

2. Initialize the vezgo instance

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

const vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  // optional parameters for authenticating the vezgo frontend instance with your server.
  // See Authentication section for a more detailed explanation.
  authEndpoint: '/vezgo/auth', // default value, need to accept POST
  auth: {
    params: { userId: 'LOGGED_IN_USER_ID' }, // custom params for authEndpoint
    headers: {}, // custom headers for authEndpoint
  },
});

A vezgo instance is initialized using your Client ID and Client Secret in the backend, and only Client ID in the frontend.

const user = vezgo.login('USERNAME');

// No need to pass username because it's assumed that the `authEndpoint`
// implementation on your backend server should already know that from
// your authenticated user.
const user = vezgo.login();

Log in a user to create a user instance if you want to request user data.

3. Connect a user, or request for data.

// Get general Vezgo data
const providers = await vezgo.providers.getList();

// Get user data via the `user` instance
const account = await user.accounts.getOne('ACCOUNT_ID');

// Get general Vezgo data
const providers = await vezgo.providers.getList();

// Start the Connect process when user clicks the Connect button
document.getElementById('#connect').addEventListener('click', () => {
  user.connect().onConnection(async accountId => {
    const account = await user.accounts.getOne(accountId);
    displayAccount(account);
  });
}, false);

Start the Connect process for users to connect their accounts, or call the SDK helper methods to request for data.

Authentication

Authentication is required for user data endpoints / actions in the form of a Vezgo user token.

API clients (both frontend and backend) will need to obtain a token before making user data API calls for or opening the Vezgo Connect Widget.

The token must be included in the Authorization: Bearer ${token} header in your Vezgo API request, or in the ?token= query string in the Vezgo Connect Widget URL.

The token is short-lived and you will need to obtain a new one when it expires. Currently the default token lifetime is 20 minutes.

Backend clients

POST {VEZGO_API_URL}/auth/token

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

const user = vezgo.login('USERNAME_FROM_YOUR_SYSTEM');
const token = await user.getToken();

curl '{VEZGO_API_URL}/auth/token' \
  -X POST \
  -H 'loginName: USERNAME_FROM_YOUR_SYSTEM' \
  -H 'Content-Type: application/json' \
  -d '{
      "clientId": "YOUR_CLIENT_ID",
      "secret": "YOUR_CLIENT_SECRET"
  }'

The endpoint returns the following JSON:

{
  "token": "YOUR_USER_TOKEN"
}

The Vezgo user token can be requested by POSTing to {VEZGO_API_URL}/auth/token with:

POST /auth/token HTTP/1.1
Host: api.vezgo.com
Content-Type: application/json
loginName: USERNAME_FROM_YOUR_SYSTEM

{
  "clientId": "YOUR_CLIENT_ID",
  "secret": "YOUR_CLIENT_SECRET"
}


Frontend client

const vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  authEndpoint: '/vezgo/auth', // default value, your server should implement this endpoint
  auth: {
    params: { username: 'USERNAME_FROM_YOUR_SYSTEM' }
  }
});

const user = vezgo.login();
const token = await user.getToken();

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

app.post('/vezgo/auth', async (req, res) => {
  // Replace with your own authentication
  const { username } = req.body;
  const user = vezgo.login(username);

  res.json({ token: await user.getToken() });
});

Because the secret is required to obtain a user token, it will always need to be requested from your backend server which is supposed to store secret securely. Your frontend client will need to obtain a token via your backend server.

Your backend server could serve a /vezgo/token endpoint which authenticates and requests a user token on behalf of your frontend client.

Connect a user

The Vezgo Connect process allows users to connect their exchange accounts or wallet addresses to your application. There are different ways to start the process and receive the connection result.

The easiest way to do that is using the Vezgo JS SDK to open the drop-in Vezgo Connect Widget right inside your web application, and receive the result via JS callbacks.

Or you can use an oAuth process where you redirect users to the Vezgo Connect URL to connect their account, and have them redirected back to your application with the result. This oAuth process can be used in web, mobile or desktop applications.

Via drop-in Connect Widget

document.getElementById('#connect').addEventListener('click', () => {
  user.connect().onConnection(accountId => {
    // Send the account id to your server
    sendToServer('/some-route', accountId);
    // Request account data to display in the page
    const account = await user.accounts.getOne(accountId);
    displayAccount(account);
  });
}, false);

Start the connect process by calling user.connect() from your web application. It will open the Vezgo Connect Widget inside the page, and let the user select the exchange / wallet they want to connect.

- Receive via callbacks

user.connect().onConnection(async accountId => {
  console.log('account connection success:', accountId)
}).onError(error => {
  console.error('account connection error:', error)
}).onEvent((name, data) => {
  console.log('account connection event:', name, data);
});

The drop-in Connect Widget sends data to the Vezgo Frontend SDK via 3 callbacks:

onConnection(accountId)

The onConnection() callback listens for successful connection from the Connect Widget. After user successfully connects their account, the Widget is automatically closed and the callback is called with an accountId that belongs to a newly-created Vezgo account. This Vezgo account is kept in sync with the user's connected exchange account / wallet.

It is recommended that you store this accountId in your database for future updates.

onError(error)

The onError() callback listens for errors from the Connect Widget. During the process, if there is an error or if user clicks the close (X) button, the Widget is closed and the callback is called with an error object.

error object attributes

Attribute Description
error_type The error code, e.g. 400.
message The error message.
account The account ID if it has been created.

onEvent(name, data) (pending)

The onEvent() callback listens for events from the Connect Widget during the connection process. There are multiple events corresponding with the multiple steps of the connection process that keep your web application notified of the process inside the Widget so it can act accordingly.

Supported events

This list is pending and are not yet available.

Event Data Description
OPEN {} The Widget is ready (fully loaded and waiting for user actions).
ACCEPT {} User has accepted Vezgo terms and policy.
SEARCH { keyword } User has searched for a provider in the provider selection screen.
keyword contains the keyword user has typed in.
SELECT_PROVIDER { provider } User has selected a provider.
provider is the Provider object.
SUBMIT_CREDENTIALS {} User has submitted their credentials for the exchange/wallet. User credentials are secured and won't be available to the SDK.
CLOSE {} The Widget has been closed automatically. Directly followed by onConnection() or onError().
FORCE_CLOSE {} The Widget has been closed by the user. Directly followed by onError().

- Customize Connect Widget

<html>
<head>
  <style>
    iframe[name='vezgo-connect-widget'] {
      border: 1px solid gray;
      width: 300px;
      height: 500px;
      display: none;
    }
  </style>
</head>
<body>
  <nav>Nav bar</nav>
  <section>
    <h1>Connect your account</h1>

    <button id="connect">Connect</button>
    <iframe name='vezgo-connect-widget'></iframe>
  </section>
</body>
</html>

Under the hood, the Connect Widget is loaded inside a <iframe name='vezgo-connect-widget> element. By default, the .connect() method appends the iframe at the root of your page's <body>, with special styling so that it appears as an overlay inside the page.

You can customize the styling of the widget overlay via the vezgo-connect-widget.

If you need to control where the iframe is inside your page, you can pre-create the <iframe name='vezgo-connect-widget> anywhere in your page and the .connect() method will load the Connect Widget inside that element instead of creating a new one.

NOTE: the JS SDK will add display: block style to the iframe when opening the Connect Widget, and display: none when closing it.

- Preselect a provider

document.getElementById('#connect_bitcoin').addEventListener('click', () => {
  user.connect({ provider: 'bitcoin' }).onConnection(accountId => {
    console.log('bitcoin connection success:', accountId)
  });
}, false);

By default .connect() will open the Vezgo providers list for user to select from. Alternately you can pass in a provider name to skip the selection step so that Vezgo Connect Widget go straight to the provider credentials form.

NOTE: Pass in the provider name that you get from the Provider object, not display_name.

- Reconnect an account

When an account's credentials expire or are revoked, Vezgo will no longer be able to synchronize its data from the provider. The account is put in a 'disconnected' state and will need to be reconnected.

To allow a user to reconnect a disconnected account, call user.reconnect(accountId) from your web application. It will open the Vezgo Connect Widget inside the page, and let the user reconnect the account. The process is almost identical to connecting a new account, except that at the end of the process it would update the existing account instead of creating a new one.

Via Connect URL

Another way to connect an user is via the Vezgo Connect URL directly. You can load the Vezgo Connect URL using your own method (redirect from the current page or open in a new window, or inside a mobile WebView...).

You can customize various aspects of the Vezgo Connect process via the url params. A standard Vezgo Connect URL looks something like this:

POST https://connect.vezgo.com/connect?client_id=YOUR_CLIENT_ID

Form Data (x-www-form-urlencoded):
token=USER_TOKEN


Or with preselected provider:

POST https://connect.vezgo.com/connect/bitcoin?client_id=YOUR_CLIENT_ID

Form Data (x-www-form-urlencoded):
token=USER_TOKEN


To reconnect account:

POST https://connect.vezgo.com/reconnect/ACCOUNT_ID?client_id=YOUR_CLIENT_ID

Form Data (x-www-form-urlencoded):
token=USER_TOKEN


Connect URL parameters

Parameter Required Description
client_id Yes Your team's Client ID.
token Yes The user token. See Authentication to see how to get the token.
redirect_uri No The URI to redirect to after the process is finished. This must match one of your team's registered Redirect URIs. More on this here.
origin No The URL origin that triggers the process (e.g. https://some.domain). This is used mostly for when the Vezgo Connect is loaded inside an iframe, so it can pass data back to the parent page at the specified origin.
lang No The content language. Currently only en, es, fr and it are accepted.
state No An opaque string containing your application state, to maintain application state between redirects (in the oAuth process).
providers No Limit the list of providers available for selection.
Example: binance,coinbase,ethereum.
theme No Vezgo Connect widget theme. Available options: light, dark. Default: light.
providers_per_line No The number of providers displayed per line on the select provider screen. Available options: 1, 2.
Default: 2.
sync_nfts No Show "Sync NFTs" checkbox. Available for proviers which support "sync_nft" feature and also if "sync_nft" feature enabled for the team (depends on plan). Boolean.
Default: false.

- Receive via URL params

The connection result is returned in the URL params at the end of the process. If you open the Connect URL inside an iframe, popup, or mobile WebView, you can expect the process to redirect to this URL when connection is successful:

https://connect.vezgo.com/connected?account=ACCOUNT_ID&code=ACCOUNT_ID


And to this URL when connection failed or is interrupted:

https://connect.vezgo.com/exit?error_type=400&message=ERROR_MESSAGE


Custom Redirect URI

You can pass in the Vezgo Connect URL a custom redirect_uri so that it redirects to this uri at the end of the process.

For example, load the following Vezgo Connect URL:

POST https://connect.vezgo.com/connect?client_id=YOUR_CLIENT_ID&redirect_uri=https://myapp.test/crypto&state=APP_STATE_BEFORE_CONNECTION_IN_BASE64

Form Data (x-www-form-urlencoded):
token=USER_TOKEN


After user finishes connecting an account, it will redirect to:

https://myapp.test/crypto?account=ACCOUNT_ID&code=ACCOUNT_ID&state=APP_STATE_BEFORE_CONNECTION_IN_BASE64


Or if the connection failed or user closes the process, it will redirect to:

After user finishes connecting an account, it will redirect to:

https://myapp.test/crypto?error_type=400&message=Invalid+credentials&state=APP_STATE_BEFORE_CONNECTION_IN_BASE64


In both cases, your page at https://myapp.test/crypto can look at the URL params and proceed accordingly. Optionally if you passed in a state, you will receive it back here to restore your application to the same state before the connection.

All redirection URL params

Parameter Type On Description
account String Both The Vezgo account id corresponding to the newly-connected exchange account / wallet.
Note that it's returned on Failure ONLY if it has been created before the error happens.
code String Success Same as account. For oAuth compliance.
error_type Number Failure The connection error code.
message String Failure The connection error message.
force Boolean Failure true means the process was explicitly closed by user.
state String Both The application state passed to the Vezgo Connect URL at the start of the process (if available).

Receive via Webhook

Server-based applications may receive connection events via Webhooks.

Currently Webhooks are enabled on request only. Contact us if you need to enable Webhooks. We would need the url where you would like to receive the webhooks.

SyncAccount

A SyncAccount webhook can be sent to your receiving endpoint via a POST when an account successfully syncs. The account refresh happens once daily, or on demand (when you POST to /accounts/:id/sync endpoint). The webhook is triggered at the end of the process if it’s successful. It would have the following schema in the body JSON:

{
  hook: "SyncAccount",
  user: { id, loginName },
  account: { id, provider }
}

User API endpoints

These endpoints return user data and thus require a Vezgo user token.

Get accounts list

HTTP request:

GET VEZGO_API_URL/accounts

Code example:

curl 'VEZGO_API_URL/accounts' \
  -H 'Authorization: Bearer VEZGO_USER_TOKEN'

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

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

This endpoint returns the following JSON:

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

This endpoint returns the list of a user's connected accounts.

Object description

Account

Get an account

HTTP request:

GET VEZGO_API_URL/accounts/:account_id

Code example:

curl 'VEZGO_API_URL/accounts/ACCOUNT_ID' \
  -H 'Authorization: Bearer VEZGO_USER_TOKEN'

const accounts = await user.accounts.getOne('ACCOUNT_ID');

const accounts = await user.accounts.getOne('ACCOUNT_ID');

This endpoint returns the following JSON:

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

This endpoint returns a specific account.

Object description

Account

Sync an account

HTTP request:

POST VEZGO_API_URL/accounts/:account_id/sync

Code example:

curl 'VEZGO_API_URL/accounts/ACCOUNT_ID/sync' \
  -X POST \
  -H 'Authorization: Bearer VEZGO_USER_TOKEN'

const account = await user.accounts.sync('ACCOUNT_ID');

const account = await user.accounts.sync('ACCOUNT_ID');

This endpoint returns a 202 status code and the following JSON if successful:

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

This endpoint triggers an account sync.

Vezgo automatically synchronizes all accounts with providers once daily. You can also triggers an account sync at any time to get the latest data.

Responses

Status Description
202 A sync has successfully started. The latest account object (typically with status: 'syncing' will be returned along with this status code.
400 The request has been rejected. This usually happens when the account is disconnected (the last sync failed due to expired/revoked credentials), in which case the account must be reconnected first.
409 A sync is already in progress.

Object description

Account

Remove an account

HTTP request:

DELETE VEZGO_API_URL/accounts/:account_id

Code example:

curl 'VEZGO_API_URL/accounts/ACCOUNT_ID' \
  -X DELETE \
  -H 'Authorization: Bearer VEZGO_USER_TOKEN'

await user.accounts.remove('ACCOUNT_ID');

await user.accounts.remove('ACCOUNT_ID');

This endpoint returns a 204 status code if success.

This endpoint removes a specific account and all of its data from a user.

Responses

Status Description
204 The account has been successfully removed.

Get transaction history

HTTP request:

GET VEZGO_API_URL/accounts/:account_id/transactions

Code example:

curl 'VEZGO_API_URL/accounts/ACCOUNT_ID/transactions?ticker=BTC&wallet=bitcoin:cash:usd&from=2021-01-01&to=2021-10-01'
  -H 'Authorization: Bearer VEZGO_USER_TOKEN'

const transactions = await user.transactions.getList({
  accountId: 'ACCOUNT_ID',
  ticker: 'BTC',
  from: '2021-01-01',
  to: '2021-09-09',
  wallet: 'bitcoin:cash:usd',
});

const transactions = await user.transactions.getList({
  accountId: 'ACCOUNT_ID',
  ticker: 'BTC',
  from: '2021-01-01',
  to: '2021-09-09',
  wallet: 'bitcoin:cash:usd',
});

This endpoint returns the following JSON:

[
  {
    "id": "603522490d2b02001233a5d6",
    "resource_type": "transaction",
    "status": null,
    "transaction_type": "deposit",
    "fiat_calculated_at": 1630412605283,
    "initiated_at": 1630412605283,
    "confirmed_at": 1630412605283,
    "wallet": "bitcoin:cash:usd",
    "account": "603522490d2b02001233a5d7",
    "misc": {
      "origin_id": "original_id_or_hash"
    },
    "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": null,
        "fiat_value": null,
        "fiat_asset_is_verified": null,
        "resource_type": "transaction_fee"
      }
    ]
  },
  // truncated
]

This endpoint returns the transactions history for an account.

By default, data for the current year is returned.

Object description

Transaction

Query Parameters

Parameter Type Required Description
ticker string No currency ticker to filter by.
from string No The start date of the period to perform the query. This cannot be a date after to date. Defaults to start of the current year.
to string No The end date of the period to perform the query. This cannot be a date before from date. Defaults to today.
last string No The ID for a last-known transaction. When this is passed in, only transactions newer than this one (by creation date) will be returned. Will trigger Pagination mode.
limit number No The number of transactions to return. Must be between 10 - 1000. Will trigger Pagination mode. Defaults to 100 in pagination mode.
wallet string No The account wallet to filter by.

NOTES:

IMPORTANT: We have a hard limit of 6MB response size for transactions.

If you are already passing ?limit then it should be good.

But if you are passing in a large ?from=&to= range, or querying a very large account without passing in ?limit, any request returning more than 6MB of response will be dropped.

Pagination

By default, transactions are sorted by transaction.initiated_at in ascending order.

When a last or limit is passed to the query, pagination mode is enabled. In this mode, transactions are sorted by their creation date (the date on which the transaction is added to the Vezgo system).

Get all transactions

const transactions = [];
const accountId = '603522490d2b02001233a5d6';

// Provide the date the wallet or exchange account was created. If unsure,
// pass in a very old date.
const from = '2005-01-01';

// Start off with an empty ?last, to query the very first page of transactions
let last = '';

while (true) {
    const page = await user.transactions.getList({ accountId, from, last });

    if (!page.length) break;

    transactions.push(...page);
    // Use this page's last transaction id to query the next page and so on
    last = page[page.length - 1].id;
}

To fetch all transactions, we need to enable pagination and go page-by-page.

First make a request with an empty last (?last=) for the first page. Then use the last transaction's ID from the first page to query the next page ?last=LAST_TRANSACTION_ID, and so on.

NOTES:

Get a specific transaction

HTTP request:

GET VEZGO_API_URL/accounts/:account_id/transactions/:tx_id

Code example:

curl 'VEZGO_API_URL/accounts/ACCOUNT_ID/transactions/TRANSACTION_ID' \
  -H 'Authorization: Bearer VEZGO_USER_TOKEN'

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

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

This endpoint returns the following JSON:

{
  "id": "603522490d2b02001233a5d6",
  "resource_type": "transaction",
  "status": null,
  "transaction_type": "deposit",
  "fiat_calculated_at": 1630412605283,
  "initiated_at": 1630412605283,
  "confirmed_at": 1630412605283,
  "wallet": "bitcoin:cash:usd",
  "account": "603522490d2b02001233a5d7",
  "misc": {
    "origin_id": "original_id_or_hash"
  },
  "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": null,
      "fiat_value": null,
      "fiat_asset_is_verified": null,
      "resource_type": "transaction_fee"
    }
  ]
}

This endpoint returns a transaction.

Object description

Transaction

Get balance history

HTTP request:

GET VEZGO_API_URL/accounts/:account_id/history

Code example:

curl 'VEZGO_API_URL/accounts/ACCOUNT_ID/history?wallet=bitcoin:cash:usd&from=2021-01-01&to=2021-10-01'
  -H 'Authorization: Bearer VEZGO_USER_TOKEN'

const history = await user.history.getList({
  accountId: 'ACCOUNT_ID',
  from: '2021-01-01',
  to: '2021-09-09',
  wallet: 'bitcoin:cash:usd',
});

const history = await user.history.getList({
  accountId: 'ACCOUNT_ID',
  from: '2021-01-01',
  to: '2021-09-09',
  wallet: 'bitcoin:cash:usd',
});

This endpoint returns the following JSON:

[
  {
    "id": "6144755af8a77cae7174afa3",
    "date": 1630412605283,
    "wallet": "demo:cash:usd",
    "account": "603522490d2b02001233a5d7",
    "fiat_ticker": "USD",
    "fiat_value": "125.30"
  },
  // truncated
]

This endpoint returns the balance history for an account.

By default, data for the current year is returned.

NOTE: An account's balance history starts from the date the account was first connected to Vezgo.

Object description

History Entry

Query Parameters

Parameter Type Required Description
from string No The start date of the period to perform the query. This cannot be a date after to date. Defaults to start of the current year.
to string No The end date of the period to perform the query. This cannot be a date before from date. Defaults to today.
wallet string No The account wallet to filter by.

General data endpoints

These endpoints provide general information and thus do not require a Vezgo user token.

Get providers list

HTTP request:

GET VEZGO_API_URL/providers

Code example:

curl 'VEZGO_API_URL/providers'

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

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

This endpoint returns the following JSON:

[
  {
    "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": null,
    "credentials": ["code"]
  },
  {
    "name": "bitcoin",
    "display_name": "Bitcoin",
    "logo": "https://app.wealthica.com/images/institutions/bitcoin.png",
    "auth_type": "wallet",
    "available_scopes": [],
    "available_currencies": null,
    "resource_type": "provider",
    "status": null,
    "is_beta": false,
    "connect_notice": null,
    "credentials": ["wallet"]
  },
  // truncated
]

This endpoint returns the list of supported providers.

Object description

Provider

Get a provider

HTTP request:

GET VEZGO_API_URL/providers/:name

Code example:

curl 'VEZGO_API_URL/providers/coinbase'

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

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

This endpoint returns the following JSON:

{
  "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": null,
  "credentials": ["code"]
}

This endpoint returns a provider.

Object description

Provider

Vezgo objects

Account

{
  "id": "603522490d2b02001233a5d6",
  "resource_type": "account",
  "blockchain": null,
  "created_at": 1630412605283,
  "updated_at": 1630412605283,
  "fiat_value": "4321.98",
  "fiat_ticker": "USD",
  "status": "ok",
  "status_details": {
    "date": "2022-07-14T12:51:29.370Z",
    "wallets": "ok",
    "balances": "ok",
    "transactions": "ok",
  },
  "provider": {
    "name": "bitcoin",
    "display_name": "Bitcoin",
    "logo": "https://app.wealthica.com/images/institutions/bitcoin.png",
    "type": "wallet",
    "scopes": [],
    "resource_type": "provider"
  },
  "wallets": [
    {
      "id": "bitcoin:cash:usd",
      "name": "Bitcoin",
      "address": "n2nL15YewGVfmteA1ptLbeimKjQPRamU8y",
      "fiat_ticker": "USD",
      "fiat_value": "2021.08"
    }
  ],
  "balances": [
    {
      "ticker": "BTC",
      "provider_ticker": "BTC",
      "name": "Bitcoin",
      "asset_is_verified": null,
      "asset_type": null,
      "amount": "0.20210831",
      "decimals": 8,
      "fiat_value": "2021.08",
      "fiat_ticker": "USD",
      "fiat_asset_is_verified": null,
      "logo": "https://data.wealthica.com/api/securities/CRYPTO:BTC/logo",
      "updated_at": 1630412605283,
      "wallet": "bitcoin:cash:usd",
      "misc": null,
      "resource_type": "balance"
    }
  ]
}
Attribute Type Format Description
id String ID The Vezgo account identifier.
resource_type String Resource Type Resource type for this object (which is "account").
blockchain String, null Blockchain ID (wallet accounts only) The blockchain holding the account. null for accounts coming from a cryptocurrency exchange.
NOTE: not yet implemented, always null for now.
created_at Number Timestamp The Vezgo account's creation date (milliseconds since Epoch).
updated_at Number Timestamp The Vezgo account's last updated date (milliseconds since Epoch).
status String Account Status The account's connection status.
status_details Object Status Details Detailed status for the last sync.
error Object Account Error The account's connection error. Only returned when there is an error.
fiat_value String Number Total fiat value of the account (string representation of a number).
fiat_ticker String Ticker The fiat currency in which the account's fiat_value is reported.
provider Object Provider The provider holding the account.
wallets Array [Wallet] The list of wallets in the account.
balances Array [Balance] The list of asset balances in the account.

Wallet

{
  "id": "bitcoin:cash:usd",
  "name": "Bitcoin",
  "address": "n2nL15YewGVfmteA1ptLbeimKjQPRamU8y",
  "fiat_ticker": "USD",
  "fiat_value": "2021.08"
}
Attribute Type Format Description
id String Wallet ID Unique identifier for a wallet within an account.
name String, null Wallet name, for display purpose. Not always available.
address String, null Wallet Address The wallet address, for display purpose. Not always available.
fiat_value String Number The total fiat value of the wallet (string representation of a number).
fiat_ticker String Ticker The fiat currency in which fiat_value is reported.

Account Status

Value Description
ok The last sync attempt successfully synced the wallets & balances.
error There was an error during the last sync attempt.
syncing A synchronization is in progress.
retry The last sync attempt was not successful and a retry has been scheduled.

Status Details

Attribute Type Format Description
wallets String Status Status on fetching wallets for the last sync.
balances String Status Status on fetching balances for the last sync.
transactions String Status Status on fetching transactions for the last sync.
date Date date The date when the status was recorded.

Status

Value Description
ok The last sync attempt was successful.
error There was an error during the last sync attempt.
retry The last sync attempt was not successful and a retry has been scheduled.

Account Error

Attribute Type Description
name String The error name.
LoginFailedError: The account credentials are invalid, have expired or been revoked. There will be no more sync attempt until this is fixed by the user via Reconnect process.
SecurityQuestionError: The sync process was blocked by a security question. There will be no more sync attempt until this is fixed by the user via Reconnect process.
TemporaryFailureError, UnknownConnectorError, UnhandledConnectorError: A temporary error was encountered during sync process (e.g. an unhandled error, orr the provider was unreachable, etc.). Our system will automatically retry to sync the account.
message String The error message, or the question in the case of SecurityQuestionError.
options Array Options for answering SecurityQuestionError (array of strings). Only returned with SecurityQuestionError if the security question has answer options.

Balance

Crypto Balance

{
  "resource_type": "balance",
  "ticker": "BTC",
  "provider_ticker": "BTC",
  "ticker_address": null,
  "name": "Bitcoin",
  "wallet": "bitcoin:cash:usd",
  "asset_type": null,
  "amount": "0.20210831",
  "decimals": 8,
  "asset_is_verified": null,
  "fiat_value": "2021.08",
  "fiat_ticker": "USD",
  "fiat_asset_is_verified": null,
  "logo": "https://data.wealthica.com/api/securities/CRYPTO:BTC/logo",
  "updated_at": 1630412605283,
  "misc": null
}

NFT Balance

{
  "ticker": "0X30A2FA3C93FB9F93D1EFEFFD350C6A6BB62BA000-33",
  "provider_ticker": "0X30A2FA3C93FB9F93D1EFEFFD350C6A6BB62BA000-33",
  "name": "Sedan #33",
  "asset_is_verified": null,
  "asset_type": "nft",
  "amount": "1.00",
  "decimals": null,
  "fiat_ticker": "USD",
  "fiat_value": 520.15,
  "fiat_asset_is_verified": null,
  "wallet": "0:cash:usd",
  "logo": "https://data.wealthica.com/api/securities/CRYPTO:0X30A2FA3C93FB9F93D1EFEFFD350C6A6BB62BA000-33/logo",
  "updated_at": 1670930713125,
  "misc": {
    "metadata": {
      "name": "Sedan #33",
      "media_url": "https://cryptomotors.io/images/full_vehicle_body/sedan_00_7_1_1.png",
      "contract_address": "0x30a2fa3c93fb9f93d1efeffd350c6a6bb62ba000",
      "token_id": "33",
      "contract_type": "erc721"
    },
    "origin_metadata": null
  },
  "resource_type": "balance"
}
Attribute Type Format Description
resource_type String Resource Type Resource type for this object (which is "balance").
ticker String Ticker Ticker symbol for the asset reported by this balance.
provider_ticker String Ticker Ticker symbol for the asset, as reported by the account's provider.
name String, null The asset name.
asset_type String, null Asset Type The asset's type or book-keeping model (e.g. "utxo").
NOTE: not yet implemented, always null for now, except for NFTs (nft in that case).
amount String Number The current balance of the asset (string representation of a number).
decimals Number, null The number of decimal places for the asset's lowest denominator (e.g. 8 for Bitcoin).
asset_is_verified Boolean, null Whether the asset's amount is verified. false means amount comes "as-is" from the provider without being processed by Vezgo (could be in a wrong format).
NOTE: not yet implemented, always null for now.
fiat_value String, null Number The fiat value of the asset (string representation of a number).
fiat_ticker String, null Ticker The fiat currency in which fiat_value is reported.
fiat_asset_is_verified Boolean, null Whether the asset's fiat_value is verified. false means fiat_value comes "as-is" from the provider without being processed by Vezgo (could be in a wrong format).
NOTE: not yet implemented, always null for now.
logo String, null URL The logo URL for the asset if it's a cryptocurrency, or null if it's a fiat currency.
updated_at Number Timestamp The balance's last updated date (milliseconds since Epoch).
wallet String Wallet ID ID of the wallet in which this balance is reported.
misc Object, null Miscellaneous information for the balance. Non standardized and could be null. For NFTs, has metadata standardized object and origin_metadata, that is not standardized.

Transaction

{
  "id": "603522490d2b02001233a5d6",
  "resource_type": "transaction",
  "status": null,
  "transaction_type": "deposit",
  "fiat_calculated_at": 1630412605283,
  "initiated_at": 1630412605283,
  "confirmed_at": 1630412605283,
  "wallet": "bitcoin:cash:usd",
  "account": "603522490d2b02001233a5d7",
  "misc": {
    "origin_id": "original_id_or_hash"
  },
  "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,
      "from_address": "bc1qmvumgzaa5j8n98vfhyq0chszpqv5qksmusug0x",
      "to_address": "bc1qlywq7u5xngqwsahe04wl9s35m6eqanzfeeqawc",
      "other_parties": ["bc1qmvumgzaa5j8n98vfhyq0chszpqv5qksmusug0x"]
    }
  ],
  "fees": [
    {
      "type": null,
      "ticker": "USD",
      "provider_ticker": "USD",
      "amount": "0.5",
      "asset_is_verified": null,
      "fiat_ticker": null,
      "fiat_value": null,
      "fiat_asset_is_verified": null,
      "resource_type": "transaction_fee"
    }
  ]
}
Attribute Type Format Description
id String ID The Vezgo transaction identifier.
resource_type String Resource Type Resource type for this object (which is "transaction").
status String, null Transaction Status The transaction status.
NOTE: not yet implemented, always null for now.
transaction_type String Transaction Type The transaction type.
fiat_calculated_at Number Timestamp The date when fiat_values from the transaction parts were calculated (milliseconds since Epoch).
initiated_at Number Timestamp The date when the transaction was initiated (milliseconds since Epoch).
confirmed_at Number, null Timestamp The date when the transaction was confirmed (milliseconds since Epoch). Could be null if the transaction hasn't been confirmed.
wallet String Wallet ID ID of the wallet in which this transaction is reported.
misc Object Transaction Misc Miscellaneous information for the transaction.
parts Array Transaction Part One or more transaction parts.
fees Array [Transaction Fee] The list of fees incurred by this transaction. Could be empty if the transaction generated no fee.

Transaction Type

Value Description
deposit (Usually 1-part) transactions where the amount was sent to the account (direction: received).
withdrawal (Usually 1-part) transactions where the amount was sent from the account (direction: sent).
trade (Usually 2-part) transactions with both sent and received directions.
other Other transactions not matching any of the above types.

Transaction Part

{
  "id": "603522490d2b02001233a5d6",
  "direction": "received",
  "ticker": "BTC",
  "provider_ticker": "BTC",
  "ticker_address": null,
  "amount": "1.20210831",
  "asset_is_verified": null,
  "fiat_ticker": "USD",
  "fiat_value": "1234567.8",
  "fiat_asset_is_verified": null,
  "from_address": "bc1qmvumgzaa5j8n98vfhyq0chszpqv5qksmusug0x",
  "to_address": "bc1qlywq7u5xngqwsahe04wl9s35m6eqanzfeeqawc",
  "other_parties": [],
  "misc": {},
}
Attribute Type Format Description
id String ID The Vezgo transaction part identifier.
direction String sent, received The financial direction for this transaction part.
ticker String Ticker Ticker symbol for the asset involved in this transaction part.
provider_ticker String Ticker Ticker symbol for the asset, as reported by the account's provider.
ticker_address String Address Address of the token, e.g. ERC20 token on an EVM-based connection.
amount String, null Number The asset amount involved in this transaction part (string representation of a number).
asset_is_verified Boolean, null Whether the transaction's amount is verified. false means amount comes "as-is" from the provider without being processed by Vezgo (could be in a wrong format).
NOTE: not yet implemented, always null for now.
fiat_value String, null Number The fiat value of the transaction part (string representation of a number).
fiat_ticker String Ticker The fiat currency in which fiat_value is reported.
fiat_asset_is_verified Boolean, null Whether the transaction's fiat_value is verified. false means fiat_value comes "as-is" from the provider without being processed by Vezgo (could be in a wrong format).
NOTE: not yet implemented, always null for now.
to_address String, null Address Address of the wallet that receives the asset
from_address String, null Address Address of the wallet that sends the asset
other_parties Array List of other cryptocurrency accounts (source addresses for received or recipient addresses for sent) involved in this transaction part.
misc Object Transaction Misc Miscellaneous information for the transaction.

Transaction Fee

{
  "id": "603522490d2b02001233a5d6",
  "resource_type": "transaction_fee",
  "type": null,
  "ticker": "USD",
  "provider_ticker": "USD",
  "amount": "0.5",
  "asset_is_verified": null,
  "fiat_ticker": null,
  "fiat_value": null,
  "fiat_asset_is_verified": null
}
Attribute Type Format Description
id String ID The Vezgo transaction fee identifier. If this is the same as a transaction part, it means the fee is applied to that part.
resource_type String Resource Type Resource type for this object (which is "transaction_fee").
type String, null network, exchange The fee type (or source of fee) for the transaction.
NOTE: not yet implemented, always null for now.
ticker String Ticker Ticker symbol for the asset charged in this transaction fee.
provider_ticker String Ticker Ticker symbol for the asset, as reported by the account's provider.
amount String Number The asset amount charged in this transaction fee (string representation of a number).
asset_is_verified Boolean, null Whether the fee's amount is verified. false means amount comes "as-is" from the provider without being processed by Vezgo (could be in a wrong format).
NOTE: not yet implemented, always null for now.
fiat_value String, null Number The fiat value of the transaction fee (string representation of a number).
fiat_ticker String, null Ticker The fiat currency in which fiat_value is reported.
fiat_asset_is_verified Boolean, null Whether the fee's fiat_value is verified. false means fiat_value comes "as-is" from the provider without being processed by Vezgo (could be in a wrong format).
NOTE: not yet implemented, always null for now.

Transaction Misc

{
  "origin_id": "original_id_or_hash",
  "incomplete": [],
}
Attribute Type Description
origin_id String Original transaction id if it comes from an exchange, or transaction hash if from a blockchain.
origin_type String Original transaction type as seen in the blockchain/exchange.
incomplete Array List of attributes that are incomplete and thus should not be trusted. This should be empty in most cases but if it isn't, it might be indicative of an error in our connector and should be reported to the Vezgo team. Possible values: fiat_value, amount, ticker, fees.

History Entry

{
  "id": "6144755af8a77cae7174afa3",
  "date": 1630412605283,
  "wallet": "demo:cash:usd",
  "account": "603522490d2b02001233a5d7",
  "fiat_ticker": "USD",
  "fiat_value": "125.30"
}
Attribute Type Format Description
id String ID The Vezgo history entry identifier.
date Number Timestamp The date when the history entry was recorded (milliseconds since Epoch).
wallet String Wallet ID ID of the account wallet recorded in this history entry.
fiat_value String Number Total fiat value of the account wallet at the recorded date (string representation of a number).
fiat_ticker String Ticker The fiat currency in which this history entry's fiat_value is reported.

Provider

{
  "resource_type": "provider",
  "name": "coinbase",
  "display_name": "Coinbase",
  "logo": "https://app.wealthica.com/images/institutions/coinbase.png",
  "auth_type": "oauth",
  "available_scopes": [],
  "available_currencies": null,
  "status": null,
  "is_beta": true,
  "connect_notice": null,
  "credentials": ["code"]
}
Attribute Type Format Description
resource_type String Resource Type Resource type for this object (which is "provider").
name String Provider Name The provider's unique name that is used as identification within the Vezgo system.
display_name String The provider's human-friendly name, to be used for display purpose.
logo String URL The logo URL for the provider.
auth_type String password, oauth, token, wallet The provider's authentication type.
available_scopes Array Provider Scope The scopes of access allowed by the provider.
NOTE: not fully implemented, scope objects (if available) contain only name for now.
available_currencies Array, null Provider Currency The list of currencies supported by the provider.
NOTE: not yet implemented, always null for now.
status String, null Provider Status The provider's service status.
NOTE: not yet implemented, always null for now.
is_beta Boolean Whether the Vezgo support for this provider is still beta. See https://vezgo.com/status for up-to-date development status on all providers.
connect_notice String, null Number Notes regarding the provider's connection process.
credentials Array List of credential information requested by the provider, as an array of the following possible values: username, password, token, key, secret, wallet, code.

Errors

The Vezgo API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your token is missing, invalid or has expired.
404 Not Found -- The specified resource could not be found.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
Vezgo Frontend JS Vezgo Backend JS REST