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 10 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 POST
ing to {VEZGO_API_URL}/auth/token
with:
- Your team's Client Id and Client Secret, which you get when signing up for Vezgo API. Passed as
clientId
&secret
in request body JSON. - The user's unique identification from your system (could be the username, id, or email). Passed as
loginName
in request header.
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)
onError(error)
onEvent(name, data)
(pending)
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
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
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. |
429 | A sync request is tried before the cooldown period (Which is 2 minutes by default). You will receive a retry-after response header indicating when to retry this request (in seconds). |
Object description
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
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:
- Due to trade reconciliation,
?limit
doesn't guarantee the exact number of results to be returned. E.g.?limit=10
might return 9 or fewer transactions, depending on how many times trade reconciliation happens within the 10 transactions queried from our DB. - Trade reconciliation is a process where 2 or more transactions that are originally part of a trade are combined into a single
transaction_type: 'trade'
transaction. This process is neccessary due to a current limitation in the Vezgo system, and will be removed in the next version of Vezgo API.
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:
- The same
?from
param must be provided in all requests (see example code). - If
?from
is not passed, it defaults to the start of the current year. If you want to get all transactions including previous years, pass a very old date (see example code).
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
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
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
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
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": "0x30a2fa3c93fb9f93d1efeffd350c6a6bb62ba000",
"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. |
ticker_address |
String |
Address | Address of the token, e.g. ERC20 token on an EVM-based connection. |
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_value s 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. |
Streaming
Vezgo Streaming enables client applications to receive real-time events via Webhooks.
Currently Streaming feature is enabled on request only. Contact us if you need to enable Streaming. We would need the url where you would like to receive the webhook events.
Account Events
A webhook event is sent to your receiving endpoint via a POST
when there is any update from account. The request payload would have the following schema :
{
"institution_id": "603522490d2b02001233a5d6",
"app_id": "your_app_id",
"websocket_id": 8267675,
"message": {
// Event information that triggered webhook
},
"hook" : "newAccountEvent",
}
Event Details
Attribute | Type | Format | Description |
---|---|---|---|
institution_id |
String |
ID | The Vezgo account id. |
app_id |
String |
ID | Your app id. |
websocket_id |
Number |
ID | A unique websocket id |
message |
Object |
Message | Event details |
hook |
String |
Event | Name of event |
Event
Value | Description |
---|---|
newAccountEvent |
Whenever there is an update from account. |
Supported Exchanges
You can find the webhook event's message field format for different exchanges below :
- Binance
Currently, we send events for spot wallet updates only. The events triggered are as follows :
message: outboundAccountPosition
This event is sent any time an account balance has changed and contains the assets that were possibly changed by the event that generated the balance change.
outboundAccountPosition
{
"institution_id": "603522490d2b02001233a5d6",
"app_id": "your_app_id",
"websocket_id": 8298322,
"message": {
"e": "outboundAccountPosition", // Event type
"E": 1564034571105, // Event Time
"u": 1564034571073, // Time of update
"B": [ // Balances Array
{
"a": "ETH", // Asset
"f": "10000.000000", // Free
"l": "0.000000" // Locked
}
]
},
"hook": "newAccountEvent",
}
message: balanceUpdate
Balance Update occurs during the following:
- Deposits or withdrawals from the account
- Transfer of funds between accounts (e.g. Spot to Margin)
balanceUpdate
{
"institution_id": "603522490d2b02001233a5d6",
"app_id": "your_app_id",
"websocket_id": 8298322,
"message": {
"e": "balanceUpdate", // Event Type
"E": 1573200697110, // Event Time
"a": "BTC", // Asset
"d": "100.00000000", // Balance Delta
"T": 1573200697068 // Clear Time
},
"hook": "newAccountEvent",
}
message: executionReport
Orders are updated with the executionReport event.
executionReport
{
"institution_id": "603522490d2b02001233a5d6",
"app_id": "your_app_id",
"websocket_id": 1862227,
"message": {
"e": "executionReport", // Event type
"E": 1499405658658, // Event time
"s": "ETHBTC", // Symbol
"c": "mUvoqJxFIILMdfAW5iGSOW", // Client order ID
"S": "BUY", // Side
"o": "LIMIT", // Order type
"f": "GTC", // Time in force
"q": "1.00000000", // Order quantity
"p": "0.10264410", // Order price
"P": "0.00000000", // Stop price
"d": 4, // Trailing Delta; This is only visible if the order was a trailing stop order.
"F": "0.00000000", // Iceberg quantity
"g": -1, // OrderListId
"C": "", // Original client order ID; This is the ID of the order being canceled
"x": "NEW", // Current execution type
"X": "NEW", // Current order status
"r": "NONE", // Order reject reason; will be an error code.
"i": 4293153, // Order ID
"l": "0.00000000", // Last executed quantity
"z": "0.00000000", // Cumulative filled quantity
"L": "0.00000000", // Last executed price
"n": "0", // Commission amount
"N": null, // Commission asset
"T": 1499405658657, // Transaction time
"t": -1, // Trade ID
"v": 3, // Prevented Match Id; This is only visible if the order expire due to STP trigger.
"I": 8641984, // Ignore
"w": true, // Is the order on the book?
"m": false, // Is this trade the maker side?
"M": false, // Ignore
"O": 1499405658657, // Order creation time
"Z": "0.00000000", // Cumulative quote asset transacted quantity
"Y": "0.00000000", // Last quote asset transacted quantity (i.e. lastPrice * lastQty)
"Q": "0.00000000", // Quote Order Quantity
"D": 1668680518494, // Trailing Time; This is only visible if the trailing stop order has been activated.
"j": 1, // Strategy ID; This is only visible if the strategyId parameter was provided upon order placement
"J": 1000000, // Strategy Type; This is only visible if the strategyType parameter was provided upon order placement
"W": 1499405658657, // Working Time; This is only visible if the order has been placed on the book.
"V": "NONE", // selfTradePreventionMode
"u":1, // TradeGroupId; This is only visible if the account is part of a trade group and the order expired due to STP trigger.
"U":37, // CounterOrderId; This is only visible if the order expired due to STP trigger.
"A":"3.000000", // Prevented Quantity; This is only visible if the order expired due to STP trigger.
"B":"3.000000" // Last Prevented Quantity; This is only visible if the order expired due to STP trigger.
},
"hook": "newAccountEvent",
}