# Virtual Accounts

## Create

Use Virtual accounts for instant and fee-less off-chain transactions.

#### Parameters

<table><thead><tr><th width="227.5">Param</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>Allowed value is <code>virtual</code> for Virtual Accounts.</td></tr><tr><td><code>ramp</code> (optional)</td><td>Related Ramp account. Mandatory for apps like Apps.Deposit, Apps.Payment and for <a href="../withdrawal#create-withdrawal">Withdrawal</a> from this account over ramp.</td></tr><tr><td><code>asset</code> </td><td>Account asset. Allowed values are "BTC", "LTC", "BCH", "DOGE", "ETH", "USDC", "USDT", "BUSD", "MATIC_ETH", "GMC", "SAND", "REVV", "BAT", "LAT", "WBTC", "MKR", "LINK", "PAX", "PAXG", "UNI", "LEO", "FREE", "XCON", "MATIC", "USDC_MATIC", "USDT_MATIC", "GAMEE", "CELO", "CUSD", "CEUR", "BSC", "USDC_BSC", "BUSD_BSC", "GMC_BSC", "CAKE", "BBTC", "BETH", "WBNB", "BDOT", "BXRP", "BLTC", "BBCH", "RMD", "TRON", "USDT_TRON", "INRT_TRON".<br><br>Or any defined <a href="virtual-currencies">Virtual Currency</a>.</td></tr><tr><td><code>currency</code> (optional)</td><td>Accounting Currency. If empty, will set to Realm default. Allowed values are "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BAT", "BBD", "BCH", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTC", "BTN", "BWP", "BYN", "BYR", "BZD", "CAD", "CDF", "CHF", "CLF", "CLP", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DOGE", "DZD", "EGP", "ERN", "ETB", "ETH", "EUR", "FJD", "FKP", "FLOW", "FUSD", "FREE", "GMC", "GMC_BSC", "RMD", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LEO", "LINK", "LKR", "LRD", "LSL", "LTC", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MKR", "MMK", "MMY", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PAX", "PAXG", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TRON", "TUSD", "BUSD", "TWD", "TZS", "UAH", "UGX", "UNI", "USD", "USDC", "USDT", "USDT_TRON", "INRT_TRON", "USDT_MATIC", "UYU", "UZS", "VEF", "VND", "VUV", "WBTC", "WST", "XAF", "XAG", "XAU", "XCD", "XCON", "XDR", "XLM", "XOF", "XPF", "XRP", "YER", "ZAR", "ZMK", "ZMW", "ZWL", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BAT", "BBD", "BCH", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTC", "BTN", "BWP", "BYN", "BYR", "BZD", "CAD", "CDF", "CHF", "CLF", "CLP", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DOGE", "DZD", "EGP", "ERN", "ETB", "ETH", "EUR", "FJD", "FKP", "FLOW", "FUSD", "FREE", "GMC", "GMC_BSC", "RMD", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LEO", "LINK", "LKR", "LRD", "LSL", "LTC", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MKR", "MMK", "MMY", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PAX", "PAXG", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TUSD", "BUSD", "TWD", "TZS", "UAH", "UGX", "UNI", "USD", "USDC", "USDT", "USDT_MATIC", "UYU", "UZS", "VEF", "VND", "VUV", "WBTC", "WST", "XAF", "XAG", "XAU", "XCD", "XCON", "XDR", "XLM", "XOF", "XPF", "XRP", "YER", "ZAR", "ZMK", "ZMW", "ZWL"</td></tr><tr><td><code>alias</code> (optional)</td><td>Create related <a href="../aliases#account-aliases">alias</a> object.</td></tr><tr><td><code>default</code> (optional)</td><td>Mark account as default for holder and asset.</td></tr><tr><td><code>data</code> (optional)</td><td>Use this object to freely model the account. </td></tr><tr><td><code>holder</code> (optional)</td><td>Identity of account holder. Defaults to current identity. Needs role <code>manage</code> or <code>admin</code> and <code>scope</code> realm to allow setting for not current Identity.</td></tr><tr><td><code>owner</code> (optional)</td><td>User of account owner. Defaults to current user. Needs role <code>manage</code> or <code>admin</code> and <code>scope</code> realm to allow setting for not current user.</td></tr></tbody></table>

{% tabs %}
{% tab title="cURL" %}

<pre class="language-shell"><code class="lang-shell"><strong>
</strong><strong>curl --location --request POST 'https://api.orangepill.cloud/v1/accounts' \
</strong>--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933deffdb' \
--header 'Content-Type: application/json' \
--data-raw '{
    "holder": "634b56217f6a7b0be52dffbd",
    "asset": "BTC",
    "type": "virtual",
    "testnet": true,
    "data": {
        "description": "BTC Savings account",
        "external_reference": "IBAN001"
    }
}'
</code></pre>

{% endtab %}
{% endtabs %}

In response we get new Virtual account. Currency and country are pulled from identity of Virtual account holder.

`balance.total` is total balance on this account

`balance.available` =  `balance.total - sum(account.blocks)`

