Tatum
Search…
API Reference
How to support fiat currencies
A fiat currency is a government-issued currency that isn't backed by a commodity such as gold.
In addition to crypto accounts, virtual accounts also support private virtual currencies. A virtual currency does not have to be connected to the blockchain. It can live within the virtual accounts alone. When you create your own virtual currency, you can then create accounts and send virtual account transactions.
A virtual currency is an entity in the virtual account distributed database. It is created with an initial supply of coins. This supply can be extended or reduced at any time.
Every virtual currency inside virtual accounts is pegged to a currency from the outside world. It can be a blockchain asset or FIAT currency. This means that one unit of the virtual currency is equal to one unit of the pegged currency.
When you create a virtual currency VC_USD with the base pair USD, 1 VC_USD = 1 USD, you can set your custom base rate, e.g., 1 VC_USD = 2 USD with the base rate 2.

To support FIAT currencies, you can create your own virtual currency with the base pair as the currency you want to support.
JavaScript
cURL
import {Currency, Fiat, createVirtualCurrency } from '@tatumio/tatum';
/**
* Create new virtual currency with given supply stored in account.
* This will create Tatum internal virtual currency.
* @param data - body of request - https://apidoc.tatum.io/tag/Virtual-Currency/#operation/createCurrency
* @returns virtual currency detail
*/
const body = {
name: "VC_USD",
supply: "100000",
basePair: USD
}
const vc = createVirtualCurrency (body);
curl --location --request POST 'https://api-eu1.tatum.io/v3/ledger/virtualCurrency' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "VC_USD",
"supply": "100000",
"basePair": "USD"
}'
The result of the call is a virtual account of the given virtual currency. The initial supply of the virtual currency is already credited to the account.
Response
{
"balance": {
"accountBalance": "100000",
"availableBalance": "100000"
},
"active": true,
"frozen": false,
"currency": "VC_USD",
"accountingCurrency": "EUR",
"id": "5fbe46739045a09adbc3f590"
}

When you want to increase the supply of a virtual currency, you have to mint new units. Minted units are credited to the specific virtual account, and the operation is visible as a new virtual account transaction for that account.
JavaScript
cURL
import { mintVirtualCurrency } from '@tatumio/tatum';
/**
* Create new supply of virtual currency linked on the given accountId.
* @param data - body of request - https://apidoc.tatum.io/tag/Virtual-Currency/#operation/mintCurrency
* @returns transaction internal reference
*/
const body = {
accountId: "5fbe46739045a09adbc3f590",
amount: "100",
}
const mint = mintVirtualCurrency (body);
curl --location --request PUT 'https://api-eu1.tatum.io/v3/ledger/virtualCurrency/mint' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"accountId": "5fbe46739045a09adbc3f590",
"amount": "100"
}'
The result of the call is a reference to the virtual account transaction.
Response
{
"reference": "c7b8ca84-bab3-42d0-9115-90fad09e5f57"
}

When you want to destroy the supply of a virtual currency, you have to revoke some units. Destroyed units are debited from the specific virtual account, and the operation is visible as a new virtual account transaction for the account.
JavaScript
cURL
import { revokeVirtualCurrency } from '@tatumio/tatum';
/**
* Destroy supply of virtual currency linked on the given accountId.
* @param data - body of request - https://apidoc.tatum.io/tag/Virtual-Currency/#operation/revokeCurrency
* @returns transaction internal reference
*/
const body = {
accountId: "5fbe46739045a09adbc3f590",
amount: "100",
}
const burn = revokeVirtualCurrency (body);
curl --location --request PUT 'https://api-eu1.tatum.io/v3/ledger/virtualCurrency/revoke' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"accountId": "5fbe46739045a09adbc3f590",
"amount": "100"
}'
The response is a reference ID for the virtual account transaction.
Response
{
"reference": "e9574b40-4b25-4f03-be76-27cec5e564fc"
}

Using the account ID of the virtual account, we can now get a list of account transactions.
JavaScript
cURL
import {getTransactionsByAccount} from '@tatumio/tatum';
/**
* Finds transactions for the account identified by the given account ID.
* @param filter - request body with data filter - https://apidoc.tatum.io/tag/Transaction/#operation/getTransactionsByAccountId
* @param pageSize - max number of items per page is 50.
* @param offset - optional Offset to obtain next page of the data.
*/
const filter = {
id: "5fbe46739045a09adbc3f590",
}
const tx = getTransactionsByAccount(filter,50,0);
curl --location --request POST 'https://api-eu1.tatum.io/v3/ledger/transaction/account?pageSize=50' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "5fbe46739045a09adbc3f590"
}'
In the response, we can see the two transactions we have just performed - mint and revoke.
Response
[
{
"amount": "-100",
"operationType": "REVOKE",
"currency": "VC_USD",
"transactionType": "DEBIT_OUTGOING_PAYMENT",
"accountId": "5fbe46739045a09adbc3f590",
"anonymous": false,
"reference": "e9574b40-4b25-4f03-be76-27cec5e564fc",
"senderNote": null,
"recipientNote": null,
"paymentId": null,
"transactionCode": null,
"marketValue": {
"currency": "EUR",
"source": "Fixer.io",
"sourceDate": 1606302850000,
"amount": "-84.13613226199991586387"
},
"created": 1606305988347
},
{
"amount": "100",
"operationType": "MINT",
"currency": "VC_USD",
"transactionType": "CREDIT_INCOMING_PAYMENT",
"accountId": "5fbe46739045a09adbc3f590",
"anonymous": false,
"reference": "c7b8ca84-bab3-42d0-9115-90fad09e5f57",
"recipientNote": null,
"paymentId": null,
"transactionCode": null,
"marketValue": {
"currency": "EUR",
"source": "Fixer.io",
"sourceDate": 1606302850000,
"amount": "84.13613226199991586387"
},
"created": 1606305827044
}
]

It is impossible to integrate Tatum directly into a specific bank or card processor to read and perform bank transactions. This is due to legislative restrictions. Bank integration must be done in your application and reflect your bank operations into Tatum.
The typical flow is as follows:
  • When you receive a payment into your bank account or via a card transaction, you can mint a new supply on the connected user account.
  • When you send a payment from your bank account, you can revoke the supply from the connected user account.
  • You will then perform all internal transactions within the Tatum virtual accounts and your application ecosystem.
For more information on how to support virtual accounts in a crypto exchange, please refer to the following workshop:
Copy link
On this page
Creating a virtual currency
Increasing the supply of a virtual currency
Destroying the supply of a virtual currency
Listing account transactions
Typical integration steps