Virtual Currency

Register and use Tatum Private Ledger's virtual currencies. You can create your own virtual currency and distribute it amongst your customers.
Virtual currencies are used to support FIAT currencies. When a virtual currency is created with basePair of the FIAT currency, it is possible to perform transactions in the private ledger in FIAT.

Create new virtual currency

2 credits per API call.


Create new virtual currency with given supply stored in account. This will create Tatum internal virtual currency. Every virtual currency must be prefixed with VC_.
Every virtual currency must be pegged to existing FIAT or supported cryptocurrency. 1 unit of virtual currency has then the same amount as 1 unit of the base currency it is pegged to. It is possible to set a custom base rate for the virtual currency. (baseRate = 2 => 1 VC unit = 2 basePair units)
Tatum virtual currency acts as any other asset within Tatum. For creation of ERC20 token, see ERC20 .
This operation returns the newly created Tatum Ledger account with an initial balance set to the virtual currency's total supply. Total supply can be changed in the future.

SecurityX-API-Key
Request
Request Body schema: application/json
name
required
string [ 1 .. 30 ] characters ^[a-zA-Z0-9_]+$

Virtual currency name. Must be prefixed with 'VC_'.

supply
required
string [ 1 .. 38 ] characters ^[+]?((\d+(\.\d*)?)|(\.\d+))$

Supply of virtual currency.

basePair
required
string [ 3 .. 50 ] characters

Base pair for virtual currency. Transaction value will be calculated according to this base pair. e.g. 1 VC_VIRTUAL is equal to 1 BTC, if basePair is set to BTC.

Enum: "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" "USDT_MATIC" "QTUM" "UYU" "UZS" "VEF" "VND" "VUV" "WBTC" "WST" "XAF" "XAG" "XAU" "XCD" "XCON" "XDR" "XLM" "XOF" "XPF" "XRP" "YER" "ZAR" "ZMK" "ZMW" "ZWL"
baseRate
number >= 0
Default: 1

Exchange rate of the base pair. Each unit of the created curency will represent value of baseRate*1 basePair.

object (CustomerRegistration)

If customer is filled then is created or updated.

accountingCurrency
string = 3 characters

All transaction will be accounted in this currency for all accounts. Currency can be overridden per account level. If not set, EUR is used. ISO-4217

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BRL" "BSD" "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" "EUR" "FJD" "FKP" "FLOW" "FUSD" "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" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "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" "TWD" "TZS" "UAH" "UGX" "USD" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XCD" "XDR" "XOF" "XPF" "YER" "ZAR" "ZMK" "ZMW" "ZWL"
customerCountry
string = 2 characters

Country customer has to be compliant with. ISO-3166-1

externalId
required
string [ 1 .. 100 ] characters

Customer external ID. Use only anonymized identification you have in your system. If customer with externalId does not exists new customer is created. If customer with specified externalId already exists it is updated.

providerCountry
string = 2 characters

Country service provider has to be compliant with. ISO-3166-1

description
string [ 1 .. 100 ] characters

Used as a description within Tatum system.

accountCode
string [ 1 .. 50 ] characters

For bookkeeping to distinct account purpose.

accountNumber
string

Account number from external system.

accountingCurrency
string = 3 characters

All transaction will be billed in this currency for created account associated with this currency. If not set, EUR is used. ISO-4217

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BRL" "BSD" "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" "EUR" "FJD" "FKP" "FLOW" "FUSD" "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" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "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" "TWD" "TZS" "UAH" "UGX" "USD" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XCD" "XDR" "XOF" "XPF" "YER" "ZAR" "ZMK" "ZMW" "ZWL"
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

post/v3/ledger/virtualCurrency
Request samples
application/json
{
  • "name": "VC_VIRTUAL",
  • "supply": "1000000",
  • "basePair": "BTC",
  • "baseRate": 1,
  • "customer": {
    },
  • "description": "My Virtual Token description.",
  • "accountCode": "AC_1011_B",
  • "accountNumber": "1234567890",
  • "accountingCurrency": "USD"
}
Response samples
application/json
{
  • "id": "5e68c66581f2ee32bc354087",
  • "balance": {
    },
  • "currency": "BTC",
  • "frozen": false,
  • "active": true,
  • "customerId": "5e68c66581f2ee32bc354087",
  • "accountCode": "03_ACC_01",
  • "accountingCurrency": "EUR",
  • "xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}

Update virtual currency

2 credits per API call.


Change base pair and/or base rate of existing virtual currency.

SecurityX-API-Key
Request
Request Body schema: application/json
name
required
string [ 1 .. 30 ] characters ^[a-zA-Z0-9_]+$

Virtual currency name, which will be updated. It is not possible to update the name of the virtual currency.

baseRate
number >= 0
Default: 1

Exchange rate of the base pair. Each unit of the created curency will represent value of baseRate*1 basePair.

basePair
string [ 3 .. 50 ] characters

Base pair for virtual currency. Transaction value will be calculated according to this base pair. e.g. 1 VC_VIRTUAL is equal to 1 BTC, if basePair is set to BTC.

Enum: "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" "USDT_MATIC" "QTUM" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "WBTC" "XCD" "XCON" "XDR" "XLM" "XOF" "XPF" "XRP" "YER" "ZAR" "ZMK" "ZMW" "ZWL"
Responses
204

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

put/v3/ledger/virtualCurrency
Request samples
application/json
{
  • "name": "VC_VIRTUAL",
  • "baseRate": 1,
  • "basePair": "EUR"
}
Response samples
application/json
{
  • "errorCode": "validation.failed",
  • "message": "Request validation failed. Please see data for additional information.",
  • "statusCode": 400,
  • "data": [
    ]
}

Get virtual currency

1 credit per API call.


Get detail of virtual currency.

SecurityX-API-Key
Request
path Parameters
name
required
string [ 3 .. 100 ] characters
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

get/v3/ledger/virtualCurrency/{name}
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/ledger/virtualCurrency/{name}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "name": "VC_VIRTUAL",
  • "supply": "1000000",
  • "accountId": "5e68c66581f2ee32bc354087",
  • "baseRate": 1,
  • "basePair": "BTC",
  • "customerId": "5e68c66581f2ee32bc354087",
  • "description": "My Virtual Token description.",
  • "erc20Address": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "issuerAccount": "GDKYMXOAJ5MK4EVIHHNWRGAAOUZMNZYAETMHFCD6JCVBPZ77TUAZFPKT",
  • "chain": "ETH",
  • "initialAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85"
}

