--- updatedAt: 2026-05-27T08:48:52.000Z agentTools: projectIndex: https://docs.tatum.io/llms.txt --- # Create new virtual currency

/v3/ledger/virtualCurrency

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. To create a fungible token, see the API for deploying a fungible token smart contract.

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.

Digital assets:

# OpenAPI definition ```json { "openapi": "3.1.0", "servers": [ { "url": "https://api.tatum.io" } ], "info": { "version": "1.2", "title": "Virtual Accounts" }, "tags": [ { "name": "Virtual Currency" } ], "paths": { "/v3/ledger/virtualCurrency": { "post": { "description": "

/v3/ledger/virtualCurrency

\n

2 credits per API call

\n

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

\n

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)

\n

Tatum virtual currency acts as any other asset within Tatum. To create a fungible token, see the API for deploying a fungible token smart contract.

\n

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.

\n

Digital assets:

\n\n", "operationId": "createCurrency", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualCurrency" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "description": "Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error403VCPrefix" }, { "$ref": "#/components/schemas/Error403VCDuplicate" }, { "$ref": "#/components/schemas/Error403VCCreateFailed" } ] } } } }, "500": { "$ref": "#/components/responses/Error500" } }, "security": [ { "X-API-Key": [] } ], "x-codeSamples": [], "summary": "Create new virtual currency", "tags": [ "Virtual Currency" ] } } }, "components": { "securitySchemes": { "X-API-Key": { "type": "apiKey", "name": "x-api-key", "in": "header", "description": "Your **API key** is used to identify your account & your plan, including the number of API calls per second and total monthly calls you have.\n\nEach key is for individual use only.\n\nIf you don't have a key already you can [Sign up for a Free Tatum account](https://co.tatum.io/signup) to get two keys (testnet and mainnet), allowing up to 5 API calls per second and 1,000,000 Credits.\n\nFor testing purposes, you can use the following key which only works inside docs and has limited functionality (e.g. you cannot create virtual accounts or notification subscriptions with it):\n* t-66a730ccccfd17001c479705-2f597d14ad7543f289a03418\n\nFor more details on limits and plans, [click here](https://docs.tatum.io/docs/plans-limits).\n" } }, "responses": { "Error400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "errorCode": { "example": "validation.failed", "description": "validation.failed", "type": "string" }, "message": { "example": "Request validation failed. Please see data for additional information.", "description": "Request validation failed. Please see data for additional information.", "type": "string" }, "statusCode": { "example": 400, "description": "400", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "object", "additionalProperties": true, "description": "Request object present in the body of the HTTP request", "example": { "property": 12345 } }, "value": { "type": "number", "description": "Value of the target object which validation is wrong. Can be of any data type, example here is using type number.", "example": 12345 }, "property": { "type": "string", "description": "Property name of the target object which validation is wrong", "example": "property1" }, "constraints": { "type": "object", "additionalProperties": true, "description": "Object of failed constraints for the target object. Key is the constraint, value is detailed description of the failed constraint.", "example": { "min": "property1 must not be less than 50000" } } } } } }, "required": [ "errorCode", "message", "statusCode", "data" ], "type": "object" } } } }, "Error401": { "description": "Unauthorized. Not valid or inactive subscription key present in the HTTP Header.", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "errorCode": { "example": "subscription.not.active", "description": "subscription.not.active", "type": "string" }, "message": { "example": "Subscription not active anymore.", "description": "Subscription not active anymore.", "type": "string" }, "statusCode": { "example": 401, "description": "401", "type": "number" } }, "required": [ "errorCode", "message", "statusCode" ], "type": "object" }, { "properties": { "errorCode": { "example": "subscription.invalid", "description": "subscription.invalid", "type": "string" }, "message": { "example": "Unable to find valid subscription for '${apiKey}'", "description": "Unable to find valid subscription for '${apiKey}'", "type": "string" }, "statusCode": { "example": 401, "description": "401", "type": "number" } }, "required": [ "errorCode", "message", "statusCode" ], "type": "object" } ] } } } }, "Error500": { "description": "Internal server error. There was an error on the server during the processing of the request.", "content": { "application/json": { "schema": { "properties": { "message": { "example": "Internal server error", "description": "Internal server error", "type": "string" }, "statusCode": { "example": 500, "description": "500", "type": "number" } }, "required": [ "statusCode", "message" ], "type": "object" } } } } }, "schemas": { "FiatCurrency": { "type": "string", "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", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "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" ] }, "FiatOrCryptoCurrency": { "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "ALGO", "ADA", "BAM", "BAT", "BBD", "BCH", "BDT", "BGN", "BHD", "BIF", "BMD", "BNB", "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", "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", "MATIC", "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", "USDC_MATIC", "USDC_MATIC_NATIVE", "USDT", "USDT_TRON", "USDT_MATIC", "UYU", "UZS", "VEF", "VND", "VUV", "WBTC", "WST", "XAF", "XAG", "XAU", "XCD", "XCON", "XDR", "XOF", "XPF", "XRP", "YER", "ZAR", "ZMK", "ZMW", "ZWL" ] }, "CustomerRegistration": { "properties": { "externalId": { "description": "The external ID of the customer; use only anonymized identification that you have in your system
If a customer with the specified external ID does not exist, a new customer is created. If a customer with the specified external ID exists, it is updated with the provided information.", "example": "123654", "maxLength": 100, "minLength": 1, "type": "string" }, "accountingCurrency": { "description": "The ISO 4217 code of the currency in which all transactions for all virtual accounts of the customer will be billed; to overwrite the currency for this specific virtual account, set the accountingCurrency parameter at the account level.", "default": "EUR", "example": "USD", "$ref": "#/components/schemas/FiatCurrency" }, "customerCountry": { "description": "The ISO 3166-1 code of the country that the customer has to be compliant with", "example": "US", "maxLength": 2, "minLength": 2, "type": "string" }, "providerCountry": { "description": "The ISO 3166-1 code of the country that the service provider has to be compliant with", "example": "US", "maxLength": 2, "minLength": 2, "type": "string" } }, "required": [ "externalId" ], "type": "object", "description": "If a customer with the specified external ID does not exist, a new customer is created. If a customer with the specified external ID exists, it is updated with the provided information." }, "Error403VCCreateFailed": { "properties": { "errorCode": { "description": "virtual.creation.error", "example": "virtual.creation.error", "type": "string" }, "message": { "description": "It is not possible to create virtual currency.", "example": "It is not possible to create virtual currency.", "type": "string" }, "statusCode": { "description": "403", "example": 403, "type": "number" } }, "required": [ "errorCode", "message", "statusCode" ], "type": "object" }, "Error403VCPrefix": { "properties": { "errorCode": { "description": "virtual.name.prefix", "example": "virtual.name.prefix", "type": "string" }, "message": { "description": "Virtual currency has wrong name, must start with VC_.", "example": "Virtual currency has wrong name, must start with VC_.", "type": "string" }, "statusCode": { "description": "403", "example": 403, "type": "number" } }, "required": [ "errorCode", "message", "statusCode" ], "type": "object" }, "Error403VCDuplicate": { "properties": { "errorCode": { "description": "virtual.duplicate", "example": "virtual.duplicate", "type": "string" }, "message": { "description": "Virtual currency with given name already exists.", "example": "Virtual currency with given name already exists.", "type": "string" }, "statusCode": { "description": "403", "example": 403, "type": "number" } }, "required": [ "errorCode", "message", "statusCode" ], "type": "object" }, "Account": { "properties": { "id": { "description": "The ID of the virtual account", "example": "5e68c66581f2ee32bc354087", "type": "string" }, "balance": { "$ref": "#/components/schemas/AccountBalance" }, "currency": { "description": "The currency of the virtual account", "example": "BTC", "type": "string" }, "frozen": { "description": "If set to \"true\", the virtual account is frozen", "example": false, "type": "boolean" }, "active": { "description": "If set to \"true\", the virtual account is active", "example": true, "type": "boolean" }, "customerId": { "description": "The ID of the customer (newly created or existing one) associated with the virtual account", "type": "string", "example": "5e68c66581f2ee32bc354087" }, "accountNumber": { "description": "The number associated with the virtual account in an external system", "maxLength": 50, "minLength": 1, "example": "123456", "type": "string" }, "accountCode": { "description": "The code associated with the virtual account in an external system to designate the purpose of the account in bookkeeping", "example": "03_ACC_01", "type": "string" }, "accountingCurrency": { "description": "The currency in which all the transactions for all accounts will be accounted", "example": "EUR", "type": "string" }, "xpub": { "description": "The extended public key of the blockchain wallet associated with the virtual account; used to generate deposit addresses for the virtual account", "example": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka", "type": "string" } }, "required": [ "id", "active", "frozen", "currency", "balance" ], "type": "object" }, "AccountBalance": { "properties": { "accountBalance": { "description": "All assets on the account, both available and blocked", "example": "1000000", "type": "string" }, "availableBalance": { "description": "The account balance minus the blocked assets; use the available balance to determine how much a customer can send or withdraw from their virtual account", "example": "1000000", "type": "string" } }, "type": "object", "required": [ "accountBalance", "availableBalance" ] }, "VirtualCurrency": { "properties": { "name": { "description": "Virtual currency name. Must be prefixed with 'VC_'.", "example": "VC_VIRTUAL", "maxLength": 30, "pattern": "^[a-zA-Z0-9_]+$", "minLength": 1, "type": "string" }, "supply": { "description": "Supply of virtual currency.", "maxLength": 38, "minLength": 1, "example": "1000000", "type": "string", "pattern": "^[+]?((\\d+(\\.\\d*)?)|(\\.\\d+))$" }, "basePair": { "description": "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.", "$ref": "#/components/schemas/FiatOrCryptoCurrency", "example": "BTC" }, "baseRate": { "type": "number", "example": 1, "default": 1, "minimum": 0, "description": "Exchange rate of the base pair. Each unit of the created curency will represent value of baseRate*1 basePair." }, "customer": { "$ref": "#/components/schemas/CustomerRegistration" }, "description": { "description": "Used as a description within Tatum system.", "example": "My Virtual Token description.", "maxLength": 100, "minLength": 1, "type": "string" }, "accountCode": { "description": "For bookkeeping to distinct account purpose.", "maxLength": 50, "example": "AC_1011_B", "minLength": 1, "type": "string" }, "accountNumber": { "description": "Account number from external system.", "example": "1234567890", "type": "string", "minLength": 1, "maxLength": 50 }, "accountingCurrency": { "description": "All transaction will be billed in this currency for created account associated with this currency. If not set, EUR is used. ISO-4217", "$ref": "#/components/schemas/FiatCurrency", "example": "USD" } }, "required": [ "basePair", "name", "supply" ], "type": "object" } } } } ```