๐Ÿ”ฎVirtual Accounts

This documentation provides details on the API endpoints available for Whirlprivacy.io, focusing on virtual accounts operations.

POST /virtual/virtual-account - Create Batch Virtual Accounts

Description: Creates multiple virtual accounts with provided labels. Each label must be unique and not exceed the maximum number of accounts allowed per user.

Parameters:

ParameterTypeDescription

labels

array of strings

List of labels for the new virtual accounts.

Response:

{
  "error": [],
  "result": {
    "uuids": ["uuid1", "uuid2"]
  }
}

Error Handling:

Error CodeDescription

E_INVALID_PARAMS

The labels array is not provided or is not valid.

E_INVALID_LABEL

One or more labels are invalid according to the validation rules.

E_MAX_VIRTUAL_ACCOUNTS

The number of accounts exceeds the limit allowed.

E_CREATING_VIRTUAL_ACCOUNT

An error occurred during the creation of accounts, possibly due to duplicate labels.

Example Code:

const fetch = require('node-fetch');

const BASE_URL = 'https://api.whirlprivacy.io/';
const API_KEY = 'your_api_token';

const createVirtualAccounts = async (labels) => {
  try {
    const response = await fetch(`${BASE_URL}virtual/virtual-account`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
      },
      body: JSON.stringify({ labels })
    });
    const data = await response.json();

    console.log(data.result);
  } catch (error) {
    console.error('Error creating virtual accounts:', error);
  }
};

createVirtualAccounts(['label1', 'label2']);

POST /virtual/virtual-account/unnamed - Create Unnamed Virtual Accounts

Description: Allows the creation of a specific number of unnamed virtual accounts, limited by the maximum allowed accounts configuration.

Parameters:

ParameterTypeDescription

amount

integer

The number of unnamed accounts to create.

Response:

{
  "error": [],
  "result": {
    "uuids": ["uuid1", "uuid2", "uuid3"]
  }
}

Error Handling:

Error CodeDescription

E_INVALID_PARAMS

The amount is not provided or is not a valid integer.

E_MAX_VIRTUAL_ACCOUNTS

The number of accounts exceeds the limit allowed.

E_CREATING_VIRTUAL_ACCOUNT

An error occurred during the account creation process.

Example Code:

const fetch = require('node-fetch');

const BASE_URL = 'https://api.whirlprivacy.io/';
const API_KEY = 'your_api_token';

const createUnnamedAccounts = async (amount) => {
  try {
    const response = await fetch(`${BASE_URL}virtual/virtual-account/unnamed`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
      },
      body: JSON.stringify({ amount })
    });
    const data = await response.json();

    console.log(data.result);
  } catch (error) {
    console.error('Error creating unnamed virtual accounts:', error);
  }
};

createUnnamedAccounts(5);

PUT /virtual/virtual-account- Updates Virtual Account

Description:

Updates the label of an existing virtual account.

Parameters:

NameTypeDescription

uuid

string

The unique identifier of the virtual account. Required if label is not provided.

label

string

Current label of the virtual account. Required if uuid is not provided.

newValue

string

New label for the virtual account.

Response:

{
  "error": [],
  "result": "Updated"
}

Error Handling:

Error CodeMeaning

E_INVALID_PARAMS

Missing or invalid parameters provided.

E_UPDATING_VIRTUAL_ACCOUNT_LABEL

Error occurred while updating the virtual account label.

Example Code:

const fetch = require('node-fetch');

const BASE_URL = 'https://api.whirlprivacy.io/';
const API_KEY = 'your_api_token';

const updateVirtualAccountLabel = async (uuid, newValue) => {
  try {
    const response = await fetch(`${BASE_URL}virtual/virtual-account`, {
      method: 'PUT',
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        uuid: uuid,
        newValue: newValue
      })
    });
    const data = await response.json();

    console.log(data.result);
  } catch (error) {
    console.error('Error updating virtual account label:', error);
  }
};

// Replace 'uuid_here' and 'new_label_here' with actual data
updateVirtualAccountLabel('uuid_here', 'new_label_here');

PUT /virtual/virtual-account/disable - Disables Virtual Account

Description:

Disables an existing virtual account. Main accounts cannot be disabled.

Parameters:

NameTypeDescription

uuid

string

The unique identifier of the virtual account. Required if label is not provided.

label

string

The label of the virtual account to disable. Required if uuid is not provided.

Response:

{
  "error": [],
  "result": "Disabled"
}

Error Handling:

