Overview v1.0
Introduction
Welcome! Zabo provides an API to connect any cryptocurrency exchange, wallet, or account. Using Zabo API you can easily fetch information from crypto accounts, including:
- Balances
- Transaction histories
- USD equivalent values for balances and transaction histories
- Deposit addresses
To see a complete list of cryptocurrency exchanges, wallets, and accounts Zabo supports, check out our integrations page.
The fastest, easiest way to get started with Zabo (in less than 5 minutes) is through our Sandbox and Quickstart app, both of which can be accessed by signing up for Zabo API. You’ll integrate Zabo into your site or app and then use our Zabo SDK or REST endpoints to retrieve the data you need from our API.
If you have any questions about Zabo or feedback on these docs, you can contact us or find us here:
About Sandbox
Zabo provides two distinct environments through the API, a sandbox environment and a live environment. The sandbox environment produces the same exact objects and data structures as the live environment, however, the data itself is not meant to be precise. The sandbox server will not connect to real cryptocurrency exchange accounts, and it does not provide accurate exchange rate data. Market rates are close to the current market for all major currencies, however, you must use the live server to connect to real accounts and obtain accurate data. The live server should be used when your application is ready to connect to a live server and have proper security built around your API keys and any data your application intends to receive. You must also receive approval to connect with our live servers. Before then, the sandbox is available for development purposes. Keep this in mind when observing data obtained from the Zabo sandbox servers.
Quickstart For Standard Setup in 3 steps
Zabo distributes its API through standard REST endpoints, plus a JavaScript SDK that can be used both in a client and server environment. Let's begin by looking at how we initialize a connection.
Step 1 Import the Client SDK
There are several options to import the Client SDK. You can import using an html script tag
<!-- Using the latest version -->
<script src="https://cdn.zabo.com/latest/zabo.js"></script>
<!-- Using a specific version -->
<script src="https://cdn.zabo.com/0.12.0/zabo.js"></script>
or you can install it into a front-end framework, such as a Webpack or React project, via npm.
npm install --save zabo-sdk-js
then import it into your javascript file using require
var Zabo = require('zabo-sdk-js')
or ES6 import format
import Zabo from 'zabo-sdk-js'
// `Zabo` is now available
Step 2 Initialize Zabo
Zabo is initialized in the client with the following required information:
Zabo.init({
clientId: 'YourAppKeyFromYourZaboDashboard',
env: 'sandbox'
}).then(zabo => {
// `zabo` is ready to be used
})
where clientId
is found on the dashboard in your team settings. NOTE: Make sure you use the Client ID associated with the correct environment. Your Client ID for the sandbox is different than your Client ID for the live environment.
Step 3 Connect A User
You are ready to connect a user once Zabo has been initialized! To do this, provide a way to trigger the connect()
function, such as a button, and give a callback function to the onConnection()
handler.
// Here we add a listener to the first button in our html file
document.querySelector('button').addEventListener('click', () => {
// We call the .connect() window when it is clicked, and provide a callback to `onConnection`
zabo.connect().onConnection((account) => {
console.log(account)
}).onError(error => {
console.error('account connection error:', error)
})
})
That's it! You now have an account object and the rest of the API at your fingertips. Keep reading to see how you can create multiple connections for one user.
Multiple Wallets
To add multiple wallets to one user, we set up Zabo in your server. The SDK operates the same way on the server-side, but with different initialization credentials. You need to create an API key pair in the dashboard if you haven't done so already. To do this, visit 'Team Settings' on the dashboard, then click 'Developer Settings' and 'Generate New API Key'.
Copy the public and private keys into a private file in your project. NOTE: The secret key will not be available after you leave this view. You will need to generate a new key pair if the secret key is lost.
Now you should load those keys into your server and initialize the SDK. NOTE: We do provide REST endpoints and the server-side SDK is not required.
var Zabo = require('zabo-sdk-js');
Zabo.init({
apiKey: process.env.PUBLIC_API_KEY,
secretKey: process.env.SECRET_API_KEY,
env: 'sandbox'
}).then(async (zabo) => {
let myTeam = await zabo.getTeam()
console.log(myTeam)
})
We return to the point we left in the previous section. After the user connects an account in the front-end of your application, we move the account to your server in the onConnection
callback.
document.querySelector('button').addEventListener('click', () => {
zabo.connect().onConnection(account => {
// Send the account object to your server
PostDataToServer('/some-route', account)
}).onError(error => {
console.error('account connection error:', error)
})
})
This must be done in the onConnection
callback, or whichever method is used to capture the initial connection. You will not be able to call accounts.get()
later and use the object from that call to create a user.
You can use this account object in your server to create a user.
let user = await zabo.users.create(account);
// Store this user in your database for retrieval later
StoreUser(user)
To add another account to this user, simply provide a way for the user to connect another wallet in the front-end
document.querySelector('#same-or-another-button').addEventListener('click', () => {
zabo.connect().onConnection((account) => {
// Send the new account object to your server
PostDataToServer('/some-route', account)
}).onError(error => {
console.error('account connection error:', error)
})
})
Then you can add this account to the user you already created
let MyZaboUserObject = RetrieveUserFromDB()
let user = zabo.users.addAccount(MyZaboUserObject, account);
// Update this user in your database
UpdateUser(user)
That's it! Now you can retrieve the information needed for your application.
NOTE: Two accounts cannot be connected in the front-end together. Only the latest connection will be directly active in the client. Requests for an account that is not actively connected in the front-end, but is connected to a user, can be made through the server.
let MyZaboUserObject = RetrieveUserFromDB()
let balances = await zabo.users.getBalances({
userId: MyZaboUserObject.id,
accountId: MyZaboUserObject.account[0].id
});
let otherBalances = await zabo.users.getBalances({
userId: MyZaboUserObject.id,
accountId: MyZaboUserObject.account[1].id
});
We're excited to see what you build with all of the cryptocurrency at your fingertips! If you are ready for more advanced cryptocurrency features, read on.
Currency and Wallet Support
Zabo integrates a variety of wallets and currencies, each with its own set of capabilities and limitations. One of our primary goals for Zabo is to allow you to navigate these limitations programmatically, not manually. For instance, we have a provider endpoint available for you to get a full list of supported providers. There is a list of currency and wallet support levels on our website at https://zabo.com/integrations/. This listing can give you a high-level overview of support for each of these components. If you notice anything that is not clear, please reach out to us and let us know.
NOTE: We allow direct querying for blockchain addresses and Extended Public Keys from Highly Deterministic Wallets. See more details in our 'Ethereum API' section below.
Pagination
// considering a list of 15 txs
// ...
const firstPage = await zabo.transactions.getList({ limit: 10 })
console.log(firstPage.data) // [{ id: '0x... }, ... +9 items]
console.log(firstPage.data.length) // 10
console.log(firstPage.limit) // 10
console.log(firstPage.hasMore) // true
const secondPage = await firstPage.next()
console.log(secondPage.data) // [{ id: '0x... }, ... +4 items]
console.log(secondPage.data.length) // 5
console.log(secondPage.limit) // 10
console.log(secondPage.hasMore) // false
const thirdPage = await secondPage.next()
console.log(thirdPage.data) // []
console.log(thirdPage.data.length) // 0
console.log(thirdPage.limit) // 10
console.log(thirdPage.hasMore) // false
Example list_cursor object:
{
"limit": 25,
"has_more": false,
"self_uri": "/accounts/8b0a037f-67cb-44b7-ac2a-18e7a54561a8/transactions?limit=25&ticker=eth",
"next_uri": ""
}
Most endpoints that return a list provide cursor-based pagination. Cursor information is found inside of the list_cursor
object to facilitate subsequent requests. The SDK can handle pagination for you if using it as your tool. You can see examples of this to the right. If using the REST API directly, you can paginate through the results by using the id of the last resource in the list as a cursor parameter for the next call. The API provides a convenience value in list_cursor.next_uri
, which you can use to call for the next page of results. When has_more
is false, you have reached the end of the list. The default limit is 25, but values up to 50 are permitted. We provide all lists in descending order only (newest item first). For a transactions list, the order will be based on the initiated_at
value.
Query Parameters for REST API Requests
Parameter | Default | Required | Description |
---|---|---|---|
limit | 25 | Optional | Can be values 2-50 |
cursor | First resource available | Optional | ID of the resource to start from |
Navigating Docs
This documentation explains Zabo integration in your application. We recognize that many decentralized applications do not run a server, so we do not require an application server to interact with Zabo. With that said, we do have the ability to work with your server-authenticated users, which opens up two different ways you can connect with user wallets, depending on your application's setup. See Authentication for further information. You can view code examples in the dark area to the right as you read through the documentation.
Zabo API Intro
The Zabo API section defines the functions available for use in your application. These functions provide a way for your user to connect a wallet of their choice and provide the cryptocurrency data your application needs. After connecting, the client and server API functions can be accessed from your application's client or server, respectively. Both environments share similar functions, and they have unique functions of their own. If you are only using the API from your application client, the account connection lives for as long as the user's session token remains unexpired in the client. After that, the user needs to connect their account again. If you are running a server that authenticates your users and would like a persistent connection, then you can use the server-side API to assign users with established accounts.
Security
Application developers should note that Zabo provides a simple interface with networking in our back-end to facilitate a better overall cryptocurrency developer and user experience. At no point do we obtain user wallet private keys or any sensitive data required to act upon cryptocurrency holdings independently. All authentication and approvals remain in the user's hands.
Rate Limits
The Zabo API has a rate limit of 5 requests per second for session calls (where you're using an account session token), and this limit is shared across all session endpoints. It's IP-based, so every client would have their own rate limit. For HMAC endpoints that are called by your back-end, the limit is 20 requests per second, count against all HMAC endpoints together as one group, and apply to your team, not your IP.
Rate limits
Request type | Limit | Restriction type |
---|---|---|
Session endpoints (from client) | 5 / sec | IP-based |
HMAC endpoints (from server) | 20 / sec | team-based |
To help you keep track of your rate limit and adjust your calls dynamically (if you should need to), many of our endpoints will also respond with the following custom headers to help you keep track of your rate limit use:
Custom response headers with dynamic rate limit information
Header | Example | Description |
---|---|---|
X-Ratelimit-Limit | 5 | The current rate limit for this endpoint. |
X-Ratelimit-Remaining | 3 | The no. of remaining calls left for this rate limit period (usually 1 second). |
X-Ratelimit-Reset | 1614195468 | Unix time in seconds at which point your rate limit will be reset. |
Request IDs
{
"message": "Something went wrong on our end. Please note the request_id and get in touch.",
"request_id": "bf75165c-f0e8-4264-853b-7a0d3b2c2a94"
}
Every request that goes to our API is assigned a request_id
which is related to that request. This is true of both successful requests and errors, all of which should have a request_id
field at the bottom of the JSON response body.
When contacting customer support with any questions, make sure to include the request_id
you received. This will speed up our ability to help you!
Base URL
Sandbox
https://api.zabo.com/sandbox-v1
Live
https://api.zabo.com/v1
Authentication
The Zabo API requires your users to authorize a connection to the wallet they choose. Before getting to this point, you must register your application with us, develop using our sandbox environment, then activate your team or contact us to go live. Once the user has connected a wallet, your application can use the various Zabo functions to pull in data and provide it to your users. The user's approval happens when a user action triggers the connection widget, or you make the call for a connection using your specific URL (screenshot below) through tools such as mobile WebView. From there, Zabo takes the user through the process of selecting the wallet and currencies available. When the user returns from establishing a connection, the zabo.onConnection()
callback, WebSocket, or WebHook provides the relevant wallet data. See the callback documentation and Connecting a User for further details.
Front-end only apps
If you're running a front-end only application, users receive a session token that initializes the Zabo SDK for JS in the client, and you do not need to take any further action for authentication. Session tokens do have a limited time-to-live depending on user activity and, once it expires, your user needs to connect again. If you are sending REST calls, you authenticate with a Bearer
token and all calls must be made from https
origins. The requests must have the following header:
- Authorization: Bearer zabosession-tokenRecievedThroughOnConnectionCallback
The Zabo SDK for JS handles this authentication for you automatically.
App Server Authentication
Zabo uses API Key authentication for the Zabo Server API. This communication link provides programmatic access to administrative functions and provides a unified experience for your authenticated users and Zabo. You must establish API keys through your Zabo administrative dashboard after registering your application. You can create API Keys in the dashboard and use them to sign and send requests from your server. These requests must be signed and have the following headers:
- X-Zabo-Key: API Key established in the dash
- X-Zabo-Sig: Signature of request using a paired secret key (See signing requests)
- X-Zabo-Timestamp: Timestamp of the request
The Zabo NPM package will do this under the hood for you once initialized. Once a user is established in the system, with an account linked, the application server can send future authenticated requests for data.
Signing Requests
If you are using the REST endpoints directly, the signature generated for the X-Zabo-Sig
header is formed by using the paired secret key to create a SHA-256 HMAC on the following concatenated string using hex encoding:
Timestamp
+ Full Request URL
+ Request Body
where:
- Timestamp is the current time in milliseconds since Unix Epoch. The request must be made within 30 seconds of the timestamp given. Example:
1420069800000
- Full Request URL is the url used for the request. Example:
https://api.zabo.com/v1/currencies
- Request Body is the body of the request as a string, encoded using UTF-8. The whitespace in the string must be the exact same as the whitespace in the request string, for example:
'{"name": "New Name}'
. If there are no request arguments or it is aGET
request, then simply useTimestamp
+Full Request URL
.
Errors and Disconnects
zabo.getAccount()
.then(function (account) {
/* See getAccount() section below */
})
.catch(function (error) {
console.log(error)
/* The error object below */
})
error
is the following JSON object:
{
"error_type": 400,
"message": "Connection closed by the user."
}
Or it could be:
{
"message": "Something went wrong on our end. Please note the request_id and get in touch.",
"request_id": "bf75165c-f0e8-4264-853b-7a0d3b2c2a94"
}
Zabo uses promises to return most responses. When implementing the catch
function, the SDK provides an error object with the following error types:
Error Type | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. Usually from a missing or incorrect parameter, or an unsupported function by the connected wallet provider* |
401 | Unauthorized -- Proper credentials were not received. |
402 | Request Failed -- A valid request was made but it failed. |
403 | Forbidden -- You do not have access rights to the requested resource. |
404 | Not Found -- The resource does not exist. |
429 | Too Many Requests -- Too many calls happened in a short period of time. |
500 | Internal Server Error -- This our error and you should note the time and let us know if you receive this.* |
* A user-friendly message should be included with these errors.
Disconnected Accounts
Sometimes Zabo will lose the connection to an account after making a successful connection. While we strive to maintain an active connection for as long as you need it, these disconnects happen for reasons outside of our control. These happen for reasons such as the user has revoked the access credentials directly in their account, the account provider has caused the credentials to expire, or the account provider simply does not support persistent connections. We are working to provide more useful responses when this happens, however, in Zabo API's current state, an account request for balances or transactions will return an error response if the account has disconnected. You should expect to handle the following errors:
- 401 - This usually returns if the access credentials have been revoked by the user directly.
- 403 - This returns if the provider has revoked access rights.
- 404 - This returns if Zabo has already detected a disconnect and the account connection has been removed.
Our next update to this process will seek to remove the error workflow completely, and provide some account data along with connection information.
Unsupported Functions
{
"error_type": 400,
"message": "Not supported for this wallet provider."
}
Due to limitations with certain wallet providers, some functions will not work if the user connected to a wallet provider that does not support those functions. Your application should plan to handle these errors gracefully. Each function will list the current wallet provider support level. If a function is called, and the connected wallet provider does not support it, your application can expect to receive the error object to the right.
Connecting a user
Initialize the Zabo client SDK:
Zabo.init({
clientId: 'YourAppKeyFromYourZaboDashboard',
env: 'sandbox'
}).then(zabo => {
// zabo ready
}).catch(err => {
console.error(err)
})
This process should begin when the user indicates they would like to establish a new wallet connection, such as after pressing a button. You can establish a connection with or without the SDK and keep the account in the client, or you can send this account object to your server and establish a server-side connection with Zabo. This server process allows you to link the account to a user. See adding users for further information.
Connection Request via JS SDK
Open connect widget in a new window:
zabo.connect()
.onConnection(function(account) {
console.log(account)
/* The account object outlined below */
})
.onError(function(error) {
console.log(error)
/* See errors section for more information */
})
// Or go directly to a specific provider
zabo.connect({ provider: 'binance' })
.onConnection(function(account) {
console.log(account)
/* The account object outlined below */
})
.onError(function(error) {
console.log(error)
/* See errors section for more information */
})
account
is the following JSON object:
{
"id": "663925bd-205d-479e-895f-27ec3891e8b3",
"token": "zabosession-abcdef1234567890",
"exp_time": "Mon, 10 Jun 2019 02:45:50 UTC",
"provider": {
"name": "coinbase",
"display_name": "Coinbase",
"logo": "https://cdn.zabo.com/assets/providers/coinbase.png",
"type": "oauth",
"scopes": ["read_balances", "read_transactions", "send_crypto", "receive_crypto"]
},
"balances": [
{
"ticker": "ETH",
"provider_ticker": "ETH",
"name": "Ether",
"asset_is_verified": true,
"asset_type": "account",
"amount": "5.068",
"decimals": 18,
"fiat_ticker": "USD",
"fiat_value": "1032.01",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/ETH.png",
"updated_at": 1560134750000,
"misc": [],
"resource_type": "balance"
},
{
"ticker": "BTC",
"provider_ticker": "XBT",
"name": "Bitcoin",
"asset_is_verified": true,
"asset_type": "account",
"amount": "0.932",
"decimals": 8,
"fiat_ticker": "USD",
"fiat_value": "7892.091",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"updated_at": 1560134750000,
"misc": [],
"resource_type": "balance"
}
],
"blockchain": null,
"created_at": 1560134750000,
"updated_at": 1560134750000,
"resource_type": "account",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
zabo.connect()
The Zabo object becomes available to you after including the Zabo Client SDK in your project. Calling the connect
function without any arguments starts the user connection process in its default state. The drop-in component Zabo Connect Widget opens for the user to select which one of the wallet provider options they wish to connect with your application.
The connect
function does not return a promise; it uses callbacks to provide a connection response. This function returns the Zabo
object, which can be used to chain callback functions as shown in the example to the right. The callbacks that may be triggered are outlined below, and you can provide a function for each callback. Applications running a server can use the onConnection
data to establish account authorization for the connected user.
Additional Connection Methods
That's not all! Utilizing the Zabo JS SDK provides the most convenient method for connecting a user. Sometimes this is not possible, or you may need to utilize more customized features. Take some time to review the additional connection capabilities to learn more:
- Mobile Webview Connections
See 'Customizable Connect URL' section. - Preselecting a Wallet
See 'Preselected Provider Connections' section. - Querying Blockchains Directly
See 'Blockchain Addresses and HD Wallets' section.
Zabo connect callbacks
onConnection()
onError()
onEvent()
onConnection
zabo.onConnection(function (account) {
console.log(account)
})
If using Zabo Server API:
This callback is called when the user has successfully authenticated and enabled their account for use by your application. The account object returned contains the same data available via getAccount() with the exception that it includes the token
and exp_time
fields. If you intend to use Zabo from your server, you should forward this object to your server and use it to create or update a user. This must be done in the onConnection
callback because the token will only be made available this one time in the onConnection
event. If you are not using the Zabo API from your server, no further action is needed to continue using the Zabo Client SDK.
onError
zabo.onError(function (error) {
console.error(error)
})
This callback is called when an error is triggered such as when the user does not provide access to their wallet for use by your application via Zabo. See the errors section for more information about the error object returned.
onEvent
zabo.onEvent(function (eventName, metadata) {
console.log(eventName, metadata)
})
This callback is called at certain points in the connection process. The function takes two arguments, the event name, and the metadata object. The supported events and metadata fields are described below.
Supported events:
Event | Description |
---|---|
CLOSE | The Zabo Connect Widget is closed, either by a user action or by a response (success or failure). |
CONNECTED | The user has completed the connection process. |
CONNECTOR_STATUS | Indicates the status of the provider connector. Such as if the provider is supported by the user device. |
ERROR | An error occurred during the connection process. See the errors section for more information. |
LOAD_CONNECTOR | The provider connector has been loaded. |
OPEN | The Zabo Connect Widget is ready and the user should be able to start the connection process. |
SEARCH | The user has searched for a provider on the provider selector page. |
SELECT_PROVIDER | The user has selected a provider. |
START_CONNECTION | The user has started a connection with the selected provider. |
SUBMIT_CREDENTIALS | The user has submitted credentials to complete the connection process. |
UPDATE_VIEW | The use has moved to the next page. |
Metadata fields:
Field | Description |
---|---|
current_path | The pathname of the current page. Emitted by: all events. |
current_view | The name of the current view/page. Emitted by: all events. |
error_type | The error code encountered. Emitted by: ERROR, EXIT. |
is_supported | The boolean indicating whether the provider is supported or not. Emitted by: CONNECTOR_STATUS. |
message | The message describing the situation. Emitted by: ERROR, EXIT, CONNECTOR_STATUS. |
provider_name | The name of the selected provider. Emitted by: all events (once the provider is selected). |
request_id | The request ID for the last request. Emitted by: ERROR, EXIT, CONNECTED. |
search | The term used to search for providers. Emitted by: SEARCH. |
timestamp | The timestamp (milliseconds) representing the moment the event occurred. Emitted by: all events. |
NOTE: The metadata fields may or may not be present depending on the event triggered. Make sure your application can handle this.
Customizable Embedding
Customize via CSS Selector:
iframe[name=zabo-connect-widget] {
background-color: red;
}
Customize via Inline Frame element:
<iframe name="zabo-connect-widget" id="myIframeId" class="myIframeClass" frameborder="0"></iframe>
The Zabo Connect Widget is embedded into your HTML page via Inline Frame element <iframe>
, allowing your app to:
- Hold the window focus (i.e., no UI re-directs)
- Have a more customizable integration
- Work even on single tab browsers
When you call the connect
function, the Zabo SDK will automatically inject the iframe element into the HTML body. The iframe element will necessarily have the attribute name=zabo-connect-widget
and, therefore, you should be able to customize it by using the CSS selector iframe[name=zabo-connect-widget]
.
Besides that, if the element hierarchy body > iframe
is not suitable for your application, you can implement your iframe element (making sure you set the attribute name=zabo-connect-widget
), and the Zabo SDK will use this element instead of injecting a new one. The SDK will manage to load and unload the content and show and hide (via the CSS display
property) the iframe element, regardless of how you embedded the iframe in the page.
Customizable Connect URL
Open the Zabo Connect Widget:
See 'Connection Request via JS SDK' above
We provide a connection URL in your Zabo Dashboard (see screenshot below) which can be used to open the Connect Widget within your own application. The URL format looks like this: https://connect.zabo.com/connect?client_id=clientIDFromYourDashboard&origin=localhost&zabo_env=sandbox&zabo_version=latest
. Simply call this URL, and the connection process will complete via query parameters, WebSocket, or WebHook methods outlined in the sections below. NOTE: Once you are finished with the widget, your application is responsible for closing the window.
Parameters
Parameter | Required | Description |
---|---|---|
client_id | Required | Key acquired when registering a team in Zabo Dashboard. |
origin | Required | The URL host where the connection originates from. |
zabo_env | Required | The Zabo API environment of your team. Could be either sandbox or live . |
zabo_version | Required | The version of the Zabo API your app is using. Could be either a version identifier (v0.0.0) or latest . |
redirect_uri | Optional | URL where users will be redirected after the account connection. If omitted, the connect widget will either close, or remain open if needed. |
otp | Optional | The One Time Password required to establish a WebSocket connection. |
navbar | Optional | When set to false , hides the top navigation bar. Defaults to true. |
Additional parameters and metadata for your server can be forwarded when utilizing WebHooks. See 'New Account Connections' in the WebHooks section below for more information.
Receiving via WebHooks
Webhooks are covered in their own section below.
Receiving via WebSockets
See 'Connection Request via JS SDK' above
Returns the following JSON object:
{
"id": "663925bd-205d-479e-895f-27ec3891e8b3",
"name": "Application Name",
"session": {
"one_time_password": "randomOneTimeUsePassword",
"expires_at": "Mon, 3 Aug 2020 15:04:05 GMT"
}
}
Successful connection received via WebSocket:
{
"zabo": true,
"eventName": "connectSuccess",
"account": {
"id": "663925bd-205d-479e-895f-27ec3891e8b3",
"token": "zabosession-abcdef1234567890",
"exp_time": "Mon, 10 Jun 2019 02:45:50 UTC",
"provider": {
"name": "coinbase",
"display_name": "Coinbase",
"logo": "https://cdn.zabo.com/assets/providers/coinbase.png",
"type": "oauth",
"scopes": ["read_balances", "read_transactions", "send_crypto", "receive_crypto"]
},
"balances": [
{
"ticker": "ETH",
"provider_ticker": "ETH",
"name": "Ether",
"asset_is_verified": true,
"asset_type": "account",
"amount": "5.068",
"decimals": 18,
"fiat_ticker": "USD",
"fiat_value": "1032.01",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/ETH.png",
"updated_at": 1560134750000,
"misc": [],
"resource_type": "balance"
},
{
"ticker": "BTC",
"provider_ticker": "XBT",
"name": "Bitcoin",
"asset_is_verified": true,
"asset_type": "account",
"amount": "0.932",
"decimals": 8,
"fiat_ticker": "USD",
"fiat_value": "7892.091",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"updated_at": 1560134750000,
"misc": [],
"resource_type": "balance"
}
],
"blockchain": null,
"created_at": 1560134750000,
"updated_at": 1560134750000,
"resource_type": "account",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
}
Failed connection received via WebSocket:
{
"zabo": true,
"eventName": "connectError",
"error": {
"error_type": 400,
"message": "Connection closed by the user."
}
}
Zabo provides the capability to capture new account connections via WebSocket. Websockets are implemented automatically if using the JavaScript SDK. The data specific to your application is in the Zabo Developer Dashboard. To get there, sign in and navigate to Team Settings -> Developer Settings, then click on the WebSocket tab seen below:
The WebSocket must be established before calling the Zabo Connect Widget URL. Follow the steps below:
- Obtain a One Time Password by calling the "Team Info" URL first:
https://api.zabo.com/sandbox-v1/teams/info?client_id=clientIDFromYourDashboard
. A single query parameter namedclient_id
should be populated with the client id found in your Zabo Dashboard. Use thesession.one_time_password
received in the response to establish the websocket in the next call. - Open the WebSocket from your application by calling
wss://api.zabo.com/sandbox-v1/ws?otp=theOneTimePasswordReceivedInStep1&client_id=clientIDFromYourDashboard
. Two query parameters,client_id
andotp
, should be provided. Theclient_id
value is the same as the previous value, and theotp
value is thesession.one_time_password
received in the previous response. From here, you will have an open websocket to the Zabo API Server. - Finally, call the Zabo Connect Widget URL when the user is ready to complete the connection process. See the example WebSocket responses to the right. NOTE: There is a slight difference in the WebSocket response than other responses.
Receiving via Query Params
Zabo can also pass successful account connections in the Zabo Connect Widget window directly via query parameters. Whenever the Zabo Connect Widget is opened using the direct URL, connection responses will be populated in the window's URL. This could be useful for mobile WebViews prior to closing the window. Examples of the following URL are also available in your Zabo Developer Dashboard. To view the examples in your dashboard, navigate to Team Settings -> Developer Settings, then click on the HTTP redirects tab seen below:
A successful connection in the Zabo Connect Widget window will open the following URL: https://connect.zabo.com/connected?account={%22id%22:%22322ab8ea-d35c-44d5-805a-ad286f408025%22,%22token%22:%22zabosession-dLkRWGnsjavyXzKBYedkyJlgDIouBjPBFVTvm45S4OZ7hGO7xDzOc4a2p1bAm5wf%22,%22exp_time%22:%22Fri,%2017%20Jul%202020%2020:53:54%20GMT%22,%22request_id%22:%2239f4eccf-629b-486e-a4b5-a6e0595a5dbf%22}
. Where the account
parameter is a stringified, URL-safe, abbreviated Zabo Account object with the data you need to get an account using the zabosession-xyz
token provided as authentication. A user can also be created with this information by simply calling the appropriate url with this account object in the body of the request.
An unsuccessful connection will open the following URL: https://connect.zabo.com/exit?error_type=400&message=Connection%20closed%20by%20the%20user&request_id=b4ab2eaa-5003-48ea-8b07-23c90eff02ca
. Where the request id can be used to ask the Zabo team for help if the error may be with our system.
These are the exact same responses your app will receive if you choose to use the redirect_uri
parameter when calling the Zabo Connect Widget. The user will be redirected to the URL provided (plus the appropriate response) as soon as they receive the visual feedback of a successful or unsuccessful connection.
Preselected Provider Connections
Preselect Provider via SDK:
zabo.connect({ provider: 'coinbase' })
Preselect Provider via Connect URL:
"https://connect.zabo.com/connect/coinbase"
zabo.connect({ provider })
If your application already allows users to select an account provider, and you wish to simply have users go directly to a provider's connection screen, then you can submit the desired provider directly in the connect
call. This will bypass our connect widget's selection screen and take users directly to the requested provider. You can use our providers
endpoint to get a complete list of options available. Simply use the name
from one of the providers as the provider
value to the connect
function.
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
provider | string | Optional | name of the account provider such as coinbase or metamask . A complete list of available options can be obtained from the providers endpoint and using the name field from the desired provider object. |
NOTE: This feature is also available through Connection Request via URL. You can bypass the provider's selector by passing the name
of the desired provider as part of the connect URL path, such as the following: https://connect.zabo.com/connect/theDesiredProviderName
.
Account disconnections
A user's account may become disconnected if their session token or API keys with the account/wallet provider expire, are revoked, or, as is the case with providers that have OAuth tokens, if the provider's servers go down for an extended period of time during which we are unable to refresh these tokens.
A disconnected account may manifest as a 401 error if the user tries to retrieve some data from the provider, such as their latest balances, transaction history, etc.
If the account became disconnected during a background Zabo transaction refresh process (which keeps transactions updated for all accounts), it will be deleted, at which point a 404 error would be returned when trying to fetch data for this account.
If you add the account to a server-side user object, you can see if an account is disconnected in the background because it will disappear from that user's list of accounts.
Zabo API
Zabo SDK for JS client script:
<script src="https://cdn.zabo.com/0.9.0/zabo.js"></script>
<script type="text/javascript">
Zabo.init({
clientId: "<Your App's Key>",
env: "sandbox"
}).then(zabo => {
/* zabo.data is a limited team object for the provided clientId */
console.log(zabo.data)
}).catch(err => {
console.error(err)
})
</script>
You can also use the 'latest' script:
<script src="https://cdn.zabo.com/latest/zabo.js"></script>
> Or pull the `zabo-sdk-js` NPM package into your framework
This section documents the Zabo API for application developers. This API is available as standard REST endpoints, a script you can add directly into your html file, and as a package you can pull into your project.
Initializing the JS SDKs
// Initialize the Zabo client SDK for JS:
Zabo.init({
clientId: 'YourAppKeyFromYourZaboDashboard',
env: 'sandbox'
}).then(zabo => {
// do stuff with zabo
}).catch(err => {
console.error(err)
})
// ES6 async/await
try {
let zabo = await Zabo.init({
clientId: 'YourAppKeyFromYourZaboDashboard',
env: 'sandbox'
})
// proceed with zabo
} catch (error) {
console.log(error)
/* See errors section for more information */
}
When using one of the JS SDKs, they must be properly initialized using credentials you received when you registered in the Zabo dashboard. You have a few configuration options that can be changed to best suit your needs. Please note that some options are available only when running the SDK from the browser while others are available when running the SDK on your node.js code.
Initialization Arguments
Parameter | Description | Required | Platform |
---|---|---|---|
clientId | Key acquired when registering a team in Zabo Dashboard. | Required | Browser |
env | Zabo API environment the SDK is connecting with. Could be either sandbox or live . Only sandbox is available unless a live connection is approved. | Required | Both |
apiKey | API Key generated via the Developer Settings section at Zabo Dashboard. | Required | Node |
secretKey | Secret Key generated via the Developer Settings section at Zabo Dashboard. | Required | Node |
autoConnect | Optional boolean useful if you wish to stop the SDK from fetching the team data during Zabo.init(). Defaults to true . | Optional | Both |
apiVersion | Optional parameter to specify the Zabo API version. Could be either v0 or v1 . Defaults to v1 . | Optional | Both |
Usage
Most applications use Zabo in their application client to initiate a wallet connection. To do this, add the script to the bottom of your <body>
tag and before using any of the functions, or alternatively pull the zabo-sdk-js NPM package into your front-end framework. The first step is to call the connect
function outlined above and establish a connection with the user's wallet. Your application can then continue to use the functions available here on the client-side or, if running a server, use the server API for more functionality. Most functions in the client SDK for JS, except for the connect
function, return promises which allow you to use async/await or chain then
and catch
blocks to obtain responses.
Developer Setup Note
If you are developing directly in an .html file, you still must serve this file from a localhost
server due to origin requirements. For Mac or Linux (with Python installed) you can open the terminal, go into the file's directory, and run python -m SimpleHTTPServer 8000
. This will serve the file at localhost:8000
. For Windows, you can use an IDE extension such as Live Server for Visual Studio.
If you are using a front-end framework, such as Reactjs, these tools will provide a server for your development process. Additionally, if you are delivering your application from a remote server and not using localhost
during development, you must serve files using 'HTTPS'. HTTPS is not necessary when using localhost
.
Get an account
Get the current account information:
zabo.accounts.getAccount()
.then(function (account) {
console.log(account)
/* account is the json object outlined below */
})
.catch(function (error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let account = await zabo.getAccount()
/* account is the json object outlined below */
} catch (error) {
console.log(error)
/* See errors section for more information */
}
Returns the
account
JSON:
{
"id": "663925bd-205d-479e-895f-27ec3891e8b3",
"provider": {
"name": "coinbase",
"display_name": "Coinbase",
"logo": "https://cdn.zabo.com/assets/providers/coinbase.png",
"auth_type": "oauth",
"scopes": ["read_balances", "read_transactions", "get_deposit_addresses", "create_deposit_address"],
"resource_type": "provider"
},
"balances": [
{
"ticker": "ETH",
"provider_ticker": "ETH",
"name": "Ether",
"asset_is_verified": true,
"asset_type": "account",
"amount": "5.068",
"decimals": 18,
"fiat_ticker": "USD",
"fiat_value": "12032.01",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/ETH.png",
"updated_at": 1560134750000,
"misc": [],
"resource_type": "balance"
},
{
"ticker": "BTC",
"provider_ticker": "XBT",
"name": "Bitcoin",
"asset_is_verified": true,
"asset_type": "account",
"amount": "0.932",
"decimals": 8,
"fiat_ticker": "USD",
"fiat_value": "58092.091",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"updated_at": 1560134750000,
"misc": [],
"resource_type": "balance"
}
],
"blockchain": null,
"created_at": 1560134750000,
"updated_at": 1560134750000,
"resource_type": "account",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This function returns the current account connected. The account object contains information such as the provider used during connection with your app. This function should only be called from your application's client. To get account information from your application server, utilize zabo.users.getOne
documented below for one of your users.
Full Object Description
Client SDK for JS
zabo.accounts.getAccount()
Server SDK for JS
Not available
HTTP Request
GET BASE_URL/accounts/:account_id
GET BASE_URL/sessions
Provider Support
All
Get a specific balance
zabo.accounts.getBalances({tickers: ['ETH', 'BTC']})
.then(function (balances) {
console.log(balances.data)
/* balances is the json object outlined below */
})
.catch(function (error) {
console.log(error)
/* User has not yet connected or doesn't have these currencies */
})
// ES6 async/await
try {
let balances = await Zabo.accounts.getBalances()
// `balances` will be all available balances
console.log(balances.data)
} catch (error) {
console.log(error)
}
Returns the following JSON:
{
"data": [
{
"ticker": "ETH",
"provider_ticker": "ETH",
"name": "Ether",
"asset_is_verified": true,
"asset_type": "account",
"amount": "5.068",
"decimals": 18,
"fiat_ticker": "USD",
"fiat_value": "12032.01",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/ETH.png",
"updated_at": 1560134750000,
"misc": [],
"resource_type": "balance"
},
{
"ticker": "BTC",
"provider_ticker": "XBT",
"name": "Bitcoin",
"asset_is_verified": true,
"asset_type": "account",
"amount": "0.932",
"decimals": 8,
"fiat_ticker": "USD",
"fiat_value": "58092.091",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"updated_at": 1560134750000,
"misc": [],
"resource_type": "balance"
}
],
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
Returns the user balances for the requested currencies. When requesting balances from the client, the request should be made in the context of the connected account. When requesting from an application server, requests should be made in the context of a user. See the documentation about users below. Cryptocurrencies available to your app can be queried using the currencies function documented below. If no currencies are specified, then all available currencies will be returned.
Full Object Description
Client SDK for JS
zabo.accounts.getBalances({ tickers })
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
tickers | array | Optional | Array of 3-letter (or more) short string identifiers for each currency/asset balance requested. |
Server SDK for JS
zabo.users.getBalances({ userId, accountId, tickers })
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
userId | string | Required | String UUID of the user established with Zabo. |
accountId | string | Required | String UUID of an account that belongs to the user. |
tickers | array | Optional | Array of 3-letter (or more) short string identifiers for each currency/asset balance requested. |
HTTP Request
From Client: GET BASE_URL/accounts/:account_id/balances
From Server: GET BASE_URL/users/:user_id/accounts/:account_id/balances
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
tickers | string | Optional | Comma separated list of 3-letter (or more) short string identifiers for each currency/asset requested. |
Provider Support
All
Get transaction history
Get a list of blockchain transactions sent or received by this account
Zabo.transactions.getList({
ticker: 'ETH',
limit: 25
}).then(function(history) {
console.log(history.data)
/*
`history` is the json object outlined below. NOTE: list_cursor is
not exposed in the JS SDK. Simply call `next()` on the response
to paginate
*/
history.next().then(moreHistory => {
console.log(moreHistory.data)
})
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let history = await zabo.transactions.getList({
limit: 25
})
// All transactions in the account will be returned if a ticker parameter is not defined.
console.log(history.data)
history = await history.next()
/* history is the json object outlined below */
} catch (error) {
console.log(error)
}
The SDK returns the following JSON:
{
"data": [
{
"id": "0x343d19bf733aa10fca5e066f6318921f3f6ad081f568f256af7478cc75b1f391",
"status": "completed",
"transaction_type": "withdrawal",
"parts": [
{
"direction": "sent",
"ticker": "ETH",
"provider_ticker": "ETH",
"provider_ticker": "ETH",
"amount": ".019",
"asset_is_verified": true,
"fiat_ticker": "USD",
"fiat_value": "41.28",
"fiat_asset_is_verified": false,
"other_parties": [
"0x621e2F127b9a730911aE5929185EeFDfa7a657FE"
]
}
],
"fees": [
{
"type": "network",
"ticker": "ETH",
"provider_ticker": "ETH",
"amount": ".001305162",
"asset_is_verified": true,
"fiat_ticker": "USD",
"fiat_value": "2.62",
"fiat_asset_is_verified": false,
"resource_type": "transaction_fee"
}
],
"misc": [],
"fiat_calculated_at": 1606311952000,
"initiated_at": 1606311952000,
"confirmed_at": 1606311952000,
"resource_type": "transaction"
},
{
"id": "0x..."
}
],
"delay": 175,
"last_updated_at": 1560134750000,
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
The REST endpoint returns the following JSON including
list_cursor
:
{
"list_cursor": {
"limit": 25,
"has_more": false,
"self_uri": "/accounts/8b0a037f-67cb-44b7-ac2a-18e7a54561a8/transactions?limit=25&ticker=eth",
"next_uri": ""
},
"data": [
{
"id": "0x343d19bf733aa10fca5e066f6318921f3f6ad081f568f256af7478cc75b1f391",
"status": "completed",
"transaction_type": "withdrawal",
"parts": [
{
"direction": "sent",
"ticker": "ETH",
"provider_ticker": "ETH",
"amount": ".019",
"asset_is_verified": true,
"fiat_ticker": "USD",
"fiat_value": "41.28",
"fiat_asset_is_verified": false,
"other_parties": [
"0x621e2F127b9a730911aE5929185EeFDfa7a657FE"
]
}
],
"fees": [
{
"type": "network",
"ticker": "ETH",
"provider_ticker": "ETH",
"amount": ".001305162",
"asset_is_verified": true,
"fiat_ticker": "USD",
"fiat_value": "2.62",
"fiat_asset_is_verified": false,
"resource_type": "transaction_fee"
}
],
"misc": [],
"fiat_calculated_at": 1606311952000,
"initiated_at": 1606311952000,
"confirmed_at": 1606311952000,
"resource_type": "transaction"
},
{
"id": "0x..."
}
],
"delay": 175,
"last_updated_at": 1560134750000,
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
The first call for an account looks like:
{
"list_cursor": {
"limit": 25,
"has_more": false,
"self_uri": "/accounts/8b0a037f-67cb-44b7-ac2a-18e7a54561a8/transactions?limit=25&ticker=eth",
"next_uri": ""
},
"data": [],
"delay": 175,
"last_updated_at": 0,
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
NOTE: Please read carefully because this call acts differently from most calls. This function returns a transaction history list for the current account. Many accounts have large transaction histories and require a lengthy period of time to retrieve a full dataset. This means that most accounts will not return any transactions on the first call, but will return an empty array with a delay
value and last_updated_at
will be 0
. The delay is an estimated number of seconds before the transaction history will be available, or, if there are transactions, the number of seconds it will take for the transaction history to update. The estimate is our best guess based on known factors, however the time could take much longer if the account has more transactions than anticipated. Make sure you are considering this delay before calling the transaction history again both via SDK or HTTP request. When making subsequent calls, the last_updated_at
field will let you know if the full history has been retrieved. You may start seeing transactions in the list, however, if last_updated_at
is still 0
, then we are still retrieving the history. When last_updated_at
updates to a particularly useful timestamp, that will be the latest time at which a full history was accounted for. All transactions will be included if no currency is specified.
Additional NOTE: We are working on a fully-featured WebSocket implementation of this call for our next release which will provide a much-improved experience.
Full Object Description
Client SDK for JS
zabo.transactions.getList({ ticker, limit, cursor })
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
ticker | string | Optional | 3-letter (or more) short string identifier for the currency requested. |
Server SDK for JS
zabo.transactions.getList({ userId, accountId, ticker, limit, cursor })
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
userId | string | Required | String UUID of the user established with Zabo. |
accountId | string | Required | String UUID of an account that belongs to the user. |
ticker | string | Optional | 3-letter (or more) short string identifier for the currency requested. |
HTTP Request
From Client: GET BASE_URL/accounts/:account_id/transactions
From Server: GET BASE_URL/users/:user_id/accounts/:account_id/transactions
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ticker | string | Optional | 3-letter (or more) short string identifier for the currency requested. |
Provider Support
Please check out our integrations page for a list of providers that support transaction history.
Get a specific transaction
zabo.transactions.getOne({
txId: '0x158be2ad4ba161c1a67e9b5646d2ed35bd4940b708103635dfd84f5ef252c18a'
}).then(function(tx) {
console.log(tx)
/* tx is the transaction object outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let tx = await zabo.transactions.getOne({
txId: '0x158be2ad4ba161c1a67e9b5646d2ed35bd4940b708103635dfd84f5ef252c18a'
})
} catch (error) {
console.log(error)
}
Returns a single transaction JSON object:
{
"id": "0x343d19bf733aa10fca5e066f6318921f3f6ad081f568f256af7478cc75b1f391",
"status": "completed",
"transaction_type": "withdrawal",
"parts": [
{
"direction": "sent",
"ticker": "ETH",
"provider_ticker": "ETH",
"amount": ".019",
"asset_is_verified": true,
"fiat_ticker": "USD",
"fiat_value": "41.28",
"fiat_asset_is_verified": false,
"other_parties": [
"0x621e2F127b9a730911aE5929185EeFDfa7a657FE"
]
}
],
"fees": [
{
"type": "network",
"ticker": "ETH",
"provider_ticker": "ETH",
"amount": ".001305162",
"asset_is_verified": true,
"fiat_ticker": "USD",
"fiat_value": "2.62",
"fiat_asset_is_verified": false,
"resource_type": "transaction_fee"
}
],
"misc": [],
"fiat_calculated_at": 1606311952000,
"initiated_at": 1606311952000,
"confirmed_at": 1606311952000,
"resource_type": "transaction"
}
This function returns a specific transaction for the given account. The account transactions must have been retrieved from the Get transaction history call before querying for a specific transaction. If using the REST API or server SDK, and the transaction did not originate from the account, or if the account is not the recipient, an error will be returned. The client SDK handles this information for you.
Full Object Description
Client SDK for JS
zabo.transactions.getOne({ txId })
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
txId | string | Required | Transaction ID of the transaction being requested. |
Server SDK for JS
zabo.transactions.getOne({ userId, accountId, txId })
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
userId | string | Required | String UUID of the user established with Zabo. |
accountId | string | Required | String UUID of an account that belongs to the user. |
txId | string | Required | Transaction ID of the transaction being requested. |
HTTP Request
From Client: GET BASE_URL/accounts/:account_id/transactions/:tx_id
From Server: GET BASE_URL/users/:user_id/accounts/:account_id/transactions/:tx_id
Create a user
Create user:
Not available from application clients, only servers
Returns Response (201) and the following JSON:
{
"id": "17c0f27e-9916-4ace-b8ca-18d1be2cff43",
"accounts": [
{
"id": "8b0a037f-67cb-44b7-ac2a-18e7a54561a8",
"blockchain": "ethereum",
"provider": {
"name": "metamask",
"display_name": "MetaMask",
"logo": "https://cdn.zabo.com/assets/providers/metamask.png",
"type": "private_key",
"scopes": ["read_balances", "read_transactions", "get_deposit_addresses", "create_deposit_address"],
"resource_type": "provider"
},
"last_connected": 1420069800000
}
],
"created_at": 1420069800000,
"updated_at": 1420069800000,
"resource_type": "user",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This function creates a new user for your application. A user connects their cryptocurrency wallet via the Zabo Client API, and then you can create a user from your server. From there, your application server can access this user's account data.
Full Object Description
Client SDK for JS
Not Available
Server SDK for JS
zabo.users.create(account)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
account | object | Required | The account object received when the user connected. This object must contain a valid token. |
HTTP Request
POST BASE_URL/users
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
account | object | Required | The account object received from the Zabo Client after a user has connected an account, in the onConnection event. The token field must be present and associated with an active account. |
Provider Support
Not applicable
Get users
Get your users:
Not available from application clients, only servers
The SDK returns the
user
list:
{
"total": 1,
"data": [
{
"id": "17c0f27e-9916-4ace-b8ca-18d1be2cff43",
"accounts": [
{
"id": "8b0a037f-67cb-44b7-ac2a-18e7a54561a8",
"blockchain": "ethereum",
"provider_name": "metamask",
"provider_display_name": "MetaMask",
"last_connected": 1420069800000,
"created_at": 1420069800000
}
]
},
{
"id": "2a..."
}
],
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
The REST API returns the following JSON object:
{
"list_cursor": {
"limit": 25,
"has_more": false,
"self_uri": "/users?limit=25",
"next_uri": ""
},
"total": 1,
"data": [
{
"id": "17c0f27e-9916-4ace-b8ca-18d1be2cff43",
"accounts": [
{
"id": "8b0a037f-67cb-44b7-ac2a-18e7a54561a8",
"blockchain": "ethereum",
"provider_name": "metamask",
"provider_display_name": "MetaMask",
"last_connected": 1420069800000,
"created_at": 1420069800000
}
]
}
]
}
This function returns all users registered with the application. You must have authorization to the users.
Full Object Description
NOTE: User lists return a limited object in the list as seen in the example to the right. To obtain the full object for a user, request a specific user with the appropriate id
.
Client SDK for JS
Not Available
Server SDK for JS
zabo.users.getList()
HTTP Request
GET BASE_URL/users
Provider Support
Not applicable
Get a user
Get user information:
Not available from application clients, only servers
Returns the
user
JSON:
{
"id": "17c0f27e-9916-4ace-b8ca-18d1be2cff43",
"accounts": [
{
"id": "8b0a037f-67cb-44b7-ac2a-18e7a54561a8",
"blockchain": "ethereum",
"provider": {
"name": "metamask",
"display_name": "MetaMask",
"logo": "https://cdn.zabo.com/assets/providers/metamask.png",
"auth_type": "private_key",
"scopes": ["read_balances", "read_transactions", "get_deposit_addresses", "create_deposit_address"],
"resource_type": "provider"
},
"last_connected": 1420069800000
}
],
"created_at": 1420069800000,
"updated_at": 1420069800000,
"resource_type": "user",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This function returns the user requested. The user object contains the user's unique id and accounts information, including the provider used during connection with your app.
Full Object Description
Client SDK for JS
Not Available
Server SDK for JS
zabo.users.getOne(userId)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
userId | string | Required | The user ID for the request. |
HTTP Request
GET BASE_URL/users/:user_id
Provider Support
Not applicable
Get a user account
Get user information:
Not available from application clients, only servers
Returns the
user
JSON:
{
"id": "8b0a037f-67cb-44b7-ac2a-18e7a54561a8",
"provider": {
"name": "metamask",
"display_name": "MetaMask",
"logo": "https://cdn.zabo.com/assets/providers/metamask.png",
"auth_type": "private_key",
"scopes": ["read_balances", "read_transactions", "get_deposit_addresses", "create_deposit_address"],
"resource_type": "provider"
},
"balances": [
{
"ticker": "ETH",
"provider_ticker": "ETH",
"name": "Ether",
"asset_is_verified": true,
"asset_type": "account",
"amount": "5.068",
"decimals": 18,
"fiat_ticker": "USD",
"fiat_value": "12358.6201",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"updated_at": 1560134750000,
"misc": null,
"resource_type": "balance"
}
],
"blockchain": "ethereum",
"created_at": 1560134750000,
"updated_at": 1560134750000,
"resource_type": "account",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This function returns the full account object for a particular user requested.
Full Object Description
Client SDK for JS
Not Available
Server SDK for JS
zabo.users.getAccount({userId, accountId})
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
userId | string | Required | The user ID for the request. |
accountId | string | Required | The account ID for the request. |
HTTP Request
GET BASE_URL/users/:user_id/accounts/:account_id
Provider Support
All
Add account to existing user
Add account to user:
Not available from application clients, only servers
Returns Response (201) and the following JSON:
{
"id": "17c0f27e-9916-4ace-b8ca-18d1be2cff43",
"application": {
"id": "b5cfb0d8-58de-4786-9545-3d38521d7d2b",
"name": "Your App Name"
},
"accounts": [
{
"id": "8b0a037f-67cb-44b7-ac2a-18e7a54561a8",
"blockchain": "ethereum",
"provider": {
"name": "metamask",
"display_name": "MetaMask",
"logo": "https://cdn.zabo.com/assets/providers/metamask.png",
"auth_type": "private_key",
"scopes": ["read_balances", "read_transactions", "get_deposit_addresses", "create_deposit_address"],
"resource_type": "provider"
}
},
{
"id": "d838a489-7956-46e5-bb8a-a35ef757277a",
"blockchain": null,
"provider": {
"name": "coinbase",
"display_name": "Coinbase",
"logo": "https://cdn.zabo.com/assets/providers/coinbase.png",
"auth_type": "oauth",
"scopes": ["read_balances", "read_transactions", "get_deposit_addresses", "create_deposit_address"],
"resource_type": "provider"
}
}
],
"created_at": 1420069800000,
"updated_at": 1420069800000,
"resource_type": "user",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This function inserts an additional account into a given user object. Useful when your application makes it possible for the same user to connect with multiple providers.
Full Object Description
Client SDK for JS
Not Available
Server SDK for JS
zabo.users.addAccount(user, account)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
user | object | Required | The user object received from zabo.users.create() response. |
account | object | Required | The account object received when the user connected. This object must contain a valid token. |
HTTP Request
POST BASE_URL/users/:user_id/accounts
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
account | object | Required | The account object received from the Zabo Client after a user has connected an account, in the onConnection event. The token field must be present and associated with an active account. |
Provider Support
Not applicable
Remove account from user
Remove account from user:
Not available from application clients, only servers
Returns Response (201) and the following JSON:
{
"id": "17c0f27e-9916-4ace-b8ca-18d1be2cff43",
"application": {
"id": "b5cfb0d8-58de-4786-9545-3d38521d7d2b",
"name": "Your App Name"
},
"accounts": [
{
"id": "8b0a037f-67cb-44b7-ac2a-18e7a54561a8",
"blockchain": "ethereum",
"provider": {
"name": "metamask",
"display_name": "MetaMask",
"logo": "https://cdn.zabo.com/assets/providers/metamask.png",
"auth_type": "private_key",
"scopes": ["read_balances", "read_transactions", "get_deposit_addresses", "create_deposit_address"],
"resource_type": "provider"
}
}
],
"created_at": 1420069800000,
"updated_at": 1420069800000,
"resource_type": "user",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This function removes a defined account from a given user object. Use this function when a user doesn't want to have any specific provider account linked to your application anymore.
Full Object Description
Client SDK for JS
Not Available
Server SDK for JS
zabo.users.removeAccount({userId, accountId})
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
userId | string | Required | ID of the user. |
accountId | string | Required | ID of the account to remove. |
HTTP Request
DELETE BASE_URL/users/:user_id/accounts/:account_id
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
userId | string | Required | String UUID of the user established with Zabo. |
accountId | string | Required | String UUID of an account that belongs to the user. |
Provider Support
Not applicable
Create a deposit address
zabo.accounts.createDepositAddress('DAI').then(function(response) {
console.log(response.address)
/* address is the string outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let response = await zabo.accounts.createDepositAddress('DAI')
} catch (error) {
console.log(error)
}
Returns Response (200) and the following JSON:
{
"currency": {
"ticker": "DAI",
"name": "Dai",
"type": "ERC20",
"priority": 5,
"logo": "https://cdn.zabo.com/assets/currencies/DAI.png",
"decimals": 18,
"address": "0x62a6ebC0ac598819CCad368788F6d2357FaE0d9e",
"resource_type": "currency"
},
"provider_ticker": "DAI",
"address": "0xdffC30d992b716a394357E3f311c97f36794C903",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This endpoint will create and return a deposit address for the specified account. If the currency is not supported by the connected provider, you will receive an 'unsupported' error. See Unsupported Functions for more information.
Full Object Description
Client SDK for JS
zabo.accounts.createDepositAddress(ticker)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
ticker | string | Required | Three-letter identifier for the currency this deposit address should be used for. |
Server SDK for JS
zabo.users.createDepositAddress({userId, accountId, ticker})
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
userId | string | Required | String UUID of the user established with Zabo. |
accountId | string | Required | String UUID of an account that belongs to the user. |
ticker | string | Required | 3-letter (or more) short string identifier for the currency to be deposited. |
HTTP Request
From Client: POST BASE_URL/accounts/:account_id/deposit-addresses
From Server: POST BASE_URL/users/:user_id/accounts/:account_id/deposit-addresses
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ticker | string | Required | Three-letter identifier for the currency this deposit address should be used for. |
Provider Support
Binance does not support creating new deposit addresses. It provides one static address per account and this address will be returned when createDepositAddress
is used. To retrieve this address using the REST API, use the GET /accounts/:account_id/deposit-addresses
endpoint documented below.
Get deposit addresses
zabo.accounts.getDepositAddresses('BTC').then(function(addresses) {
console.log(addresses)
/* addresses is the object outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let addresses = await zabo.accounts.getDepositAddresses('BTC')
} catch (error) {
console.log(error)
}
Returns Response (200) and the following JSON:
{
"data": [
{
"ticker": "BTC",
"provider_ticker": "XBT",
"address": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
"resource_type": "deposit_address"
}
],
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This endpoint will retrieve all deposit addresses for the specified account. If the currency is not supported by the connected provider, you will receive an 'unsupported' error. See Unsupported Functions for more information.
Full Object Description
Client SDK for JS
zabo.accounts.getDepositAddresses(ticker)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
ticker | string | Required | Three-letter identifier for the currency this deposit address should be used for. |
Server SDK for JS
zabo.users.getDepositAddresses({userId, accountId, ticker})
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
userId | string | Required | String UUID of the user established with Zabo. |
accountId | string | Required | String UUID of an account that belongs to the user. |
ticker | string | Required | 3-letter (or more) short string identifier for the currency to be deposited. |
HTTP Request
From Client: GET BASE_URL/accounts/:account_id/deposit-addresses
From Server: GET BASE_URL/users/:user_id/accounts/:account_id/deposit-addresses
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ticker | string | Required | Three-letter identifier for the currency this deposit address should be used for. |
Provider Support
All
Get team
zabo.getTeam().then(function(team) {
console.log(team)
/* team is the limited object outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let app = await zabo.getTeam()
} catch (error) {
console.log(error)
}
The Client SDK returns the limited 'team' JSON:
{
"id": "b5cfb0d8-58de-4786-9545-3d38521d7d2b",
"name": "New Team Name"
}
The Server SDK and the REST API returns Response (200) and the following JSON:
{
"id": "b5cfb0d8-58de-4786-9545-3d38521d7d2b",
"client_id": "aPublicKeyIdentifyingYourTeam",
"name": "New Team Name",
"tier": "developer",
"type": "business",
"use_case": "Description from the input.",
"members": {
"total": 1,
"data": [
{
"id": "663925bd-205d-479e-895f-27ec3891e8b3",
"first_name": "Zabo",
"last_name": "Master",
"emails": ["anemail@interwebs.org"],
"paired_id": "b5cfb0d8-58de-4786-9545-3d38521d7d2b",
"is_primary_contact": true,
"role": "Owner"
}
]
},
"authorized_origins": ["zabo.com", "www.zabo.com"],
"website": "zabo.com",
"needs_review": false,
"connections": [],
"invites": [],
"created_at": 14200698000000,
"updated_at": 14200698000000,
"resource_type": "team",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This endpoint will return the specified team resource. You must have access rights to the team.
Full Object Description
Client SDK for JS
zabo.getTeam()
Server SDK for JS
zabo.getTeam()
HTTP Request
GET BASE_URL/teams/:team_id
Provider Support
Not applicable
WebHooks
Zabo has introduced WebHooks which allow server-based applications to receive information directly to their server. There are currently two event types that we can POST to an endpoint provided to us through your Zabo Dashboard: New Account Connections and Transaction History Updates.
WebHook Setup
Zabo can POST successful account connections and transaction updates to a webhook you provide in your Zabo Dashboard. This webhook should be a URL to your system that is ready to accept the POST request. To set this up, sign in to your Zabo Dashboard, and navigate to Team Settings -> Developer Settings, then click on the WebHook tab seen below:
HTTPS is required, and be sure to "Enable" the webhook once you are ready to receive events! Continue reading to see the event types and data your webhook will receive.
New Account Connections
Successful webhook POST:
{
"event": "account.post",
"data": {
"id": "663925bd-205d-479e-895f-27ec3891e8b3",
"token": "zabosession-abcdef1234567890",
"exp_time": "Mon, 10 Jun 2019 02:45:50 UTC",
"provider": {
"name": "coinbase",
"display_name": "Coinbase",
"logo": "https://cdn.zabo.com/assets/providers/coinbase.png",
"type": "oauth",
"scopes": [
"read_transaction_history",
"read_balances",
"get_deposit_addresses",
"create_deposit_address"
],
"resource_type": "provider"
},
"balances": [
{
"ticker": "OXT",
"provider_ticker": "OXT",
"name": "Orchid",
"asset_is_verified": true,
"asset_type": "ERC20",
"amount": "0.49040326",
"decimals": 18,
"fiat_ticker": "USD",
"fiat_value": "0.0000",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/OXT.png",
"updated_at": 1576052555883,
"misc": [],
"resource_type": "balance"
},
{
"ticker": "ETH",
"provider_ticker": "ETH",
"name": "Ether",
"asset_is_verified": true,
"asset_type": "account",
"amount": "0.06249079",
"decimals": 18,
"fiat_ticker": "USD",
"fiat_value": "20.1301",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/ETH.png",
"updated_at": 1576052555893,
"misc": [],
"resource_type": "balance"
},
{
"ticker": "BTC",
"provider_ticker": "BTC",
"name": "Bitcoin",
"asset_is_verified": true,
"asset_type": "UTXO",
"amount": "0.00000435",
"decimals": 8,
"fiat_ticker": "USD",
"fiat_value": "0.0488",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"updated_at": 1576052555904,
"misc": [],
"resource_type": "balance"
}
],
"blockchain": null,
"created_at": 1573545638442,
"updated_at": 1576052554115,
"resource_type": "account"
},
"timestamp": 1576052555923,
"resourceType": "webhook"
}
Event Type
account.post
The example WebHook response to the right shows the object that will be provided in the body of a POST request to your application webhook URL when a user connects their account to your application. For new account connection POST calls, we also provide a process for your client to pass custom information to your server. You can accomplish this by setting the Zabo Connect Widget URL yourself, when a user is ready to connect, and adding query parameters to this URL, such as the following: https://connect.zabo.com/connect?client_id=clientIDFromYourDashboard&origin=localhost&zabo_env=sandbox&zabo_version=latest&customParamOne=SomeValue&customParamTwo=AnotherValue
. By adding these custom parameters, Zabo will pass them as a string in the Header of the POST request using the X-Connect-Meta
key. The full header would look like X-Connect-Meta: customParamOne=SomeValue&customParamTwo=AnotherValue
.
Adding custom parameters via Connect URL:
"https://connect.zabo.com/connect?client_id=clientIDFromYourDashboard&origin=localhost&zabo_env=sandbox&zabo_version=latest&customParamOne=SomeValue&customParamTwo=AnotherValue"
You can also add custom parameters via JS SDK passing the params
object when calling the connect
function:
Adding custom parameters via SDK:
zabo.connect({
params: {
customParamOne: "SomeValue",
customParamTwo: "AnotherValue"
}
})
zabo.connect({ params })
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
params | object | Optional | The object containing the key/value pairs to be added as query parameters when opening the Zabo Connect Widget. |
Transaction and Balance Updates
Successful webhook POST:
{
"event": "transactions.update",
"data": {
"account_id": "663925bd-205d-479e-895f-27ec3891e8b3",
"balances": [
{
"ticker": "OXT",
"provider_ticker": "OXT",
"name": "Orchid",
"asset_is_verified": true,
"asset_type": "ERC20",
"amount": "0.49040326",
"decimals": 18,
"fiat_ticker": "USD",
"fiat_value": "0.0000",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/OXT.png",
"updated_at": 1576052555883,
"misc": [],
"resource_type": "balance"
},
{
"ticker": "ETH",
"provider_ticker": "ETH",
"name": "Ether",
"asset_is_verified": true,
"asset_type": "account",
"amount": "0.06249079",
"decimals": 18,
"fiat_ticker": "USD",
"fiat_value": "20.1301",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/ETH.png",
"updated_at": 1576052555893,
"misc": [],
"resource_type": "balance"
},
{
"ticker": "BTC",
"provider_ticker": "BTC",
"name": "Bitcoin",
"asset_is_verified": true,
"asset_type": "UTXO",
"amount": "0.00000435",
"decimals": 8,
"fiat_ticker": "USD",
"fiat_value": "0.0488",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"updated_at": 1576052555904,
"misc": [],
"resource_type": "balance"
}
],
"transactions": [
{
"id": "0x343d19bf733aa10fca5e066f6318921f3f6ad081f568f256af7478cc75b1f391",
"status": "completed",
"transaction_type": "withdrawal",
"parts": [
{
"direction": "sent",
"ticker": "ETH",
"provider_ticker": "ETH",
"amount": "19000000000000000",
"asset_is_verified": true,
"fiat_ticker": "",
"fiat_value": "",
"fiat_asset_is_verified": false,
"other_parties": [
"0x621e2F127b9a730911aE5929185EeFDfa7a657FE"
]
}
],
"fees": [
{
"type": "network",
"ticker": "ETH",
"provider_ticker": "ETH",
"amount": "1305162000000000",
"asset_is_verified": true,
"fiat_ticker": "",
"fiat_value": "",
"fiat_asset_is_verified": false,
"resource_type": "transaction_fee"
}
],
"misc": [],
"fiat_calculated_at": 1606311952000,
"initiated_at": 1606311952000,
"confirmed_at": 1606311952000,
"resource_type": "transaction"
},
{
"id": "0xc66b68364c67a44ecfe78a23f40bc4fa3e784d18c0e8ee7a84b3a38bf6aaf6a7",
"status": "completed",
"transaction_type": "deposit",
"parts": [
{
"direction": "received",
"ticker": "ETH",
"provider_ticker": "ETH",
"amount": "21096000000000000",
"asset_is_verified": true,
"fiat_ticker": "",
"fiat_value": "",
"fiat_asset_is_verified": false,
"other_parties": [
"0x3A8BfD106F8Bed4623143127A55212a42c38dF75"
]
}
],
"fees": [],
"misc": [],
"fiat_calculated_at": 1606047001000,
"initiated_at": 1606047001000,
"confirmed_at": 1606047001000,
"resource_type": "transaction"
}
]
},
"timestamp": 1576052587433,
"resourceType": "webhook"
}
Event Type
transactions.update
Transaction and balance updates are provided hourly. One important thing to note is that these updates will only occur if there are changes to the account. If there are no new transactions and no resulting balance changes, then the webhook URL will not receive any data for that hour. The information received within the data
key are as follows:
account_id
: The UUID of the account being updatedbalances
: An array of updated Balance Objectstransactions
: An array of new Transaction Objects
Data Endpoints
The following endpoints will provide general crypto information.
Get exchange rates
Get a list of current market exchange rates for all supported cryptocurrencies and assets.
zabo.currencies.getExchangeRates().then(function(exchangeRates) {
console.log(exchangeRates)
/* exchangeRates is the array outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let exchangeRates = await zabo.currencies.getExchangeRates()
} catch (error) {
console.log(error)
}
The SDK returns the list:
[
{
"from": "BTC",
"to": "USD",
"rate": "8000.00",
"timestamp": 145824503000,
"resource_type": "exchange_rate"
},
{
"from": "ETH",
"to": "USD",
"rate": "300.00",
"timestamp": 145824503000,
"resource_type": "exchange_rate"
}
]
The REST API returns the following JSON object:
{
"list_cursor": {
"limit": 25,
"has_more": false,
"self_uri": "/exchange-rates?limit=25",
"next_uri": ""
},
"data": [
{
"from": "BTC",
"to": "USD",
"rate": "8000.00",
"timestamp": 145824503000,
"resource_type": "exchange_rate"
},
{
"from": "ETH",
"to": "USD",
"rate": "300.00",
"timestamp": 145824503000,
"resource_type": "exchange_rate"
}
],
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
Or the following JSON object if a
tickers
paramter is provided:
{
"from": "BTC",
"to": "USD",
"rate": "8000.00",
"timestamp": 145824503000,
"resource_type": "exchange_rate",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This function returns a list of exchange rates for the available cryptocurrencies/assets for a given fiat currency. Currently, USD is the only fiat currency available. Any supported assets can be used for the tickers
parameter. This parameter is optional and, if left out, all supported cryptocurrencies/assets will be returned.
Full Object Description
Client SDK for JS
zabo.currencies.getExchangeRates({ tickers, toCrypto })
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
tickers | string | Optional | If left out, all supported cryptocurrencies and assets are returned. |
toCrypto | bool | Optional | Default is false and provides exchange rate to the fiat currency. If true, the rate will be cryptocurrency per unit of fiat. |
Server SDK for JS
zabo.currencies.getExchangeRates({ cryptoCurrency, toCrypto })
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
tickers | string | Optional | If left out, all supported cryptocurrencies and assets are returned. |
toCrypto | bool | Optional | Default is false and provides exchange rate to the fiat currency. If true, the rate will be cryptocurrency per unit of fiat. |
HTTP Request
GET BASE_URL/exchange-rates
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
tickers | string | Optional | If left out, all supported cryptocurrencies and assets are returned. |
to_crypto | bool | Optional | Default is false and provides exchange rate to the fiat currency. If true, the rate will be cryptocurrency per unit of fiat. |
Provider Support
Not Applicable
Get all currencies
zabo.currencies.getList().then(function(currencies) {
console.log(currencies)
/* currencies is the object outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let currencies = await zabo.currencies.getList()
} catch (error) {
console.log(error)
}
The SDK returns the list:
[
{
"ticker": "BTC",
"name": "Bitcoin",
"type": "UTXO",
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"decimals": 9,
"address": null,
"resource_type": "currency"
},
{
"ticker": "ETH",
"name": "Ether",
"type": "account",
"logo": "https://cdn.zabo.com/assets/currencies/ETH.png",
"decimals": 18,
"address": null,
"resource_type": "currency"
},
{
"ticker": "DAI",
"name": "Dai",
"type": "ERC20",
"logo": "https://cdn.zabo.com/assets/currencies/DAI.png",
"decimals": 18,
"address": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
"resource_type": "currency"
}
]
The REST API returns the following JSON object:
{
"list_cursor": {
"limit": 25,
"has_more": false,
"self_uri": "/currencies?limit=25",
"next_uri": ""
},
"data": [
{
"ticker": "BTC",
"name": "Bitcoin",
"type": "UTXO",
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"decimals": 9,
"address": null,
"resource_type": "currency"
},
{
"ticker": "ETH",
"name": "Ether",
"type": "account",
"logo": "https://cdn.zabo.com/assets/currencies/ETH.png",
"decimals": 18,
"address": null,
"resource_type": "currency"
},
{
"ticker": "DAI",
"name": "Dai",
"type": "ERC20",
"logo": "https://cdn.zabo.com/assets/currencies/DAI.png",
"decimals": 18,
"address": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359",
"resource_type": "currency"
}
],
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This endpoint will return the full list of currencies available in the system. Use the /providers
endpoint documented below to see the currencies supported by each provider.
Full Object Description
Client SDK for JS
zabo.currencies.getList()
Server SDK for JS
zabo.currencies.getList()
HTTP Request
GET BASE_URL/currencies
Provider Support
Not Applicable
Get specific currency
zabo.currencies.getOne('btc').then(function(currency) {
console.log(currency)
/* currency is the object outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
Returns Response (200) and the following JSON:
{
"ticker": "BTC",
"name": "Bitcoin",
"type": "UTXO",
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"decimals": 8,
"address": null,
"resource_type": "currency",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This endpoint provides information about a specific currency.
Full Object Description
Client SDK for JS
zabo.currencies.getOne(ticker)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
ticker | string | Required | 3-letter (or more) short string identifier for this currency or asset |
Server SDK for JS
zabo.currencies.getOne(ticker)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
ticker | string | Required | 3-letter (or more) short string identifier for this currency or asset |
HTTP Request
GET BASE_URL/currencies/:ticker
Provider Support
Not Applicable
Get providers
zabo.providers.getList().then(function(providers) {
console.log(providers)
/* providers is the object outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let providers = await zabo.providers.getList()
} catch (error) {
console.log(error)
}
Returns Response (200) and the following JSON:
{
"list_cursor": {
"limit": 25,
"has_more": false,
"self_uri": "/providers?limit=25",
"next_uri": ""
},
"data": [
{
"name": "coinbase",
"display_name": "Coinbase",
"logo": "https://cdn.zabo.com/assets/providers/coinbase.png",
"auth_type": "oauth",
"resource_type": "provider",
"available_currencies": [{ "type": "account", "list": [ "ETH" ], "resource_type": "currency_list" },{ "type": "UTXO", "list": [ "BTC" ], "resource_type": "currency_list" }],
"resource_type": "provider"
},
{
"name": "metamask",
"display_name": "MetaMask",
"logo": "https://cdn.zabo.com/assets/providers/metamask.png",
"auth_type": "private_key",
"resource_type": "provider",
"available_currencies": [{ "type": "account", "list": [ "ETH" ], "resource_type": "currency_list" }, { "type": "ERC20", "list": [ "ALL" ], "resource_type": "currency_list" }],
"resource_type": "provider"
},
{
"name": "ledger",
"display_name": "Ledger Hardware Wallet",
"logo": "https://cdn.zabo.com/assets/providers/ledger.png",
"auth_type": "private_key",
"resource_type": "provider",
"available_currencies": [{ "type": "account", "list": [ "ALL" ], "resource_type": "currency_list" }, { "type": "ERC20", "list": [ "ALL" ], "resource_type": "currency_list" }],
"resource_type": "provider"
}
],
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This endpoint will return the list of all providers available for an application as well as the scopes and currencies available for that particular provider.
Full Object Description
Client SDK for JS
zabo.providers.getList()
Server SDK for JS
zabo.providers.getList()
HTTP Request
GET BASE_URL/providers
Provider Support
Not Applicable
Get a provider
zabo.providers.getOne('metamask').then(function(provider) {
console.log(provider)
/* provider is the object outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
Returns Response (200) and the following JSON:
{
"name": "metamask",
"display_name": "MetaMask",
"logo": "https://cdn.zabo.com/assets/providers/metamask.png",
"auth_type": "private_key",
"available_currencies": [{ "type": "account", "list": [ "ETH" ], "resource_type": "currency_list" }, { "type": "ERC20", "list": [ "ALL" ], "resource_type": "currency_list" }],
"resource_type": "provider",
"request_id": "3c98ed84-175d-47ce-95a7-c26e3561bc47"
}
This endpoint will return the requested provider resource. Note: The provider name is the all lowercase 'computer' name for the provider, not the display name.
Full Object Description
Client SDK for JS
zabo.providers.getOne(name)
Server SDK for JS
zabo.providers.getOne(name)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Required | Name of the provider |
HTTP Request
GET BASE_URL/providers/:provider_name
Provider Support
Not Applicable
Zabo Objects
The following is a full list and description of the objects that the Zabo API produces.
Account Object
{
"id": "663925bd-205d-479e-895f-27ec3891e8b3",
"provider": {
"name": "coinbase",
"display_name": "Coinbase",
"logo": "https://cdn.zabo.com/assets/providers/coinbase.png",
"type": "oauth",
"scopes": ["read_balances", "read_transactions", "send_crypto", "receive_crypto"],
"resource_type": "provider"
},
"balances": [
{
"ticker": "ETH",
"provider_ticker": "ETH",
"name": "Ether",
"asset_is_verified": true,
"asset_type": "account",
"amount": "5.068",
"decimals": 18,
"fiat_ticker": "USD",
"fiat_value": "12358.6201",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"updated_at": 1560134750000,
"misc": [],
"resource_type": "balance"
},
{
"ticker": "BTC",
"provider_ticker": "BTC",
"name": "Bitcoin",
"asset_is_verified": true,
"asset_type": "UTXO",
"amount": "0.932",
"decimals": 8,
"fiat_ticker": "USD",
"fiat_value": "58092.091",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/ETH.png",
"updated_at": 1560134750000,
"misc": [],
"resource_type": "balance"
}
],
"blockchain": null,
"created_at": 1560134750000,
"updated_at": 1560134750000,
"resource_type": "account"
}
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
id | string | uuidV4 | This is the base identifier for the Zabo Account. |
provider | object | Provider Object | The provider which provided this user's account. |
balances | array | Array of Balance Objects | An array of asset balances held in this account. |
blockchain | string | null OR One of these Supported Blockchains | If the account is provided by an exchange provider, the value is null . If the account is provided by self-custody wallet software, the value will be the blockchain used by this account. |
created_at | number | Timestamp | Timestamp this Zabo Account was created. |
updated_at | number | Timestamp | Timestamp this Zabo Account was last updated. |
resource_type | string | account | This object type. |
Supported Blockchains
List
Name | Value |
---|---|
Tezos | tezos |
Bitcoin | bitcoin |
Ethereum | ethereum |
Hedera Hashgraph | hedera |
DASH | dash |
Neo | neo |
Ripple | ripple |
Bitcoin Cash | bitcoin-cash |
EOSIO | eosio |
Bitcoin SV | bitcoin-sv |
Litecoin | litecoin |
Decred | decred |
Zcash | zcash |
Stellar | stellar |
Cosmos | cosmos |
Ethereum Classic | ethereum-classic |
Balance Object
{
"ticker": "BTC",
"provider_ticker": "BTC",
"name": "Bitcoin",
"asset_is_verified": true,
"asset_type": "UTXO",
"amount": "0.932",
"decimals": 8,
"fiat_ticker": "USD",
"fiat_value": "58092.091",
"fiat_asset_is_verified": true,
"logo": "https://cdn.zabo.com/assets/currencies/ETH.png",
"updated_at": 1606311952000,
"misc": [],
"resource_type": "balance"
}
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
ticker | string | Asset Ticker | The 3-letter (or more) short string identifier for this asset, e.g. "BTC" or "ETH". |
provider_ticker | string | Provider's Asset Ticker | The connected underlying provider's 3-letter (or more) short string identifier for this asset, e.g. "XBT" for "BTC". |
name | string | Name | The name for this asset, e.g. "Bitcoin". |
asset_is_verified | bool | true or false | A verified asset is one that has been verified by Zabo with the correct fiat value and having the correct format, including the number of decimal places. If this is labeled as false, that means the amount returned is exactly "as is" from the provider, likely because the asset they use has not yet been verified. |
asset_type | string | One of these Asset Types | The type of ledger technology used for this cryptocurrency. |
amount | string | Floating-Point Number as String | The current balance of this asset held by the account, set as a string type, e.g. "5.068". |
decimals | number | Integer | See Decimals in the Cryptocurrency explanation below. |
fiat_ticker | string | Fiat Ticker | The 3-letter (or more) short string identifier for the fiat currency used to calculate this balance's fiat_value . See Fiat Currency for more information on fiat currency, e.g. "USD". |
fiat_value | string | Floating-Point Number as String | The value of this balance in terms of the given fiat_ticker , e.g. a fiat_value of "2358.6201" with fiat_ticker of "USD" means that this balance is currently worth around $2358.62 |
fiat_asset_is_verified | bool | true or false | A verified fiat asset is one that has been verified by Zabo with the correct fiat value and having the correct format. If this is labeled as false, we haven't been able to calculate the fiat value for this balance, likely because the fiat asset they use has not yet been verified. |
logo | string | URL | A link to an image of this asset, only available for verified assets. |
updated_at | number | Timestamp | Timestamp this balance was last updated. |
misc | string array | Varies | This field is used as meta-data for information that is not standardized. |
resource_type | string | balance | This object type. |
Transaction Object
{
"id": "0x158be2ad4ba161c1a67e9b5646d2ed35bd4940b708103635dfd84f5ef252c18a",
"status": "completed",
"transaction_type": "send",
"parts": [
{
"direction": "sent",
"ticker": "ETH",
"provider_ticker": "ETH",
"amount": ".019",
"asset_is_verified": true,
"fiat_ticker": "USD",
"fiat_value": "41.28",
"fiat_asset_is_verified": false,
"other_parties": [
"0x621e2F127b9a730911aE5929185EeFDfa7a657FE"
]
}
],
"fees": [
{
"type": "network",
"ticker": "ETH",
"provider_ticker": "ETH",
"amount": ".001305162",
"asset_is_verified": true,
"fiat_ticker": "USD",
"fiat_value": "2.62",
"fiat_asset_is_verified": false,
"resource_type": "transaction_fee"
}
],
"misc": ["ethereum"],
"fiat_calculated_at": 1606311952000,
"initiated_at": 1606311952000,
"confirmed_at": 1606311952000,
"resource_type": "transaction"
}
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
id | string | Varies | This is the base identifier for the Transaction. If the transaction took place with an exchange provider, then it may be in uuid format, if the transaction took place with self cutody wallet software, then it may be a different format. |
status | string | One of these Transaction Statuses | The current status of this transaction. |
transaction_type | string | One of these Transaction Types | The type of transaction this object represents. |
parts | array of objects | One or more Transaction Parts | Transaction parts help identify what type of transaction this is, and allow us to generically handle everything from a simple deposit transaction to a multi-part DeFi transaction. |
fees | array | Array of Fee Objects | An array of fees charged for this transaction. |
misc | string array | Varies | This field is used as meta-data for information that is not standardized. For certain blockchain transactions, it is the name of the blockchain network, for transactions that use particular smart contracts, such as UniSwap, it is the name of the "decentralized" application. |
fiat_calculated_at | number | Timestamp | Timestamp of the fiat_value calculation. |
initiated_at | number | Timestamp | Timestamp this transaction was initiated. |
confirmed_at | number | null OR Timestamp | Timestamp this transaction was confirmed if status is not pending. If status is pending , this field will be null . |
resource_type | string | transaction | This object type. |
Transaction Part Object
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
direction | string | See Part Directions below | The direction of money flow in this transaction part. |
ticker | string | Currency Ticker | The 3-letter (or more) short string identifier of the asset used in this transaction part, e.g. "BTC" or "ETH". |
provider_ticker | string | Provider's Currency Ticker | The connected underlying provider's 3-letter (or more) short string identifier for this asset, e.g. "XBT" for "BTC". |
amount | string | Floating-Point Number as String | The amount of the asset involved in this transaction part, set as a string type, e.g. if amount is "5.068" and asset is "ETH" , then this transaction part involves 5.068 ETH . |
asset_is_verified | bool | true or false | A verified asset is one that has been verified by Zabo with the correct fiat value and having the correct format, including the number of decimal places. If this is labeled as false, that means the amount returned is exactly "as is" from the provider, likely because the asset they use has not yet been verified. |
fiat_ticker | string | Currency Ticker | The 3-letter (or more) short string identifier for the fiat currency used to calculate this transaction part's fiat_value . See Fiat Currency for more information on fiat currency, e.g. "USD". |
fiat_value | string | Floating-Point Number as String | The value of this transaction part in terms of the given fiat_ticker . ie a fiat_value of "2358.6201" with fiat_ticker of "USD" means that this transaction part was worth around $2358.62 when it was executed |
fiat_asset_is_verified | bool | true or false | A verified fiat asset is one that has been verified by Zabo with the correct fiat value and having the correct format. If this is labeled as false, we haven't been able to calculate the fiat value for this transaction part, likely because the fiat asset they use has not yet been verified. |
other_parties | array | null OR Array of Strings | This represents other cryptocurrency accounts involved in this transaction part. If direction is sent , then this is the list of transaction part recipients. If direction is received , then this is the list of transaction part sources. |
resource_type | string | transaction_fee | This object type. |
Part Directions
List
Name | Value | Description |
---|---|---|
Sent | sent | Sent direction marks the transaction part as money being withdrawn from the account/wallet. |
Received | received | Received direction marks the transaction part as money being deposited to the account/wallet. |
Fee Object
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
type | string | See Fee Types below | The type of fee this object represents. |
ticker | string | Asset Ticker | The 3-letter (or more) short string identifier of the currency used to pay this fee, e.g. "BTC" or "USD". |
provider_ticker | string | Provider's Asset Ticker | The connected underlying provider's 3-letter (or more) short string identifier for this asset, e.g. "XBT" for "BTC". |
amount | string | Floating-Point Number as String | The amount of the asset ticker paid in this fee. |
asset_is_verified | bool | true or false | A verified asset is one that has been verified by Zabo with the correct fiat value and having the correct format. If this is labeled as false, that means the amount returned is exactly "as is" from the provider, likely because the asset they use has not yet been verified. |
fiat_ticker | string | Currency Ticker | The 3-letter (or more) short string identifier for the fiat currency used to calculate this fee's fiat_value . See Fiat Currency for more information on fiat currency, e.g. "USD". |
fiat_value | string | Floating-Point Number as String | The value of this fee in terms of the given transaction fiat_ticker currency, e.g. a fiat_value of "0.1101" with fiat_ticker of "USD" means that this fee was worth around $0.11. |
fiat_asset_is_verified | bool | true or false | A verified fiat asset is one that has been verified by Zabo with the correct fiat value and having the correct format. If this is labeled as false, we haven't been able to calculate the fiat value for this fee, likely because the fiat asset they use has not yet been verified. |
resource_type | string | transaction_fee | This object type. |
Fee Types
List
Name | Value | Description |
---|---|---|
Network | network | This fee type is paid to the blockchain network that executed this transaction. These fees are paid in cryptocurrency, e.g. "Mining" fees in the Bitcoin network, or "Gas" costs in the Ethereum network. |
Exchange | exchange | This fee type is paid to exchange providers for things such as buying and selling cryptocurrency. |
Transaction Types
List
Name | Value | Description |
---|---|---|
Deposit | deposit | The transaction was sent to the account. Deposits usually have just one transaction part. |
Withdrawal | withdrawal | The transacton was sent from the account. Withdrawals usually have just one transaction part. |
Trade | trade | A trade usually involves 2 parts to a transaction. |
Other | other | Any other type of transaction, for instance, DeFi transactions with 3 or more parts. |
Transaction Statuses
List
Name | Value | Description |
---|---|---|
Completed | completed | The transaction was sent and executed. |
Failed | failed | The transaction was sent but failed to execute. |
Pending | pending | The transaction has been sent and is pending execution. |
Unknown | unknown | The transaction is too old and we cannot confirm if it failed or completed. |
User Object
{
"id": "17c0f27e-9916-4ace-b8ca-18d1be2cff43",
"accounts": [
{
"id": "8b0a037f-67cb-44b7-ac2a-18e7a54561a8",
"blockchain": "ethereum",
"provider": {
"name": "metamask",
"display_name": "MetaMask",
"logo": "https://cdn.zabo.com/assets/providers/metamask.png",
"type": "private_key",
"scopes": ["read_balances", "read_transactions", "send_crypto", "receive_crypto"],
"resource_type": "provider"
},
"last_connected": 1420069800000
}
],
"created_at": 1420069800000,
"updated_at": 1420069800000,
"resource_type": "user"
}
Fields
NOTE: Accounts contained within the user object are limited to only account.id
, account.blockchain
, and account.provider
fields. There is an additional last_connected
field for accounts within the user
object which provides the latest timestamp your application connected to this account, in milliseconds. To obtain a full account object, request the user account using the appropriate account.id
.
Name | Type | Possible Values | Description |
---|---|---|---|
id | string | uuidV4 | This is the base identifier for the Zabo User. |
accounts | array | Array of limited Account Objects | The list of accounts that belong to this user. |
created_at | number | Timestamp | Timestamp this Zabo User was created. |
updated_at | number | Timestamp | Timestamp this Zabo User was last updated. |
resource_type | string | user | This object type. |
Deposit Address Object
{
"ticker": "BTC",
"provider_ticker": "BTC",
"address": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
"resource_type": "deposit_address"
}
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
ticker | string OR object | Currency Ticker OR Currency Object | If retrieving existing deposit addresses for currency , this is the 3-letter (or more) short string identifier of the cryptocurrency associated with address . If creating a deposit address, this is a Currency Object for the cryptocurrency associated with the new address . |
provider_ticker | string | Provider's Currency Ticker | The connected underlying provider's 3-letter (or more) short string identifier for this currency, e.g. "XBT" for "BTC" |
address | string | Cryptocurrency network address | This address can be used by the application to deposit currency into the connected account. |
resource_type | string | deposit_address | This object type. |
Team Object
{
"id": "b5cfb0d8-58de-4786-9545-3d38521d7d2b",
"name": "Your Team Name",
}
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
id | string | uuidV4 | This is the base identifier for the Zabo Account. |
name | string | Varies | The name given to the team upon registration. |
Provider Object
Provider objects take two different forms depending on the context of the request. Provider objects contained within account objects return the currencies
and scopes
available to the account using this provider. Standalone provider objects do not contain scopes and provide available_currencies
with this provider.
Account Provider Object
{
"name": "metamask",
"display_name": "MetaMask",
"logo": "https://cdn.zabo.com/assets/providers/metamask.png",
"scopes": [
{
"name": "read_balances",
"display_name": "Read Balances",
"description": "Can read all balance information."
},
{
"name": "read_transaction_history",
"display_name": "Read Transaction History",
"description": "Can read all past transactions."
}
],
"currencies": [
{ "type": "account", "list": [ "ETH" ] },
{ "type": "ERC20", "list": [ "all" ] }
],
"resource_type": "provider"
}
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
name | string | Computer name of the provider | This is the computer name for the software or business that provides an account connection. Computer names are generally all lowercase strings of the provider's name. ie coinbase , metamask , binance |
display_name | string | Display name of the provider | This is a display friendly version of the provider's name. |
logo | string | URL | URL to the logo for this provider. |
auth_type | string | One of these Authentication Types | The type of authentication used by this provider. |
scopes | array | One of these Scopes | The scope of actions available from this provider. |
currencies | array | null OR Array of Currency List Objects | The list of cryptocurrencies available with this provider. |
resource_type | string | provider | This object type. |
Standalone Provider Object
{
"name": "metamask",
"display_name": "MetaMask",
"logo": "https://cdn.zabo.com/assets/providers/metamask.png",
"auth_type": "private_key",
"available_currencies": [{ "type": "account", "list": [ "ETH" ] }, { "type": "ERC20", "list": [ "all" ] }],
"resource_type": "provider"
}
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
name | string | Computer name of the provider | This is the computer name for the software or business that provides an account connection. Computer names are generally all lowercase strings of the provider's name. ie coinbase , metamask , binance |
display_name | string | Display name of the provider | This is a display friendly version of the provider's name. |
logo | string | URL | URL to the logo for this provider. |
auth_type | string | One of these Authentication Types | The type of authentication used by this provider. |
available_currencies | array | null OR Array of Currency List Objects | The list of cryptocurrencies available with this provider. |
resource_type | string | provider | This object type. |
Authentication Types
List
Name | Value | Description |
---|---|---|
Read Only | read_only | This provider is a "read only" connection. ie deposit addresses cannnot be created or used with this provider. |
Password | password | Connections are made with a username or email, and password. |
Token | token | Connections are made using a "first party" secret API token. |
Extended Public Key | xpub | This provider is a "self custody wallet" provider that establishes accounts with an HD Wallet keychain. See Self Custody Wallet in the Zabo Terminology section for more information. |
OAuth | oauth | Connections are made using the standard OAuth process. |
Web 3 Wallet | web3 | This provider is accesses through standard web3 interfaces. |
Scopes Available
List
Name | Value | Description |
---|---|---|
Get Deposit Address | get_deposit_address | This scope allows an application to obtain a deposit address for a connected account using this provider. |
Create Deposit Address | create_deposit_address | This scope allows an application to create a deposit address for a connected account using this provider. |
Read Transaction History | read_transaction_history | This scope allows an application to obtain historical transactions for a connected account using this provider. |
Read Balances | read_balances | This scope allows an application to obtain current balance information for a connected account using this provider. |
Currency Object
{
"ticker": "BTC",
"name": "Bitcoin",
"type": "UTXO",
"logo": "https://cdn.zabo.com/assets/currencies/BTC.png",
"decimals": 8,
"address": null,
"resource_type": "currency"
}
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
ticker | string | Currency Ticker | The 3-letter (or more) short string identifier for this currency, e.g. "BTC" or "ETH" |
name | string | Currency Name | The full name for this currency. |
type | string | One of these Cryptocurrency Types | The type of ledger technology used for this cryptocurrency. |
logo | string | URL | URL to the logo for this currency. |
decimals | number | Integer | See Decimals in the Currency Terms section below. |
address | string | null OR Smart Contract Address | If applicable, this is the location of the cryptocurrency's operating logic. See Cryptocurrency Types for more information. |
resource_type | string | currency | This object type. |
Currency List Object
{ "type": "UTXO", "list": [ "BTC" ], "resource_type": "currency_list" }
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
type | string | See Asset Type List below | The type of ledger technology used for this cryptocurrency. See Cryptocurrency Types in the Zabo Terminology section below for more information. |
list | array | Array of Currency Tickers | List of 3-letter (or more) short string identifiers for the currencies of the type defined, e.g. "BTC" or "ETH" |
resource_type | string | currency_list | This object type. |
Asset Type List
List
Name | Value | Description |
---|---|---|
UTXO | utxo | Unspent Transaction Output accounting is used, ie the Bitcoin network. |
Account | account | Accounts are established on the network at an address mapped to the paired secret key, ie the Ethereum network. |
ERC20 | erc20 | ERC, or Ethereum Request for Comments, is a process that seeks to establish standards for the Ethereum network. The proposal labeled ERC-20 is an accounting techonolgy developed and adopted through this process for smart contract networks, such as Ethereum. This type of cryptocurrency usually has a network address associated with it to identify the location of its ledger and operating logic. |
NOTE: See Cryptocurrency Types below for more information.
Exchange Rate Object
{
"from": "BTC",
"to": "USD",
"rate": "58000.00",
"timestamp": 145824503000,
"resource_type": "exchange_rate"
}
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
from | string | Currency Ticker | The 3-letter (or more) short string identifier for the currency being converted from, e.g. "BTC" or "ETH" |
to | string | Currency Ticker | The 3-letter (or more) short string identifier for the currency being converted to, e.g. "USD" |
rate | string | Floating-Point Number as String | The value of one unit of from in units of to . ie if from is BTC and to is USD, the rate would be the value of 1 Bitcoin in US Dollars |
timestamp | number | Timestamp | The timestamp of the given rate. |
Zabo Trading API (Beta)
Zabo has added trading capabilities into the API via the client interface! This is currently available as a Beta feature and only for Coinbase Pro and Binance accounts connected. Please note this is a beta feature and should be used at your own risk. For now, individual orders are limited to no more than $500. Let us know if you find it useful, as well as any issues with this service.
Get Trading Symbols
Get trading symbols:
zabo.trading.getSymbols().then(function(symbols) {
console.log(symbols)
/* symbols is the response outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let symbols = await zabo.trading.getSymbols()
} catch (error) {
console.log(error)
}
Returns the following response object:
{
"data": [
{
"base_currency":"ETH",
"quote_currency":"BTC"
},
{
"base_currency":"BCH",
"quote_currency":"BTC"
},
...
],
"request_id": "ee556fef-c83c-45a5-866c-ff30d8a60c4d"
}
This function returns the trading tickers available at the given account's provider. These pairs can be used in the remaining calls to the Zabo Trading API.
Response Fields
Name | Type | Possible Values | Description |
---|---|---|---|
base_currency | string | Currency Ticker Symbol | The ticker symbol of an available base currency. |
quote_currency | string | Currency Ticker Symbol | The ticker symbol of an available quote currency for the base currency. |
Client SDK for JS
zabo.trading.getSymbols()
Arguments
None
Server SDK for JS
Not Available
HTTP Request
GET BASE_URL/accounts/:account_id/trading-symbols
Path Parameters
None
Provider Support
Coinbase Pro and Binance.
Get Ticker Info
Get ticker information:
zabo.trading.getTickerInfo({
baseCurrency: 'ETH',
quoteCurrency: 'USD'
}).then(function(tickerInfo) {
console.log(tickerInfo)
/* tickerInfo is the response outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let tickerInfo = await zabo.trading.getTickerInfo({
baseCurrency: 'ETH',
quoteCurrency: 'USD'
})
} catch (error) {
console.log(error)
}
Returns the following response object:
{
"last_price": "1058.45",
"last_size": "5.0398",
"ask": "1298.09",
"ask_size": "1.03847",
"bid": "1057.99",
"bid_size": "3827.03847",
"volume": "493744.38324983",
"timestamp": 1597416299,
"request_id": "ee556fef-c83c-45a5-866c-ff30d8a60c4d"
}
This function returns the current market information available for the currency pair, at the provider, for the given account.
Response Fields
Name | Type | Possible Values | Description |
---|---|---|---|
last_price | string | Floating-Point Number as String | This is the last executed price for the given currency pair. |
last_size | string | Floating-Point Number as String | The size of the last executed transaction. |
ask | string | Floating-Point Number as String | The current best ask price for the given currency pair. |
ask_size | string | Floating-Point Number as String | The size of the best ask order. |
bid | string | Floating-Point Number as String | The current best bid price for the given currency pair. |
bid_size | string | Floating-Point Number as String | The size of the best bid order. |
volume | string | Floating-Point Number as String | The accumulated volume. |
timestamp | number | Timestamp | The timestamp of this snapshot. |
request_id | string | UUID | The ID of the Zabo request. |
Client SDK for JS
zabo.trading.getTickerInfo({baseCurrency, quoteCurrency})
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
baseCurrency | string | Required | The 'ticker' identifier of the base currency at the given account's provider. |
quoteCurrency | string | Required | The block number to retrieve. If left empty, the latest block we have available will be returned. |
Server SDK for JS
Not Available
HTTP Request
GET BASE_URL/accounts/:account_id/tickers/:ticker_pair
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ticker_pair | string | Required | The ticker pair being requested separated by a dash. e.g. "ETH-USD". NOTE: The ticker symbols must be the valid tickers at the provider for the given account. These can be found by calling for the trading pairs. See the 'Get Trading Symbols' section above. |
Provider Support
Coinbase Pro and Binance.
Place New Order
Place new order:
zabo.trading.createOrder({
baseCurrency: 'ETH',
quoteCurrency: 'USD',
buyOrSell: 'buy',
priceLimit: '',
baseAmount: '0.056',
quoteAmount: '',
timeInForce: 'GTC',
ttl: 0
}).then(function(orderResponse) {
console.log(orderResponse)
/* tickerInfo is the response outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let orderResponse = await zabo.trading.createOrder({
baseCurrency: 'ETH',
quoteCurrency: 'USD',
buyOrSell: 'buy',
priceLimit: '',
baseAmount: '0.056',
quoteAmount: '',
timeInForce: 'GTC',
ttl: 0
})
} catch (error) {
console.log(error)
}
Returns the following response object:
{
"id": "ee556fef-c83c-45a5-866c-ff30d8a60c4d",
"base_currency": "ETH",
"quote_currency": "USD",
"buy_or_sell": "buy",
"type": "market",
"provide_liquidity_only": false,
"created_at": 1600888769951,
"status": "NEW",
"request_id": "6427399c-9f5e-4f04-9db3-cd6047d911f2"
}
This function creates a new trade order.
Full Object Description
Client SDK for JS
zabo.trading.createOrder({baseCurrency, quoteCurrency, ...See Arguments Below})
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
baseCurrency | string | Required | The 'ticker' identifier of the base currency at the given account's provider. e.g. BTC. This is the currency that will be bought, if buyOrSell is buy , or the currency sold, if buyOrSell is sell . |
baseAmount | string | Optional* | The amount of baseCurrency to buy or sell. *NOTE: This parameter is required if quoteAmount is not provided. It is also required if this is a priceLimit is provided. See the Ordering Process Explained section for more information. |
quoteCurrency | string | Required | The 'ticker' identifier of the quote currency at the given account's provider. e.g. USD. This is the currency that will be used to buy baseCurrency , if buyOrSell is buy , or the currency received, if buyOrSell is sell . |
quoteAmount | string | Optional* | The amount of quoteCurrency to use or receive. *NOTE: This parameter should only be provided if baseAmount AND priceLimit are not provided. It is only relevant for market orders that have not defined a baseAmount . See the Ordering Process Explained section for more information. |
buyOrSell | string | Required | Should be one of buy or sell . |
priceLimit | string | Optional | The highest price in terms of quoteCurrency to pay for baseCurrency , if placing a buy order. e.g. The highest amount of USD to buy 1 BTC. OR the lowest price in terms of quoteCurrency to sell baseCurrency . e.g. The lowest amount of USD to sell 1 BTC. If no priceLimit is provided, then the current "market rate" will be used. See the Ordering Process Explained section for more information. |
timeInForce | string | Optional* | Should be one of GTC , GTT , IOC , or FOK . This should only be provided if priceLimit is also provided. See the Ordering Process Explained section for more information. |
ttl | number | Optional* | The "time to live" if timeInForce is GTT . SHOULD BE EXPRESSED IN MILLISECONDS |
provideLiquidityOnly | boolean | Optional | Should be set to true if the order should not "take" from the market order book. This defaults to false . See the Ordering Process Explained section for more information. |
Server SDK for JS
Not Available
HTTP Request
POST BASE_URL/accounts/:account_id/orders
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
base_currency | string | Required | The 'ticker' identifier of the base currency at the given account's provider. e.g. BTC. This is the currency that will be bought, if buyOrSell is buy , or the currency sold, if buyOrSell is sell . |
base_amount | string | Optional* | The amount of base_currency to buy or sell. *NOTE: This parameter is required if quote_amount is not provided. It is also required if this is a price_limit is provided. See the Ordering Process Explained section for more information. |
quote_currency | string | Required | The 'ticker' identifier of the quote currency at the given account's provider. e.g. USD. This is the currency that will be used to buy base_currency , if buy_or_sell is buy , or the currency received, if buy_or_sell is sell . |
quote_amount | string | Optional* | The amount of quote_currency to use or receive. *NOTE: This parameter should only be provided if base_amount AND price_limit are not provided. It is only relevant for market orders that have not defined a base_amount . See the Ordering Process Explained section for more information. |
buy_or_sell | string | Required | Should be one of buy or sell . |
price_limit | string | Optional | The highest price in terms of quote_currency to pay for base_currency , if placing a buy order. e.g. The highest amount of USD to buy 1 BTC. OR the lowest price in terms of quote_currency to sell base_currency . e.g. The lowest amount of USD to sell 1 BTC. If no price_limit is provided, then the current "market rate" will be used. See the Ordering Process Explained section for more information. |
time_in_force | string | Optional* | Should be one of GTC , GTT , IOC , or FOK . This should only be provided if price_limit is also provided. See the Ordering Process Explained section for more information. |
ttl | number | Optional* | The "time to live" if time_in_force is GTT . SHOULD BE EXPRESSED IN MILLISECONDS |
provide_liquidity_only | boolean | Optional | Should be set to true if the order should not "take" from the market order book. This defaults to false . See the Ordering Process Explained section for more information. |
Provider Support
Coinbase Pro and Binance.
Get orders
Get your orders:
zabo.trading.getOrders().then(function(orderList) {
console.log(orderList)
/* orderList is the response outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let orderList = await zabo.trading.createOrder()
} catch (error) {
console.log(error)
}
Returns the
order
list:
{
"data": [
{
"id":"4545edd1-c9bb-4a50-9304-dd737f2c37c1",
"base_currency": "ETH",
"quote_currency":"USD",
"base_amount":"0.02000000",
"buy_or_sell": "buy",
"quote_amount": "",
"price": "1000.00000000",
"time_in_force": "GTC",
"ttl": 0,
"provide_liquidity_only": false,
"type":"limit",
"status":"NEW",
"created_at":1600967765356,
"done_at":0,
"done_reason":"",
"filled_size":"0.00000000",
"fill_fees":"0.0000000000000000",
"settled":false
},
...
],
"request_id": "9fa5155e-0189-40b0-a9be-718705a842f3"
}
This function returns all active orders for the given account.
Full Object Description
Client SDK for JS
zabo.trading.getOrders()
Arguments
None
Server SDK for JS
Not Available
HTTP Request
GET BASE_URL/accounts/:account_id/orders
Provider Support
Coinbase Pro and Binance
Get an order
Get a specific order:
zabo.trading.getOrder({orderId}).then(function(order) {
console.log(order)
/* order is the response outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let order = await zabo.trading.getOrder({orderId})
} catch (error) {
console.log(error)
}
Returns the
order
list:
{
"id":"4545edd1-c9bb-4a50-9304-dd737f2c37c1",
"base_currency": "ETH",
"quote_currency":"USD",
"base_amount":"0.02000000",
"buy_or_sell": "buy",
"quote_amount": "",
"price": "1000.00000000",
"time_in_force": "GTC",
"ttl": 0,
"provide_liquidity_only": false,
"type":"limit",
"status":"NEW",
"created_at":1600967765356,
"done_at":0,
"done_reason":"",
"filled_size":"0.00000000",
"fill_fees":"0.0000000000000000",
"settled":false,
"request_id": "9fa5155e-0189-40b0-a9be-718705a842f3"
}
This function returns the specific order for the given order id.
Full Object Description
Client SDK for JS
zabo.trading.getOrder({orderId})
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
orderId | string | Required | The id of the active order being queried. |
Server SDK for JS
Not Available
HTTP Request
GET BASE_URL/accounts/:account_id/orders/:order_id
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
order_id | string | Required | The id of the active order being queried. |
Provider Support
Coinbase Pro and Binance
Cancel all orders
Cancel all open orders:
zabo.trading.cancelOrders().then(function(cancelledResp) {
console.log(cancelledResp)
/* cancelledResp is the response outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let cancelledResp = await zabo.trading.cancelOrders()
} catch (error) {
console.log(error)
}
Returns the list of cancelled order id's:
{
"data": [
"4545edd1-c9bb-4a50-9304-dd737f2c37c1",
"b6cb15db-a6ee-4adf-8994-91a155195362",
...
],
"request_id": "9fa5155e-0189-40b0-a9be-718705a842f3"
}
This function cancels all open orders.
Response
List of order ids for all orders that were cancelled.
Client SDK for JS
zabo.trading.cancelOrders()
Arguments
None
Server SDK for JS
Not Available
HTTP Request
DELETE BASE_URL/accounts/:account_id/orders
Provider Support
Coinbase Pro and Binance
Cancel an order
Cancel a specific order:
zabo.trading.cancelOrder({orderId}).then(function(cancelledResp) {
console.log(cancelledResp)
/* cancelledResp is the response outlined below */
})
.catch(function(error) {
console.log(error)
/* See errors section for more information */
})
// ES6 async/await
try {
let cancelledResp = await zabo.trading.cancelOrder({orderId})
} catch (error) {
console.log(error)
}
Returns the list of cancelled order id's:
{
"data": ["4545edd1-c9bb-4a50-9304-dd737f2c37c1"],
"request_id": "9fa5155e-0189-40b0-a9be-718705a842f3"
}
This function cancels the order with the given order id.
Response
Returns a data list populated with the cancelled order id.
Client SDK for JS
zabo.trading.cancelOrder({orderId})
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
orderId | string | Required | The id of the active order being cancelled. |
Server SDK for JS
Not Available
HTTP Request
DELETE BASE_URL/accounts/:account_id/orders/:order_id
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
order_id | string | Required | The id of the active order being cancelled. |
Provider Support
Coinbase Pro and Binance
Order Object
{
"id":"4545edd1-c9bb-4a50-9304-dd737f2c37c1",
"base_currency": "ETH",
"quote_currency":"USD",
"base_amount":"0.02000000",
"buy_or_sell": "buy",
"quote_amount": "",
"price": "1000.00000000",
"time_in_force": "GTC",
"ttl": 0,
"provide_liquidity_only": false,
"type":"limit",
"status":"NEW",
"done_at":0,
"done_reason":"",
"filled_size":"0.00000000",
"fill_fees":"0.0000000000000000",
"settled":false,
"created_at":1600967765356,
"request_id": "9fa5155e-0189-40b0-a9be-718705a842f3"
}
Fields
Name | Type | Possible Values | Description |
---|---|---|---|
id | string | UUID | The ID of the order. |
base_currency | string | Currency Ticker | The 'ticker' identifier of the base currency at the given account's provider. e.g. BTC. This is the currency being bought, if buyOrSell is buy , or the currency being sold, if buyOrSell is sell . |
base_amount | string | Floating-Point Number as String | The amount of base_currency to buy or sell. *NOTE: This parameter should only be provided if quote_amount is not provided. |
quote_currency | string | Currency Ticker | The 'ticker' identifier of the quote currency at the given account's provider. e.g. USD. This is the currency that will be used to buy base_currency , if buy_or_sell is buy , or the currency received, if buy_or_sell is sell . |
quote_amount | string | Floating-Point Number as String | The amount of quote_currency to use or receive. *NOTE: This parameter should only be provided if base_amount AND price_limit are not provided. |
buy_or_sell | string | buy or sell | Determines whether the base_currency is being bought or sold. |
price_limit | string | Floating-Point Number as String | The highest price in terms of quote_currency to pay for base_currency , if placing a buy order. e.g. The highest amount of USD to buy 1 BTC. OR the lowest price in terms of quote_currency to sell base_currency . e.g. The lowest amount of USD to sell 1 BTC. Thus is only provided for order type limit . |
time_in_force | string | GTC , GTT , IOC , or FOK | The cancellation policy set for a limit type order. |
ttl | number | Integer | The "time to live" if time_in_force is GTT . SHOULD BE EXPRESSED IN MILLISECONDS |
provide_liquidity_only | boolean | true or false | Returns true if the order should not "take" from the market order book. |
type | string | market or limit | The order type. This value is "market" if the order is using the best available market price, or "limit" if the order is setting its own price. |
status | string | One of the Order Statuses | The status of the order |
done_at | number | Timestamp | The timestamp at which this order was given a done_reason |
done_reason | string | One of the Order Statuses | The reason the order is "done." |
filled_size | string | Floating-Point Number as String | The amount of base_currency filled for this order. |
fill_fees | string | Floating-Point Number as String | The fees paid in quote_currency amount. |
settled | boolean | true or false | Whether this order settled or not. |
created_at | number | Timestamp | Timestamp this order was created. |
request_id | string | UUID | The Zabo request ID. |
Order Statuses
List
Name | Value |
---|---|
New Order | NEW |
Filled Order | FILLED |
Cancelled Order | CANCELED |
Pending Cancellation | PENDING_CANCEL |
Rejected Order | REJECTED |
Partially Filled Order | PARTIALLY_FILLED |
Unknown | UNKNOWN |
Ordering Process Explained
Cryptocurrency trades in Zabo can be one of two major types; a market
order, or a limit
order. The simplest of these is the market
order.
Market Orders
Market orders are orders that simply buy an asset at the "market price," or sell an asset at the "market price." The "market price" is the price currently being offered by the provider's "order book." An order book is a list of all existing offers to buy or sell an asset. The market generally wants to buy assets at a low price, and sell assets at a high price. This means that all offers to sell an asset will be at a price higher than all offers to buy an asset.
Let's look at an example. When placing a buy
market
order for 1 BTC, the order will "execute" by finding the best price (the lowest sell price) to buy 1 BTC, and buy it. When placing a sell
market
order for 1 BTC, the order will "execute" by finding the best price (the highest buy price) to sell 1 BTC, and sell it. Therefore, to execute a buy
market
order, the exchange needs to know which asset to buy, which asset to use (or spend), and how much to buy or spend. Exchanges can take the order in terms of the amount to "buy", e.g. "I want to buy 1 Bitcoin", OR they will take the order in terms of the amount to "spend", e.g. "I want to spend $150 on Bitcoin". The terms used for these currencies and amounts is the "base currency" and "quote currency."
The base currency is the currency we are going to buy or sell, e.g. Bitcoin. The quote currency is the currency we will spend or receive as a result of the order execution, e.g. US Dollars. Remember that the exchange only needs to know how much Bitcoin (base amount) we want, OR how much US Dollars (quote amount) we want to spend. Therefore we only need to tell it one of these amounts. With all of that in mind, let's look at how we can place a market
order to buy
1 Bitcoin. The data payload sent to the POST /orders
endpoint would look like the following:
{
"base_currency": "BTC",
"quote_currency": "USD",
"buy_or_sell": "buy",
"base_amount": "1.00"
}
That's it! Because we defined the base_amount
as 1, this sends the request to buy 1 BTC, at the current market price, with US Dollars. If we wanted to only spend a certain amount of US Dollars, the payload would look like the following:
{
"base_currency": "BTC",
"quote_currency": "USD",
"buy_or_sell": "buy",
"quote_amount": "150.00"
}
In this case, we would spend $150 and receive the most Bitcoin the current market offers for that amount of US Dollars. It is also ok to set both "quote amount" AND "base amount." In this case, the lower of the two would be used as the cap in the buying process. If we set base_amount
to 1, and quote_amount
to 150 in the same request, then this means "I want to buy no more than 1 Bitcoin and spend no more than $150." But, what if we want to set our own price?
Limit Orders
Limit orders allow us to set our own price for a trade by setting our own "price limit." Remember the order book we discussed in the Market Orders section? A proper "limit order" essentially puts your offer on that order book for others to see. To accomplish this, the exchange needs more information than we provided in our market order request.
Let's say we want to buy
bitcoin, and only spend $10,500 per Bitcoin. First, we must let the exchange know we want to set a "price limit." If there is no price limit, then the exchange can only assume you want to buy or sell at the best market price. When we include a price limit, however, this turns our order into a Limit Order. In the example, we would set the price_limit
to 10500.00. If the market is only offering Bitcoin at $15,000, then how will the exchange know when we want to take our offer completely off the table? This is where our time_in_force
comes into play. We have several options, with "GTC" being the default option:
GTC
: Stands for Good 'Til Cancelled and will leave our offer on the books until we manually cancel it ourselves.GTT
: Good 'Til Time allows us to specify the amount of time this offer should stay open until it cancels automatically. When we set this policy, we also include thettl
, or Time to Live, which specifies, in milliseconds, how long this offer should stay open. e.g. "I want to make this offer for 1 hour and then, if nobody takes my offer, cancel it." NOTE: The offer can still be manually cancelled at any time.IOC
: Immediate or Cancel will actually keep the offer from going onto the order book. The order will either immediately execute in the market when it is received, or cancelled.FOK
: Fill or Kill requires that the entire offer be taken, rather than only partially "filled." Without this requirement, if you offered to buy 1 Bitcoin at $10,500, and a market participant wanted to offer only 0.25 Bitcoin at $10,500, then your order would take the 0.25 Bitcoin.
Putting all of this together, let's say we wanted to make an offer to sell our 1 Bitcoin for no less than $20,000, and we'll leave this offer open until we want to cancel it. The data payload sent to the POST /orders
endpoint would look like the following:
{
"base_currency": "BTC",
"quote_currency": "USD",
"buy_or_sell": "sell",
"base_amount": "1.00",
"price_limit": "20000.00"
"time_in_force": "GTC",
"provide_liquidity_only": true
}
There is one parameter in that dataset we have not discussed, the provide_liquidity_only
parameter. If this is set to true
, then we are telling the exchange that we do not want to "take" from existing offers on the book. We want to provide our own offer in the market. This tends to affect fees because "takers" will pay higher fees than those "making" offers. As one more example, let's say Ether was selling at $15,000 and we want to try and sell our 1 ETH for $16,000 for an hour. This would look like the following:
{
"base_currency": "ETH",
"quote_currency": "USD",
"buy_or_sell": "sell",
"base_amount": "16000.00",
"price_limit": "20000.00"
"time_in_force": "GTT",
"ttl": 3600000,
"provide_liquidity_only": true
}
Where 3600000
is one hour in milliseconds. Happy Trading!!
Bitcoin/Ethereum API (Beta)
On-chain Address:
Not available in the client SDK
Highly Deterministic Wallet:
Returns the following JSON object for Ethereum:
{
"data": [{
"token": {
"contract": {
"address": "0xtheTokenAddress"
},
"symbol": "ABC",
"name": "No Zabo Tokens",
"decimals": 18,
"total_supply": "100000000000000000000000000",
"is_erc20": true
},
"address": "0x62a6ebC0ac598819CCad368788F6d2357FaE0d9e",
"balance": "250000000"
}]
}
Returns the following JSON object for Bitcoin:
{
"data": 7598343714,
}
The Zabo API already supports connecting browsers, mobile, and hardware wallets, including Ledger and Trezor, through our standard connection process. In addition to this, we have opened up the ability to retrieve raw blockchain data directly. The following list provides the available interface to the Bitcoin and Ethereum blockchains. Let us know if you find this useful and we can continue iterating on it if so!
Get a Block
Not available in the client SDK
Returns the following Ethereum
block
object:
{
"number": 10658732,
"hash": "0xdcb7ad1f4beb3f13117a2a6e104cb0bf4b291f1d6c7c79395710370601fe4b2d",
"size": 39651,
"gas_limit": 12499929,
"gas_used": 12482105,
"transaction_count": 183,
"timestamp": 1597416299
}
Returns the following Bitcoin
block
object:
{
"number": 649479,
"hash": "00000000000000000005e3fc7e47241648321eb96be8dec90953f88054196713",
"size": 1305585,
"version": 549453824,
"nonce": "927ab970",
"transaction_count": 2492,
"timestamp": 1600768201
}
This function returns information regarding the requested block number. If the endpoint is called without a block number, then the latest block Zabo has will be returned. NOTE: Zabo lags the head of the blockchain by 10 blocks.
Response Fields
Name | Type | Possible Values | Description |
---|---|---|---|
number | number | Block Number | This is the block number of the information returned. |
hash | string | Hex String | The 32-byte hash of the block. |
size | number | Int | Size of the block. |
version | number | Int | Bitcoin Only Block version information. |
nonce | string | Hex String | Bitcoin Only The nonce used to generate this block |
gas_limit | number | Int | Ethereum Only The max gas that could have been used in this block. |
gas_used | number | Int | Ethereum Only The actual gas used in this block. |
transaction_count | number | Int | The number of transaction messages sent to this block. This does not include additional transactions executed as a result of sent messages. |
timestamp | number | Timestamp | The timestamp of this block. |
Client SDK for JS
Not Available
Server SDK for JS
zabo.blockchains.getBlock(blockchain, blockNumber)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | One of ethereum or bitcoin . |
blockNumber | number | Optional | The block number to retrieve. If left empty, the latest block we have available will be returned. |
HTTP Request
GET BASE_URL/blockchains/:blockchain/blocks/:block_number
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | One of either ethereum or bitcoin . |
block_number | number | Optional | A specific block number being requested. |
Get a Smart Contract [Ethereum Only]
Not available in the client SDK
Returns the following
contract
object:
{
"address": {
"hex":"0x34d0448A79F853d6E1f7ac117368C87BB7bEeA6B",
"nonce":1,
"name":"Uniswap YFKA/TOB Pool"
},
"bytecode": "608060405234801561001057600080fd5b506040516136863803...."
}
This function returns the address and bytecode for the contract at a given address. The address is required, and there must a smart contract deployed at the given address.
Response Fields
Name | Type | Possible Values | Description |
---|---|---|---|
address | object | Address Object | The address object of the given address. |
bytecode | string | Hex String | The raw bytecode deployed at the given address. |
Client SDK for JS
Not Available
Server SDK for JS
zabo.blockchains.getBlock(blockchain, blockNumber)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | Must be ethereum . |
address | string | Required | The address of the contract being requested. |
HTTP Request
GET BASE_URL/blockchains/:blockchain/contracts/:contract_address
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | Must be ethereum . |
contract_address | string | Required | The address of the contract being requested. |
Get Tokens [Definitely Not for Bitcoin]
Not available in the client SDK
Getting a list
Getting a token by name
Returns the following
token
list:
{
"list_cursor": {
"limit": 25,
"has_more": true,
"self_uri": "/blockchains/ethereum/tokens?cursor=Wrapped%20Bitcoin&limit=25",
"next_uri": "/blockchains/ethereum/tokens?cursor=Wrapped%20Ether&limit=25"
},
"data": [
...,
{
"contract": {
"address": {
"hex":"0x3d0d921a19796C3b68eC9dDe6e692BaA984d68BA",
"nonce":1,
"name":null
}
},
"ticker": "WETH",
"name": "Wrapped Ether",
"decimals": 18,
"total_supply": "3569209563897723306196065",
"is_erc20": true
}
]
}
This function returns a list of tokens on the Ethereum blockchain in general, or a specific token if the name is provided. Names are not unique so, if a name is provided in the path, a list is still returned for all tokens that share the same name. NOTE: The name is case-sensitive!
Response Fields
Name | Type | Possible Values | Description |
---|---|---|---|
contract | object | Contract Object | A contract object with the token's address populated. |
ticker | string | Token Symbol | The token's ticker symbol. |
name | string | Token Name | The token's name. |
decimals | number | Int | The decimal places this token uses to translate its lowest denomination to the standard denomination. |
total_supply | string | Number Characters | The string representation of the token's total supply. |
is_erc20 | boolean | true or false | Indicates whether or not this token is ERC-20 compliant. |
Client SDK for JS
Not Available
Server SDK for JS
zabo.blockchains.getTokens(blockchain, tokenName)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | Must be ethereum . |
tokenName | string | Optional | The name of the token being requested. |
HTTP Request
GET BASE_URL/blockchains/:blockchain/tokens/:token_name
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | Must be ethereum . |
token_name | string | Optional | The name of the requested token. |
Get Balances for Address or XPub
Not available in the client SDK
Returns the following JSON object for Ethereum:
{
"data": [{
"token": {
"contract": {
"address": "0xtheTokenAddress"
},
"symbol": "ABC",
"name": "No Zabo Tokens",
"decimals": 18,
"total_supply": "100000000000000000000000000",
"is_erc20": true
},
"address": "0x62a6ebC0ac598819CCad368788F6d2357FaE0d9e",
"balance": "250000000"
}]
}
Returns the following JSON object for Bitcoin:
{
"data": 7598343714,
}
This function returns a list of balances of the assets which the given address or extended public key holds. If the response is for a Bitcoin network request, then the data
response is simply the address', or xpub key's, balance in satoshis.
Response Fields
Name | Type | Possible Values | Description |
---|---|---|---|
token | object | Token Object | Ethereum Only The token related to the given balance. |
address | string | Ethereum Address | Ethereum Only The on-chain address that holds this balance. |
balance | string | Number Characters | Ethereum Only The string representation of the balance. |
Client SDK for JS
Not Available
Server SDK for JS
zabo.blockchains.getBalances(blockchain, address)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | One of either ethereum or bitcoin . |
address | string | Required | The address being requested. |
HTTP Request
GET BASE_URL/blockchains/:blockchain/addresses/:address_or_xpub_key/balances
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | One of either ethereum or bitcoin . |
token_or_xpub | string | Required | The on-chain address or xpub key being queried. NOTE: Zabo will traverse well known branches of the xpub address chain until it finds balances, if any exist. |
Get Transactions for Address or XPub
Not available in the client SDK
Returns the following for Bitcoin:
{
"list_cursor": {
"limit":25,
"has_more":false,
"self_uri":"/blockchains/bitcoin/addresses/167fDNxskA9mC6UTMRAeghhy9vPKKQCk2N/transactions",
"next_uri":""
},
"data": [
{
"hash":"be7553663726ff2c8d5437501a68a2674383abe740e3c8b8e474d0cabed0b569",
"block_number":649514,
"outputs": [
{
"node": {
"output_script":"OP_DUP OP_HASH160 ee561bffcca9112fbdf2c9956bbb9bca0225158e OP_EQUALVERIFY OP_CHECKSIG",
"output_script_type":"pubkeyhash",
"addresses": [
{
"address": {
"hex":"1NjCye6vPpL7XCjNsJ1qgsWsstQ1A9TAJV"
},
"index":0
}
],
"input_script": null,
"input_sequence": null,
"required_signatures": 1,
"output_value": 16157879
},
"output_transaction": {
"hash": "be7553663726ff2c8d5437501a68a2674383abe740e3c8b8e474d0cabed0b569",
"block_number": 649514,
"outputs": null,
"inputs": null,
"size": 669,
"lock_time": 0,
"is_coinbase": false
},
"output_index": 0,
"input_transaction": null,
"input_index": null
},
{
"node": {
"output_script": "OP_DUP OP_HASH160 381b060dfaab58b271a083221eeb6bd887828b81 OP_EQUALVERIFY OP_CHECKSIG",
"output_script_type": "pubkeyhash",
"addresses": [
{
"address": {
"hex": "167fDNxskA9mC6UTMRAeghhy9vPKKQCk2N"
},
"index": 0
}
],
"input_script": null,
"input_sequence": null,
"required_signatures": 1,
"output_value": 95000000
},
"output_transaction": {
"hash":"be7553663726ff2c8d5437501a68a2674383abe740e3c8b8e474d0cabed0b569",
"block_number": 649514,
"outputs": null,
"inputs": null,
"size": 669,
"lock_time": 0,
"is_coinbase": false
},
"output_index": 1,
"input_transaction": null,
"input_index": null
}
],
"inputs": [
{
"node": {
"output_script": "OP_DUP OP_HASH160 e80274f5d6d2a4f132e68e58b35b2864c7279def OP_EQUALVERIFY OP_CHECKSIG",
"output_script_type": "pubkeyhash",
"addresses": [
{
"address": {
"hex": "1N9kiDGBRfLUvrCXbAbrPo5aj3fyS8oFWm"
},
"index": 0
}
],
...
},
...
},
...
]
}
]
}
Returns the following for Ethereum:
{
"list_cursor": {
"limit": 25,
"has_more": false,
"self_uri": "/blockchains/bitcoin/addresses/167fDNxskA9mC6UTMRAeghhy9vPKKQCk2N/transactions",
"next_uri": ""
},
"data": [
{
"hash": "0x23170b29a16c3ed89a2d7514c2d6d0796e39a29184c52a0bb5aed6b404b78a83",
"block_number": 10609471,
"from_address": {
"hex": "0x4ae694344e7e4e5820c62aa9816b7aa61210eaba",
"nonce": 4
},
"to_address": {
"hex": "0xe41d2489571d322189246dafa5ebde1f4699f498",
"nonce": 1
},
"value": "0",
"gas": 77012,
"gas_price": "42000000000",
"gas_used": 23506,
"input": "0xa9059cbb0000000000000000000000006...",
"status": 1
},
...
]
}
This function returns a list of transactions executed by the given address or extended public key.
Response Fields
Name | Type | Possible Values | Description |
---|---|---|---|
hash | string | Hex String | The 32-byte hash for this transaction. |
block_number | number | Int | The block number this transaction was included in. |
from_address | object | Address Object | Ethereum Only An address object which includes the hex string representation of the address, and the nonce value that the address is currently on. |
to_address | object | Address Object | Ethereum Only An address object which includes the hex string representation of the address, and the nonce value that the address is currently on. |
value | string | Number Characters | Ethereum Only The string representation of the amount of Wei sent in this transaction |
gas | number | Int | Ethereum Only The amount of gas authorized for this transaction. |
gas_price | string | Ethereum Only Number Characters | The amount of Wei paid for each unit of gas. |
gas_used | number | Int | Ethereum Only The actual amount of gas used to execute this transaction. |
input | string | Hex String | Ethereum Only The input data sent to execute this transaction in the EVM. |
status | number | 1 , 0 , or null | Ethereum Only The status of this transaction. If it is a 1 , this transaction successfully executed. If it is a 0 , this transaction failed to make any state changes on the network. If it is null , then this transaction was executed at a time when status indications were not supported. |
outputs | array | List of UTXO Objects | Bitcoin Only The list of outputs being produced by this transaction |
inputs | array | List of UTXO Objects | Bitcoin Only The list of outputs being spent by this transaction |
Client SDK for JS
Not Available
Server SDK for JS
zabo.blockchains.getTransactions(blockchain, address)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | One of either ethereum or bitcoin . |
address | string | Required | The address being requested. |
HTTP Request
GET BASE_URL/blockchains/ethereum/addresses/:address_or_xpub_key/transactions
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | One of either ethereum or bitcoin . |
address_or_xpub | string | Required | The on-chain address or xpub key being queried. NOTE: Zabo will traverse well known branches of the xpub address chain until it finds transactions, if any exist. |
Get Transaction by Hash
Not available in the client SDK
See the 'Get Transactions for Address or XPub' section for response examples.
This function returns a single transaction object related to the hash included in the request.
Response Fields
See 'Get Transactions for Address or XPub' section for response information.
Client SDK for JS
Not Available
Server SDK for JS
zabo.blockchains.getTransaction(blockchain, hash)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | One of either ethereum or bitcoin . |
hash | string | Required | The hash of the transaction being requested. |
HTTP Request
GET BASE_URL/blockchains/:blockchain/transactions/:transaction_hash
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | One of either ethereum or bitcoin . |
transaction_hash | string | Required | The hash of the transaction being queried. |
Get Token Transfers for Address or XPub [Ethereum Only]
Not available in the client SDK
Returns the following:
{
"list_cursor": {
"limit": 25,
"has_more": true,
"self_uri": "/blockchains/ethereum/addresses/0x4ae694344e7e4e5820c62aa9816b7aa61210eaba/token-transfers",
"next_uri": "/blockchains/ethereum/addresses/0x4ae694344e7e4e5820c62aa9816b7aa61210eaba/token-transfers?cursor=0x23170b29a16c3ed89a2d7514c2d6d0796e39a29184c52a0bb5aed6b404b78a83&limit=25"
},
"data": [
{
"transaction": {
"hash": "0x23170b29a16c3ed89a2d7514c2d6d0796e39a29184c52a0bb5aed6b404b78a83",
"block_number": 10609471,
"from_address": {
"hex": "0x4ae694344e7e4e5820c62aa9816b7aa61210eaba",
"nonce": 4
},
"to_address": {
"hex": "0xe41d2489571d322189246dafa5ebde1f4699f498",
"nonce": 1
},
"value": "0",
"gas": 77012,
"gas_price": "42000000000",
"gas_used": 23506,
"input": "0xa9059cbb0000000000000000000000006...",
"status": 1
},
"token": {
"contract": {
"address": "0xtheTokenAddress"
},
"symbol": "ABC",
"name": "No Zabo Tokens",
"decimals": 18,
"total_supply": "100000000000000000000000000",
"is_erc20": true
},
"from_address": {
"hex": "0x4ae694344e7e4e5820c62aa9816b7aa61210eaba",
"nonce": 4
},
"to_address": {
"hex": "0xe41d2489571d322189246dafa5ebde1f4699f498",
"nonce": 1
},
"value": "12823000000000000000000"
},
...
]
}
This function returns a list of token transfers directly involving the given address or extended public key.
Response Fields
Name | Type | Possible Values | Description |
---|---|---|---|
transaction | object | Transaction Object | The raw transaction object which initiated this transfer. |
token | object | Token Object | The token object involved with this token transfer |
from_address | object | Address Object | The address sending the token. |
to_address | object | Address Object | The address receiving the token. |
value | string | Number Characters | The string representation of the amount of the token being transferred. |
Client SDK for JS
Not Available
Server SDK for JS
zabo.blockchains.getTokenTransfers(blockchain, address)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | One of either ethereum or bitcoin . |
address | string | Required | The address being requested. |
HTTP Request
GET BASE_URL/blockchains/:blockchain/addresses/:address_or_xpub_key/token-transfers
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | Must be ethereum . |
address_or_xpub | string | Required | The on-chain address or xpub key being queried. NOTE: Zabo will traverse well known branches of the xpub address chain until it finds token transfers, if any exist. |
Get a Token Transfer by Hash [Ethereum Only]
Not available in the client SDK
Returns the following:
{
"data": [
{
"transaction": {
"hash": "0x23170b29a16c3ed89a2d7514c2d6d0796e39a29184c52a0bb5aed6b404b78a83",
"block_number": 10609471,
"from_address": {
"hex": "0x4ae694344e7e4e5820c62aa9816b7aa61210eaba",
"nonce": 4
},
"to_address": {
"hex": "0xe41d2489571d322189246dafa5ebde1f4699f498",
"nonce": 1
},
"value": "0",
"gas": 77012,
"gas_price": "42000000000",
"gas_used": 23506,
"input": "0xa9059cbb0000000000000000000000006...",
"status": 1
},
"token": {
"contract": {
"address": "0xtheTokenAddress"
},
"symbol": "ABC",
"name": "No Zabo Tokens",
"decimals": 18,
"total_supply": "100000000000000000000000000",
"is_erc20": true
},
"from_address": {
"hex": "0x4ae694344e7e4e5820c62aa9816b7aa61210eaba",
"nonce": 4
},
"to_address": {
"hex": "0xe41d2489571d322189246dafa5ebde1f4699f498",
"nonce": 1
},
"value": "12823000000000000000000"
}
]
}
This function returns the token transfers which executed as a result of the given transaction hash.
Response Fields
Name | Type | Possible Values | Description |
---|---|---|---|
transaction | object | Transaction Object | The raw transaction object which initiated this transfer. |
token | object | Token Object | |
from_address | object | Address Object | The address sending the token. |
to_address | object | Address Object | The address receiving the token. |
value | string | Number Characters | The string representation of the amount of the token being transferred. |
Client SDK for JS
Not Available
Server SDK for JS
zabo.blockchains.getTokenTransfer(blockchain, hash)
Arguments
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | Must be ethereum . |
hash | string | Required | The hash of the transaction being requested. |
HTTP Request
GET BASE_URL/blockchains/:blockchain/token-transfers/:transaction_hash
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
blockchain | string | Required | Must be ethereum . |
transaction_hash | string | Required | The hash of the transaction which initiated the token transfers. |
Zabo Terminology
The following is a description of several terms you may encounter when exploring both our API and the cryptocurrency ecosystem as a whole.
Account Terms
Cryptocurrency users generally hold their cryptocurrency in one of two types of accounts: "Exchange Account" and "Self-Custody Wallet".
Exchange Account
Exchange accounts are those held by a cryptocurrency exchange provider, such as Coinbase or Binance. Another term used for these types of accounts are 'Custodial Wallets'. They are labeled custodial wallets because the exchange provider maintains 'custody' or control of the secret keys which access the underlying cryptocurrency. The provider creates accounts for their users and the provider maintains its own accounting ledger for cryptocurrency balances. Users access their accounts through a standard login method and control their currency through the exchange provider's software.
Self Custody Wallet
A self-custody wallet is a setup where the user maintains direct control of the secret keys which access their cryptocurrency. In contrast with Exchange Accounts, no third party has access to these keys, and users access their cryptocurrency with software that accesses the underlying blockchain network directly. Users generally store their secret keys in an encrypted format which can only be unlocked with a password. Connections made with these providers do not access these private keys, but rather, ask for public key information only.
Zabo Account
A Zabo Account is created when a user connects either an Exchange Account, or Self-Custody Wallet to your application through the Zabo API. The underlying type of account the user connects makes no difference to your application. Zabo produces an Account object with the same data structure no matter what. The previous explanations are meant to provide a general understanding of cryptocurrency accounts at a high level, however, your project only needs to worry about the Zabo Account object.
Currency Terms
There two types of currencies referred to when discussing cryptocurrency systems: "Cryptocurrency" and "Fiat Currency".
Cryptocurrency
Cryptocurrencies are those currencies which "live on" blockchain networks. They represent an ownership of value that is cryptographically secured by the network that created it. For instance, the Bitcoin network created Bitcoin, represented by the "BTC" symbol, and maintains the accounting ledger for this currency. Likewise, the Ethereum network created Ether, represented by the "ETH" symbol, and maintains the accounting ledger for the Ether currency.
Cryptocurrency Types
Different types of ledger technology are used within cryptocurrency systems. The ones you may encounter in the Zabo API are listed in the Asset Type List. NOTE: The details of how these systems work are outside of this document's scope, however, if your application needs to use this information, the value
will be included with currency objects.
Decimals
Another unique property for cryptocurrency is the way it is denominated. While most of our everyday currency is denominated down to 1/100th of the primary currency, such as a "cent", cryptocurrency breaks down to values much lower than that. Additionally, these denominations are not standardized across cryptocurrencies. For example, the lowest denomination for Bitcoin is "Satoshis", which is 1/100000000th (1/10^8) of a Bitcoin, or 8 decimal places. Ethereum breaks down to units of "Wei" which are 1/10^18 of an Ether, or 18 decimal places (1 Ether = 1000000000000000000 Wei). Your project may or may not care about the lowest denomination of any given currency, however, this information is included in the decimals
field for currency objects. The value for this field represents how many decimals places the primary currency represents from the lowest denomination.
Fiat Currency
Fiat currencies are those currencies we tend to use every day such as US Dollars or Euros. They are generally created by state governments and labeled as "fiat" because they are not backed by a physical commodity. These currencies are labeled as fiat
in the cryptocurrency ecosystem to help us differentiate between a currency that natively resides on a blockchain network, and one that does not. Whenever Zabo presents a currency object for a fiat currency, such as "USD", the type
will be fiat
.