# API Guide

HollaEx APIs allow programmatic access to all available features in the exchange and can automate different use cases. For example, an exchange operator can create users, generate wallets for the user and listen to incoming and outgoing transactions in real-time. As an exchange end user also you can use the APIs to automate your trades, transactions, and other activities with APIs.

HollaEx APIs are divided into **admin** and **user** APIs. Admin APIs are only accessible to the exchange operator while user APIs are publicly available to all exchange users using HollaEx-based exchange.

{% hint style="info" %}
To quickly test your exchange APIs you should place your exchange API URL followed by /v2/health at the end of the URL. e.g. <https://api.hollaex.com/v2/health>
{% endhint %}

## Admin

Admin APIs give a huge amount of possible ways to interact with the exchange, creating users, making deposits and withdrawals, and viewing exchange-wide information. This functionality and access to information are of course protected behind the API keys.&#x20;

### Creating Admin API Keys

{% hint style="info" %}
To securely generate your keys, the Admin account must have 2FA set up in his exchange.
{% endhint %}

Before you start take security precautions and be careful since the admin keys are quite sensitive and should be kept securely.

{% hint style="info" %}
Admin API Keys should not be kept securely not shared publicly. These keys should never bed used in client-side applications like website front end or in mobile apps.
{% endhint %}

{% hint style="info" %}
Apply proper whitelist and scope for the keys for the best security practices and revoke these keys periodically.
{% endhint %}

By default, you won't have any keys for the exchange. To resolve this and add your first head to the *Operator Controls* of your exchange, *General* from the sidebar, and then the *Security* tab.

<figure><img src="proxy.php?url=https://3965312054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MP899VqAdyGFgLTy9SY%2Fuploads%2FevaH8dW5TdlOstx11sER%2Fimage.png?alt=media&#x26;token=0818dc22-3f71-4f41-a303-b1d091845ac1" alt=""><figcaption></figcaption></figure>

Scroll to the bottom to find the API Keys section, which if this is your first time coming to it, will be empty, and hit the *Generate API Key* link.

This will open a menu, where a few options will be offered:

1. **Name**: The name of the Key.
2. **IPs**: Here create a list of the white-listed IP addresses that will be associated with the key. These addresses will be the only IPs that the key will be useable.
3. **Key Type**: It is selected by default as admin. You can just proceed next.
4. **Confirmation**: Enter a code sent to the Admin email, as well as the Admin's OTP code to finalize the setup.

With these steps complete, the key will be generated like in the image below:

{% hint style="warning" %}
**Take note of the secret key now**, as it will become invisible forever on page refresh.
{% endhint %}

<figure><img src="proxy.php?url=https://3965312054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MP899VqAdyGFgLTy9SY%2Fuploads%2F1gy23DEeVTeCeSStbxWu%2Fimage.png?alt=media&#x26;token=dbf22f7c-a3cd-485d-b80c-9496dc912e4e" alt=""><figcaption></figcaption></figure>

Now there are a few options to define how far, and what, this particular key can access. They are fairly self-explanatory but some settings do enable a bit more than the name would suggest:

* **Read access**: Refers to **getting** information from the exchange such as user wallet balances etc.
* **Write access**: Refers to **changing the state** of the exchange, such as withdrawals, editing user info, etc.&#x20;

In addition, more white-listed IP addresses can be added if required.

{% hint style="info" %}
Bear in mind that changing things programmatically with the write API can be very risky if improperly set up, so care must be taken.
{% endhint %}

### Using an Admin Key

Trying out some sample scripts will help check our key is doing what we expect, as well as see a brief glimpse of what is possible with the API library.