Error CodeMeaning

E_INVALID_PARAMS

Missing or invalid parameters provided.

E_DISABLING_VIRTUAL_ACCOUNT

Error occurred while disabling the account.

Example Code:

const fetch = require('node-fetch');

const BASE_URL = 'https://api.whirlprivacy.io/';
const API_KEY = 'your_api_token';

const disableVirtualAccount = async (uuid) => {
  try {
    const response = await fetch(`${BASE_URL}virtual/virtual-account/disable`, {
      method: 'PUT',
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ uuid: uuid })
    });
    const data = await response.json();

    console.log(data.result);
  } catch (error) {
    console.error('Error disabling virtual account:', error);
  }
};

// Replace 'uuid_here' with the actual UUID of the virtual account
disableVirtualAccount('uuid_here');

Here's a detailed Markdown documentation based on the provided code, suitable for copying and pasting into a GitBook. Each function's description aligns with the corresponding HTTP request, detailing expected parameters, behaviors, responses, error management, and sample code for execution.

## GET /virtual/virtual-accounts - List All User Virtual Accounts

This endpoint retrieves all virtual accounts associated with a logged-in user. It can filter accounts based on whether they are active and whether account balances should be included in the response.

### Parameters

| Parameter | Type      | Description                                    |
|-----------|-----------|------------------------------------------------|
| `active`  | `boolean` | Optional. Filter accounts that are currently active. Defaults to `true`. |
| `balances`| `boolean` | Optional. Include account balances in the response if `true`. |

### Successful Response

