# Ramp Accounts

Use Ramps to enable on-chain deposits and withdrawals.

Withdrawal is always done from `ramp.address` even if there are multiple deposit Addresses assigned. All incoming transactions deposited to other addresses are automatically forwarded to `ramp.address`. In this case, balance received on Ramp is diminished for on-chain fee value applied to internal transfer Deposit Address -> Ramp Address.

When incoming deposit is received on Virtual Account's address, assets will be forwarded to Ramp's `ramp.address`,  following the liabilities balance movement from Ramp -> Virtual Account.&#x20;

Vice versa, withdrawal created for Virtual Account will move liabilities balance Virtual Account -> Ramp account, following the asset withdrawal from Ramp Account's `ramp.address` to destination address.

{% hint style="info" %}
Ramp accounts and Deposit accounts are holding 3 or 4 types of balances. In case when asset is native cryptocurrency, accounts will have 2 off chain balances, **available** and **total**, and 1 on chain balance, **assets**. Additionally if account asset is ERC20, BEP20 or TRC20 token, there will be additional balance, **gas**, with amount of available native tokens to pay blockchain gas fees for withdrawal process.
{% endhint %}

## Create Ramp Account

#### 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>ramp</code> for Ramp Accounts.</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": "ramp",
    "data": {
        "description": "Cummulative BTC account.",
        "external_reference": "IBAN002"
    }
}'
</code></pre>

{% endtab %}
{% endtabs %}

In response we get new Ramp Account

`ramp.address` is main address for deposits and withdrawals.

`ramp.assets` is balance of assets on `ramp.address` available for withdrawal.

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "id": "634b56217f6a7b0be52dffaa",
    "holder": "634b56217f6a7b0be52dffbd",
    "asset": "BTC",
    "type": "ramp",
    "data": {
        "description": "Cummulative BTC account.",
        "external_reference": "IBAN002"
    },
    "currency": "USD",
    "country": "US",
    "balance": {
        "available": 0,
        "total": 0,
        "assets": 0
    },
    "ramp": {
        "address": "634b56217f6a7b0be52dffab",
    },
    "reference": "6b0be52dffcc34b56217f6a7",    
    "active": "false",
    "frozen": "false",
    "created_at": "1519211809934",
    "error": null
}
</code></pre>

## Connect Virtual Account to Ramp Account

Adding a field `ramp` will connect Virtual account to Ramp account.

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

```shell

curl --location --request POST 'https://api.orangepill.cloud/v1/accounts \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'idempotency-key: 27373fabc392933deffdc' \
--header 'Content-Type: application/json' \
--data-raw '{
    "holder": "634b56217f6a7b0be52dffbd",
    "asset": "BTC",
    "type": "virtual",
    "ramp": "689ba7b0be52dffbd56217aa",
    "data": {
        "description": "BTC account of John Doe",
        "external_reference": "IBAN003"
    },
}'
```

{% endtab %}
{% endtabs %}

In response we get new Virtual Account

`ramp` is reference to a Ramp that will handle deposits and withdraws for Virtual Account.

```json
{
    "id": "634b56217f6a7b0be52dffca",
    "holder": "634b56217f6a7b0be52dffbd",
    "asset": "BTC",
    "type": "virtual",
    "data": {
        "description": "BTC account of John Doe",
        "external_reference": "IBAN003"
    },
    "currency": "USD",
    "country": "US",
    "balance": {
        "available": 0,
        "total": 0
    },
    "ramp": "634b56217f6a7b0be52dffaa",
    "reference": "6b0be52dffcc34b56217f6a7",    
    "active": "false",
    "frozen": "false",
    "created_at": "1519211809934",
    "error": null
}
```

## Deposit to Ramp account

On-chain deposits can be sent to default Ramp address. After deposit is received and processed, all balances of ramp account will be increased for amount received. To get blockchain address to receive on-chain transactions, populate address details with `populate=address` querystring parameters.

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

```shell
echo 'populate address details for ramp account'

curl --location --request GET 'https://api.orangepill.cloud/v1/account/634b56217f6a7b0be52dffbd?populate=address' \
--header 'x-api-key: AXVubzpwQDU1dzByYM==' \
--header 'Content-Type: application/json'
```

{% endtab %}
{% endtabs %}

In response you will get full address details. In this example blockchain address is `"address": "0x4e5ac860ee4c2db16a3bd4450bdeb21e14cf281e".`

```json
{
    "id": "63ab92d694bdaeb815cb4365",
    "asset": "ETH",
    "chain": "ethereum",
    "data": null,
    "holder": "639675ab191e9023f356dfa7",
    "currency": "USD",
    "type": "ramp",
    "testnet": false,
    "reference": "63ab92d611da79ce37322335",
    "subscription": "63ab92d750dede50c4c7e6af",
    "balance": {
        "available": 0,
        "total": 0,
        "assets": 0
    },
    "ramp": null,
    "owner": "639675ab191e9023f356dfa6",
    "created_at": 1672188630240,
    "error": null,
    "active": true,
    "frozen": false,
    "deleted": false,
    "address": {
        "id": "63ab92d794bdaeb815cb4367",
        "account": "63ab92d694bdaeb815cb4365",
        "data": null,
        "asset": "ETH",
        "address": "0x4e5ac860ee4c2db16a3bd4450bdeb21e14cf281e",
        "derivation_key": "1",
        "xpub": "xpub6ET1YuT1WEHNzdyoBYMhYScEZMTSBRixirKAps5FJcBTz2KNq2eRsRzEKQvmLearYNe9JXHpLFuPfYokQvr9emohL7ZQuo7U4CSBswYzZfw",
        "destination_tag": null,
        "memo": null,
        "message": null,
        "notification": null,
        "created_at": 1672188631469,
        "error": null
    }
}
```

##
Param	Description
`type`	Allowed value is `ramp` for Ramp Accounts.
`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.