Account creation is async operation. Once account is ready, field `enabled` is set to `true`. &#x20;

{% hint style="info" %}
Testnet networks are available only for native cryptocurrencies.
{% endhint %}

```json
{
    "id": "634b56217f6a7b0be52dffcc",
    "holder": "634b56217f6a7b0be52dffbd",
    "asset": "BTC",
    "type": "virtual",
    "testnet": true,    
    "data": {
        "description": "BTC Savings account",
        "external_reference": "IBAN001"
    },
    "currency": "USD",
    "country": "US",
    "balance": {
        "available": 0,
        "total": 0
    },
    "reference": "6b0be52dffcc34b56217f6a7",
    "active": "false",
    "frozen": "false",
    "created_at": "1519211809934",
    "error": null 
    
}
```

## Retrieve

{% tabs %}
{% tab title="cURL" %}

```shell

curl --location --request GET 'https://api.orangepill.cloud/v1/accounts/634b56217f6a7b0be52dffcc' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933deffdb' \
--header 'Content-Type: application/json'
```

{% endtab %}
{% endtabs %}

Response is example of active and enabled account.&#x20;

```json
{
    "id": "634b56217f6a7b0be52dffcc",
    "holder": "634b56217f6a7b0be52dffbd",
    "asset": "BTC",
    "type": "virtual",
    "testnet": true,    
    "data": {
        "description": "BTC Savings account",
        "external_reference": "IBAN001"
    },
    "currency": "USD",
    "country": "US",
    "balance": {
        "available": 0,
        "total": 0
    },
    "reference": "6b0be52dffcc34b56217f6a7",    
    "active": "true",
    "frozen": "false",
    "created_at": "1519211809934",
    "error": null
}
```

## Freeze

Frozen account can only receive balance. Available balance to send is set to 0.

{% tabs %}
{% tab title="cURL" %}

```shell

curl --location --request POST 'https://api.orangepill.cloud/v1/accounts/634b56217f6a7b0be52dffcc/freeze' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933deffdb' \
--header 'Content-Type: application/json'
```

{% endtab %}
{% endtabs %}

Response is example of frozen account.&#x20;

```json
{
    "id": "634b56217f6a7b0be52dffcc",
    "holder": "634b56217f6a7b0be52dffbd",
    "asset": "BTC",
    "type": "virtual",
    "testnet": true,    
    "data": {
        "description": "BTC Savings account",
        "external_reference": "IBAN001"
    },
    "currency": "USD",
    "country": "US",
    "balance": {
        "available": 0,
        "total": 1.0
    },
    "reference": "6b0be52dffcc34b56217f6a7",    
    "active": "true",
    "frozen": "true",
    "created_at": "1519211809934",
    "updated_at": "1519217655585",
    "error": null
}
```

{% hint style="info" %}
To unfreeze account call service `POST /v1/accounts/:id/unfreeze`
{% endhint %}

## Deactivate

This operation closes `Account`. Deactivated account can neither send or receive balance. Account can be deactivated only when `balance.total` and `balance.available` are 0.&#x20;

{% tabs %}
{% tab title="cURL" %}

```shell

curl --location --request POST 'https://api.orangepill.cloud/v1/accounts/634b56217f6a7b0be52dffcc/deactivate' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933deffdb' \
--header 'Content-Type: application/json'
```

{% endtab %}
{% endtabs %}

Response is example of deactivated account.&#x20;

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "id": "634b56217f6a7b0be52dffcc",
    "holder": "634b56217f6a7b0be52dffbd",
    "asset": "BTC",
    "type": "virtual",
    "testnet": true,    
    "data": {
        "description": "BTC Savings account",
        "external_reference": "IBAN001"
    },
    "currency": "USD",
    "country": "US",
    "balance": {
        "available": 0,
        "total": 0
    },
    "reference": "6b0be52dffcc34b56217f6a7",    
    "active": "false",
    "frozen": "false",
    "created_at": "1519211809934",
    "updated_at": "1519217655585",
    "error": null
}
</code></pre>

{% hint style="info" %}
To activate account call service `POST /v1/accounts/:id/activate`
{% endhint %}

## Assigning external address

This operation will link external blockchain address to virtual account. Any deposit made on-chain to external address will appear as balance available in virtual account. You can link any number of external addresses. Each external addresses can be assigned once to one virtual account.

Existing balance on the linked address at the moment of assigning will not appear in virtual account. Only new deposits sent to external address will appear as balance available on virtual account.

{% hint style="info" %}
**IMPORTANT**: Linked balance cannot be subtracted.
{% endhint %}

{% tabs %}
{% tab title="cURL" %}

```sh
curl --location --request POST 'https://api.orangepill.cloud/v1/accounts/634b56217f6a7b0be52dffcc/assign/0xf57820a66C0b3677C2e4F540303c5d3f2d368FF4' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933deffdb' \
--header 'Content-Type: application/json'
```

{% endtab %}
{% endtabs %}

In response you will receive details of assigned external address.