```json
{
  "error": [],
  "result": [
    {
      "id": "uuid",
      "label": "Account Label",
      "active": true,
      "balance": 100
    }
  ]
}

Error Handling

Error CodeDescription

E_INVALID_PARAMS

Parameters provided are invalid.

Example Code

const fetch = require('node-fetch');
const BASE_URL = 'https://api.whirlprivacy.io/';
const API_KEY = 'your_api_token';

const getUserVirtualAccounts = async () => {
  try {
    const response = await fetch(`${BASE_URL}virtual/virtual-accounts?active=true&balances=true`, {
      headers: {
        'X-API-Key': API_KEY
      }
    });
    const data = await response.json();

    console.log(data.result);
  } catch (error) {
    console.error('Error retrieving virtual accounts:', error);
  }
};

getUserVirtualAccounts();

GET /virtual/virtual-account/count - Count User Virtual Accounts

This endpoint counts the virtual accounts associated with a logged-in user.

Parameters

None.

Successful Response

{
  "error": [],
  "result": {
    "count": 5
  }
}

Error Handling

Error CodeDescription

E_INVALID_PARAMS

Parameters provided are invalid.

Example Code

const fetch = require('node-fetch');
const BASE_URL = 'https://api.whirlprivacy.io/';
const API_KEY = 'your_api_token';

const countUserVirtualAccounts = async () => {
  try {
    const response = await fetch(`${BASE_URL}virtual/virtual-account/count`, {
      headers: {
        'X-API-Key': API_KEY
      }
    });
    const data = await response.json();

    console.log(data.result);
  } catch (error) {
    console.error('Error counting virtual accounts:', error);
  }
};

countUserVirtualAccounts();

GET /virtual/virtual-account - Get Specific Virtual Account

Description: This endpoint retrieves a specific virtual account by either label or UUID for a logged-in user.

Parameters:

ParameterTypeDescription

label

string

Optional. The label of the virtual account.

uuid

string

Optional. The UUID of the virtual account.

Response:

{
  "error": [],
  "result": {
    "id": "uuid",
    "label": "Account Label",
    "active": true
  }
}

Error Handling:

Error CodeDescription

E_INVALID_PARAMS

Parameters provided are invalid.

E_VIRTUAL_ACCOUNT_NOT_FOUND

The requested virtual account could not be found.

Example Code:

const fetch = require('node-fetch');
const BASE_URL = 'https://api.whirlprivacy.io/';
const API_KEY = 'your_api_token';

const getSpecificVirtualAccount = async (labelOrUuid) => {
  try {
    const response = await fetch(`${BASE_URL}virtual/virtual-account?label=${encodeURIComponent(labelOrUuid)}`, {
      headers: {
        'X-API-Key': API_KEY
      }
    });
    const data = await response.json();

    console.log(data.result);
  } catch (error) {
    console.error('Error retrieving specific virtual account:', error);
  }
};

// Replace 'Account Label' or 'uuid' with the actual label or uuid of the account
getSpecificVirtualAccount('Account Label');

GET /virtual/virtual-account/search - Search User Virtual Accounts

Description: This endpoint searches for virtual accounts based on a label for a logged-in user.

Parameters:

ParameterTypeDescription

label

string

The label to search for among virtual accounts.

Response:

{
  "error": [],
  "result": [
    {
      "id": "uuid",
      "label": "Account Label",
      "active": true
    }
  ]
}

Error Handling:

Error CodeDescription

E_INVALID_PARAMS

Parameters provided are invalid.

Example Code:

const fetch = require('node-fetch');
const BASE_URL = 'https://api.whirlprivacy.io/';
const API_KEY = 'your_api_token';

const searchUserVirtualAccounts = async (searchLabel) => {
  try {
    const response = await fetch(`${BASE_URL}virtual/virtual-account/search?label=${encodeURIComponent(searchLabel)}`, {
      headers: {
        'X-API-Key': API_KEY
      }
    });
    const data = await response.json();

    console.log(data.result);
  } catch (error) {
    console.error('Error searching virtual accounts:', error);
  }
};

// Replace 'Search Label' with the actual label to search
searchUserVirtualAccounts('Search Label');

GET /virtual/virtual-accounts - List User Virtual Accounts

Description: Retrieves a list of all virtual accounts associated with the logged-in user. This includes the ability to filter accounts based on their active status and whether to include balance information.

Parameters:

ParameterTypeRequiredDescription

active

boolean

No

Filters the accounts based on their active status. Defaults to true.

balances

boolean

No

Determines if the balances should be included in the response.

Response:

{
  "error": [],
  "result": [
    {
      "id": "uuid",
      "label": "string",
      "active": "boolean",
      "balance": "number"
    }
  ]
}

Error Handling:

Error CodeDescription

E_INVALID_PARAMS

The provided parameters are invalid or missing.

E_VIRTUAL_ACCOUNT_NOT_FOUND

No virtual account matching the criteria found.

Example Code:

const fetch = require('node-fetch');

const BASE_URL = 'https://api.whirlprivacy.io/';
const API_KEY = 'your_api_token';

const listUserVirtualAccounts = async () => {
  try {
    const response = await fetch(`${BASE_URL}virtual/virtual-accounts?active=true&balances=true`, {
      headers: {
        'X-API-Key': API_KEY
      }
    });
    const data = await response.json();

    console.log(data.result);
  } catch (error) {
    console.error('Error retrieving user virtual accounts:', error);
  }
};

listUserVirtualAccounts();

Below is a markdown documentation for the API request described in the code you provided, specifically for retrieving the asset balance of a virtual account. This description is tailored to be integrated into a GitBook for project documentation.

GET /virtual/virtual-account/balance - Retrieve Asset Balance of a Virtual Account

Description: Retrieves the balance of the specified asset in a virtual account identified by either UUID or label. If the account is the user's main account or matches the given UUID or label, the balance of the asset is fetched. This endpoint is useful for financial tracking and management within the virtual account ecosystem.

Parameters:

ParameterTypeDescriptionRequired

ticker

string

The ticker symbol of the asset

Yes

uuid

string

The UUID of the virtual account (optional if label used)

No

label

string

The label of the virtual account (optional if UUID used)

No

Response:

{
  "error": [],
  "result": {
    "amount": "string (numeric)",
    "formatted": "string (decimal)"
  }
}

Error Handling:

Error CodeDescription

E_INVALID_PARAMS

Missing or invalid parameter(s)

E_INVALID_TICKER

The specified ticker does not exist

Example Code:

const fetch = require('node-fetch');

const BASE_URL = 'https://api.whirlprivacy.io/';
const API_KEY = 'your_api_token';

const getAssetBalance = async (ticker, uuid, label) => {
  try {
    let endpoint = `${BASE_URL}virtual/virtual-account/balance?ticker=${encodeURIComponent(ticker)}`;
    if (uuid) endpoint += `&uuid=${encodeURIComponent(uuid)}`;
    if (label) endpoint += `&label=${encodeURIComponent(label)}`;

    const response = await fetch(endpoint, {
      headers: {
        'X-API-Key': API_KEY
      }
    });
    const data = await response.json();

    console.log(data.result);
  } catch (error) {
    console.error('Error retrieving asset balance:', error);
  }
};

// Replace 'ticker', 'uuid', and 'label' with actual data
getAssetBalance('ETH', '1234-uuid', 'Main Account');

Last updated