Create new supply of virtual currency

2 credits per API call.


Create new supply of virtual currency linked on the given accountId. Method increases the total supply of the currency.
This method creates Ledger transaction with operationType MINT with undefined counterAccountId.

SecurityX-API-Key
Request
Request Body schema: application/json
accountId
required
string = 24 characters

Ledger account with currency of the virtual currency, on which the operation will be performed.

amount
required
string <= 38 characters ^[+]?((\d+(\.\d*)?)|(\.\d+))$

Amount of virtual currency to operate within this operation.

paymentId
string [ 1 .. 100 ] characters

Identifier of the payment, shown for created Transaction within Tatum sender account.

reference
string [ 1 .. 100 ] characters

Reference of the payment.

transactionCode
string [ 1 .. 100 ] characters

For bookkeeping to distinct transaction purpose.

recipientNote
string [ 1 .. 500 ] characters

Note visible to both, sender and recipient. Available for both Mint and Revoke operations

counterAccount
string = 24 characters

External account identifier. By default, there is no counterAccount present in the transaction.

senderNote
string [ 1 .. 500 ] characters

Note visible to sender. Available in Revoke operation.

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

put/v3/ledger/virtualCurrency/mint
Request samples
application/json
{
  • "accountId": "5e68c66581f2ee32bc354087",
  • "amount": "1.5",
  • "paymentId": "My Payment",
  • "reference": "akjsndakjsdn-asd-kjasnd-asdkn-asdjnasjkdn",
  • "transactionCode": "1_01_EXTERNAL_CODE",
  • "recipientNote": "Private note",
  • "counterAccount": "5e6645712b55823de7ea82f1",
  • "senderNote": "Sender note"
}
Response samples
application/json
{
  • "reference": "0c64cc04-5412-4e57-a51c-ee5727939bcb"
}

Destroy supply of virtual currency

2 credits per API call.


Destroy supply of virtual currency linked on the given accountId. Method decreases the total supply of the currency.
This method creates Ledger transaction with operationType REVOKE with undefined counterAccountId.

SecurityX-API-Key
Request
Request Body schema: application/json
accountId
required
string = 24 characters

Ledger account with currency of the virtual currency, on which the operation will be performed.

amount
required
string <= 38 characters ^[+]?((\d+(\.\d*)?)|(\.\d+))$

Amount of virtual currency to operate within this operation.

paymentId
string [ 1 .. 100 ] characters

Identifier of the payment, shown for created Transaction within Tatum sender account.

reference
string [ 1 .. 100 ] characters

Reference of the payment.

transactionCode
string [ 1 .. 100 ] characters

For bookkeeping to distinct transaction purpose.

recipientNote
string [ 1 .. 500 ] characters

Note visible to both, sender and recipient. Available for both Mint and Revoke operations

counterAccount
string = 24 characters

External account identifier. By default, there is no counterAccount present in the transaction.

senderNote
string [ 1 .. 500 ] characters

Note visible to sender. Available in Revoke operation.

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

put/v3/ledger/virtualCurrency/revoke
Request samples
application/json
{
  • "accountId": "5e68c66581f2ee32bc354087",
  • "amount": "1.5",
  • "paymentId": "My Payment",
  • "reference": "akjsndakjsdn-asd-kjasnd-asdkn-asdjnasjkdn",
  • "transactionCode": "1_01_EXTERNAL_CODE",
  • "recipientNote": "Private note",
  • "counterAccount": "5e6645712b55823de7ea82f1",
  • "senderNote": "Sender note"
}
Response samples
application/json
{
  • "reference": "0c64cc04-5412-4e57-a51c-ee5727939bcb"
}