```json
{
    "address": "0xa2b16a2f08e67ea603efa97577e435d5073d91ce",
    "currency": "ETH"
}
```

## Remove assigned address

External address can be unlinked from virtual account. Balance of virtual account will not be affected with this operation.

{% tabs %}
{% tab title="cURL" %}

```sh
curl --location --request DELETE 'https://api.orangepill.cloud/v1/accounts/634b56217f6a7b0be52dffcc/assign/0xf57820a66C0b3677C2e4F540303c5d3f2d368FF4' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933deffdb' \
--header 'Content-Type: application/json'
```

{% endtab %}
{% endtabs %}

in response you will receive an array of active assigned addresses.

```json
[
    {
        "address": "0xa2b16a2f08e67ea603efa97577e435d5073d91ce",
        "currency": "ETH"
    }
]
```

## List assigned addresses

All external addresses assigned to virtual account can be listed.

{% tabs %}
{% tab title="cURL" %}

```sh
curl --location --request GET 'https://api.orangepill.cloud/v1/accounts/634b56217f6a7b0be52dffcc/assign\
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933deffdb' \
--header 'Content-Type: application/json'
```

{% endtab %}
{% endtabs %}

In response you will get a list of external addresses linked to this virtual account.

<pre class="language-json"><code class="lang-json">[
    {
        "address": "0xa2b16a2f08e67ea603efa97577e435d5073d91ce",
        "currency": "ETH"
    },
<strong>    {
</strong>        "address": "0xa2f08e67ea97577e435d5073d91ce2b16a603efa",
        "currency": "ETH"
    }    
]
</code></pre>
Param	Description
`type`	Allowed value is `virtual` for Virtual Accounts.
`ramp` (optional)	Related Ramp account. Mandatory for apps like Apps.Deposit, Apps.Payment and for Withdrawal from this account over ramp.
`asset`	Account asset. Allowed values are "BTC", "LTC", "BCH", "DOGE", "ETH", "USDC", "USDT", "BUSD", "MATIC_ETH", "GMC", "SAND", "REVV", "BAT", "LAT", "WBTC", "MKR", "LINK", "PAX", "PAXG", "UNI", "LEO", "FREE", "XCON", "MATIC", "USDC_MATIC", "USDT_MATIC", "GAMEE", "CELO", "CUSD", "CEUR", "BSC", "USDC_BSC", "BUSD_BSC", "GMC_BSC", "CAKE", "BBTC", "BETH", "WBNB", "BDOT", "BXRP", "BLTC", "BBCH", "RMD", "TRON", "USDT_TRON", "INRT_TRON". Or any defined Virtual Currency.
`currency` (optional)	Accounting Currency. If empty, will set to Realm default. Allowed values are "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BAT", "BBD", "BCH", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTC", "BTN", "BWP", "BYN", "BYR", "BZD", "CAD", "CDF", "CHF", "CLF", "CLP", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DOGE", "DZD", "EGP", "ERN", "ETB", "ETH", "EUR", "FJD", "FKP", "FLOW", "FUSD", "FREE", "GMC", "GMC_BSC", "RMD", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LEO", "LINK", "LKR", "LRD", "LSL", "LTC", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MKR", "MMK", "MMY", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PAX", "PAXG", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TRON", "TUSD", "BUSD", "TWD", "TZS", "UAH", "UGX", "UNI", "USD", "USDC", "USDT", "USDT_TRON", "INRT_TRON", "USDT_MATIC", "UYU", "UZS", "VEF", "VND", "VUV", "WBTC", "WST", "XAF", "XAG", "XAU", "XCD", "XCON", "XDR", "XLM", "XOF", "XPF", "XRP", "YER", "ZAR", "ZMK", "ZMW", "ZWL", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BAT", "BBD", "BCH", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTC", "BTN", "BWP", "BYN", "BYR", "BZD", "CAD", "CDF", "CHF", "CLF", "CLP", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DOGE", "DZD", "EGP", "ERN", "ETB", "ETH", "EUR", "FJD", "FKP", "FLOW", "FUSD", "FREE", "GMC", "GMC_BSC", "RMD", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LEO", "LINK", "LKR", "LRD", "LSL", "LTC", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MKR", "MMK", "MMY", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PAX", "PAXG", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TUSD", "BUSD", "TWD", "TZS", "UAH", "UGX", "UNI", "USD", "USDC", "USDT", "USDT_MATIC", "UYU", "UZS", "VEF", "VND", "VUV", "WBTC", "WST", "XAF", "XAG", "XAU", "XCD", "XCON", "XDR", "XLM", "XOF", "XPF", "XRP", "YER", "ZAR", "ZMK", "ZMW", "ZWL"
`alias` (optional)	Create related alias object.
`default` (optional)	Mark account as default for holder and asset.
`data` (optional)	Use this object to freely model the account.
`holder` (optional)	Identity of account holder. Defaults to current identity. Needs role `manage` or `admin` and `scope` realm to allow setting for not current Identity.
`owner` (optional)	User of account owner. Defaults to current user. Needs role `manage` or `admin` and `scope` realm to allow setting for not current user.