{% hint style="info" %}
These examples are written in nodejs and is using the [hollaex-node-lib](https://www.npmjs.com/package/hollaex-node-lib). You can check [other resources](#resources) for different programming languages at the bottom of this page.
{% endhint %}

Start by creating a folder called `node-lib-hollaex,` or whatever name you fancy. It doesn't matter where this folder is.&#x20;

After creating the folder, enter this new folder in the terminal with `cd <FOLDER-NAME>` and install the npm dependencies and the HollaEx node library, with the following command:

```
npm install hollaex-node-lib
```

Now, create a Javascript file, reader.js, and in either your IDE or text editor, copy the following code into it:

<details>

<summary>reader.js code</summary>

```javascript
const hollaex = require("hollaex-node-lib");

const client = new hollaex({
  apiURL: "<YOUR_EXCHANGES_URL>",
  apiKey: "<YOUR_API_KEY>",
  apiSecret: "<YOUR_API_KEY_SECRET>",
});

const app = async () => {
  try {
    const user = await client.getExchangeUsers({ limit: 10 });
    console.log(user);
  } catch (err) {
    console.log(err.message);
  }
};

app();
```

</details>

Make sure you replace `<YOUR_EXCHANGES_URL>` with  your exchange api url as well `<YOUR_API_KEY>` and `<YOUR_API_KEY_SECRET>` with your api key and secret in the file.

Save up that file, and then  run it, in the terminal with:

```
node reader.js
```

Of course, the output will vary dependent on the users on your exchange, but should look generally as below:

<details>

<summary>Output of reader.js (condensed)</summary>

```
{
  count: 8,
  data: [
    {
      id: 9,
      email: 'tester@gmail.com',
      full_name: '',
      gender: false,
      nationality: '',
      dob: null,
      phone_number: '',
      address: [Object],
      id_data: [Object],
      bank_account: [],
      crypto_wallet: {},
      verification_level: 1,
      email_verified: true,
      otp_enabled: false,
      activated: true,
      note: '',
      username: 'tech',
      affiliation_code: '8DRYJG',
      settings: [Object],
      flagged: false,
      affiliation_rate: 0,
      network_id: 400977,
      discount: 0,
      meta: {},
      created_at: '2023-04-15T08:03:15.981Z',
      updated_at: '2023-04-15T08:03:33.679Z'
    },
    {
      ...
    },
  ...
```

</details>

Can see that this simple script has returned all the users, as objects, on the exchange that the key is for.&#x20;

This information should of course only be available to view as the Admin. Fortunately, the above was set up for Admin purposes by an Admin. Moving on to the next section we will see how a user can do similar tasks but is restricted in the scope of what they can carry out.

## User

These API keys allow access to the user's account. Users can get their account information like balances, open orders, trade history, etc. Users can also make actions such as creating or canceling an order or making a withdrawal through these keys.

### Creating User API Keys

The process for a user to create their own key is a little different from what is described above for the Admin. To test out how your users could feasibly programmatically interact with their account let's create a 'dummy' user for the sake of testing.

After logging in with this dummy user, head to the sidebar -> Security -> API Key.&#x20;

{% hint style="info" %}
As this is a dummy account, 2FA won't be set up so do this now, so that the API key can be generated.&#x20;
{% endhint %}

Click *Generate Key*, give the key a name, and then enter the security codes when asked. After this, the key will be ready. **Again take note of the secret now, as it will disappear on refresh.**

<figure><img src="proxy.php?url=https://3965312054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MP899VqAdyGFgLTy9SY%2Fuploads%2FY3RaivXiluSTjqGFRbLI%2Fimage.png?alt=media&#x26;token=90a7762e-22cf-404e-9711-ab5f71690503" alt=""><figcaption></figcaption></figure>

Set it so that we can perform Reading and Trading on it. You will notice that the key looks somewhat similar to the Admin version but with the IP access having the addition of any IP address being able to work with it.

### Using a User Key with Admin Functions

If we took our key information and replaced the key details of the reader.js script, lets inspect what happens:

<details>

<summary>user-reader.js code</summary>

```javascript
const hollaex = require("hollaex-node-lib");

const client = new hollaex({
  apiURL: "<YOUR_EXCHANGES_URL>",
  apiKey: "<USER_API_KEY>",
  apiSecret: "<USER_API_KEY_SECRET>",
});

const app = async () => {
  try {
    const user = await client.getExchangeUsers({ limit: 10 });
    console.log(user);
  } catch (err) {
    console.log(err.message);
  }
};

app();
```

</details>

Running this script like before will let print the error:&#x20;

```
403 - {"message":"Access denied: User is not authorized to access this endpoint"}
```

Exactly what we hope to see, the Admin key showed us the list of user, but the User's key was blocked from seeing the same list.

### Using the User Key

Let's try a quick script a user could actually use.

<details>

<summary>user-reader.js code</summary>

```javascript
const hollaex = require("hollaex-node-lib");

const client = new hollaex({
  apiURL: "<YOUR_EXCHANGES_URL>",
  apiKey: "<USER_API_KEY>",
  apiSecret: "<USER_API_KEY_SECRET>",
});

const app = async () => {
  try {
    const balance = await balance.getBalance();
    console.log(user);
  } catch (err) {
    console.log(err.message);
  }
};

app();
```

</details>

As expected, this retrieves that user's balance and displays it (as this is a dummy account, sadly, nothing too exciting to see in the output!):

<details>

<summary>user-reader.js code - Output</summary>

```javascript
{
  user_id: 10,
  xrp_balance: 0,
  xrp_available: 0,
  usdt_balance: 0,
  usdt_available: 0,
  eth_balance: 0,
  eth_available: 0,
  btc_balance: 0,
  btc_available: 0,
  xht_balance: 0,
  xht_available: 0,
  bnb_balance: 0,
  bnb_available: 0,
  patx_balance: 0,
  patx_available: 0,
  jin_balance: 0,
  jin_available: 0,
  xmr_balance: 0,
  xmr_available: 0
}
```

</details>

These are just examples and there are plenty of other functions that can be used in the library.

\---

## Websocket

Websockets are used to stream real-time data and notifications for different events such as trading, deposits, and withdrawals to the users, and exchange admin.

Using the client created in the previous examples with `hollaex-node-lib` you can create a websocket like this to listen to the orderbook updates.

```javascript
const hollaex = require("hollaex-node-lib");

const client = new hollaex({
  apiURL: "<YOUR_EXCHANGES_URL>/api",
  wsURL: "<YOUR_EXCHANGES_URL>/stream",
  apiKey: "<USER_API_KEY>",
  apiSecret: "<USER_API_KEY_SECRET>",
});

client.connect(['orderbook', 'trade']);

client.ws.on('message', (data) => {
	data = JSON.parse(data);
	console.log(data);
});

```

{% hint style="warning" %}
Note that for WebSocket scripts, the hollaex object must have one additional value, wsURL. This is simply the URL of the exchange with *'/stream'* added to the end.
{% endhint %}

You can subscribe and listen to the following events in websocket:

* orderbook: exchange orderbooks (Public)
* trade: Exchange trades (Public)
* order: User real-time orders information (Private)
* usertrade: User real-time trades (Private)
* wallet: User wallet balance update (Private)
* deposit: User wallet deposit (Private)
* withdrawal: User wallet withdrawal (Private)
* admin: Exchange admin notifications for deposit and withdrawals of all users (Private for only admin)

## Resources

The latest API Documentation can be found in the link below:

{% embed url="<https://apidocs.hollaex.com/#introduction>" %}

Nodejs developers:

{% embed url="<https://www.npmjs.com/package/hollaex-node-lib>" %}

Python developers:

{% embed url="<https://github.com/hollaex/hollaex-py-lib>" %}

Alternatively HollaEx APIs and websocket is supported on **CCXT** which is a very popular library used for algorithmic trading

{% embed url="<https://github.com/ccxt/ccxt>" %}