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.

Sorry, your browser doesn't support embedded videos.

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('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)

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)

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

Event	Data	Description
APP_LOADED	{}	The Widget is ready (fully loaded and waiting for user actions).
SCREEN_LOADED	{ screen }	Screen successfully loaded. Screens: ACCEPT_TERMS_AND_POLICY, SELECT_PROVIDER, PROVIDE_CREDENTIALS, CONNECTION_SUCCESS, EXIT.
TERMS_AND_POLICY_ACCEPTED	{}	User has accepted Vezgo terms and policy.
ERROR	{ type }	Error occurred. Available error types: PAGE_NOT_FOUND, OAUTH_ERROR, CLIENT_ID_REQUIRED, INVALID_ORIGIN, TOKEN_REQUIRED, WRONG_CLIENT_ID, WRONG_REDIRECT_URI, INVALID_ACCOUNT_ID, RECONNECT_CONFLICT
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().
PROVIDER_SEARCH	{ query }	User has searched for a provider in the provider selection screen. query contains the search string which the user typed in.
PROVIDER_SELECTED	{ 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.
SUBMIT_ANSWER	{}	User has submitted their answer to security question.
START_OAUTH	{}	User started oAuth flow.
RETURNED_FROM_OAUTH	{}	User returned to Vezgo from third party oAuth service.
OPEN_METAMASK	{}	User opened MetaMask.
OPEN_WALLET_CONNECT	{}	User opened Wallet Connect.
OPEN_LEDGER	{}	User opened Ledger.

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.

Sorry, your browser doesn't support embedded videos.

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

info

The same Connect URL is loaded in the iframe when you connect via the drop-in Connect Widget using the JS SDK. The SDK just automatically encapsulates all handling logic in an easy-to-use interface to save you time.

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).
provider_categories	No	Show providers only from selected categories. Available options: exchanges,blockchains,wallets.
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.

info

The Redirect URI must be registered first before it can be used. You can register multiple Redirect URIs for your team (for your development, staging or production urls). Contact us if you need to register your Redirect URIs.

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).