🔮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:

Parameter	Type	Description
labels	array of strings	List of labels for the new virtual accounts.

Response:

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

Error Handling:

Error Code	Description
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:

Parameter	Type	Description
amount	integer	The number of unnamed accounts to create.

Response:

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

Error Handling:

Error Code	Description
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:

Name	Type	Description
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 Code	Meaning
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:

Name	Type	Description
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 Code	Meaning
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 Code	Description
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 Code	Description
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:

Parameter	Type	Description
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 Code	Description
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:

Parameter	Type	Description
label	string	The label to search for among virtual accounts.

Response:

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

Error Handling:

Error Code	Description
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:

Parameter	Type	Required	Description
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 Code	Description
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:

Parameter	Type	Description	Required
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 Code	Description
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');