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.
Request Body schema: application/json
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
- Payload
- curl
- JavaScript
- Python
- PHP
- Go
- C#
{- "name": "VC_VIRTUAL",
- "supply": "1000000",
- "basePair": "BTC",
- "baseRate": 1,
- "customer": {
- "accountingCurrency": "USD",
- "customerCountry": "US",
- "externalId": "123654",
- "providerCountry": "US"
}, - "description": "My Virtual Token description.",
- "accountCode": "AC_1011_B",
- "accountNumber": "1234567890",
- "accountingCurrency": "USD"
}- 200
- 400
- 401
- 403
- 500
{- "id": "5e68c66581f2ee32bc354087",
- "balance": {
- "accountBalance": "1000000",
- "availableBalance": "1000000"
}, - "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.
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. |
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
- Payload
- curl
- JavaScript
- Python
- PHP
- Go
- C#
{- "name": "VC_VIRTUAL",
- "baseRate": 1,
- "basePair": "EUR"
}- 400
- 401
- 403
- 500
{- "errorCode": "validation.failed",
- "message": "Request validation failed. Please see data for additional information.",
- "statusCode": 400,
- "data": [
- {
- "target": {
- "property": 12345
}, - "value": 12345,
- "property": "property1",
- "constraints": {
- "min": "property1 must not be less than 50000"
}
}
]
}Get virtual currency
1 credit per API call.
Get detail of virtual currency.
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
- curl
- JavaScript
- Python
- PHP
- Go
- C#
curl -i -X GET \ 'https://api-eu1.tatum.io/v3/ledger/virtualCurrency/{name}' \ -H 'x-api-key: YOUR_API_KEY_HERE'
- 200
- 400
- 401
- 403
- 500
{- "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.
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. |
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
- Payload
- curl
- JavaScript
- Python
- PHP
- Go
- C#
{- "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"
}- 200
- 400
- 401
- 403
- 500
{- "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.
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. |
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
- Payload
- curl
- JavaScript
- Python
- PHP
- Go
- C#
{- "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"
}- 200
- 400
- 401
- 403
- 500
{- "reference": "0c64cc04-5412-4e57-a51c-ee5727939bcb"
}