Virtual Accounts

Virtual account holds off-chain balance.

Create

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

Parameters

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 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 .

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 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.


curl --location --request POST 'https://api.orangepill.cloud/v1/accounts' \
--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"
    }
}'

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.

Testnet networks are available only for native cryptocurrencies.

{
    "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


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'

Response is example of active and enabled account.

{
    "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.


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'

Response is example of frozen account.

{
    "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
}

To unfreeze account call service POST /v1/accounts/:id/unfreeze

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.


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'

Response is example of deactivated account.

{
    "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
}

To activate account call service POST /v1/accounts/:id/activate

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.

IMPORTANT: Linked balance cannot be subtracted.

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'

In response you will receive details of assigned external address.

{
    "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.

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'

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

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

List assigned addresses

All external addresses assigned to virtual account can be listed.

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'

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

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

PreviousDeposit Accounts NextAliases

Last updated 1 year ago