A Tatum Account is the primary building block of Tatum-powered applications. It is an envelope that holds essential information about balances, the state of the account or customer, and to whom the account belongs.
Accounts in Tatum are stored within Tatum Private Ledger. Tatum Private Ledger contains information about accounts, the customers that own the accounts, transactions that affect the accounts or virtual currencies present in the ledger.
By default, the private ledger is not connected to any blockchain. It is possible to create an application on it without any blockchain at all. Using Tatum Private Ledger and the building blocks included within it, it is possible to quickly swap the whole application from the ledger to any blockchain supported by Tatum. All of the API calls will remain the same, the only thing that changes is the blockchain the application lives on.
Most blockchains do not have any compliance layer at all. It is not possible to freeze funds at a blockchain address or deactivate an address. The Tatum Account has built-in compliance, and it is possible to block funds in the account, freeze outgoing transactions from the account or even completely deactivate the account.
2 credits per API call
Create a new virtual account for a customer.
You can create a virtual account for any supported cryptocurrency, fiat currency, Tatum virtual currency, or fungible tokens created within Tatum. Once the currency/asset is set for a virtual account, it cannot be changed.
Virtual account balance
A virtual account has its own balance. The balance can be logically presented by the account balance and available balance:
accountBalance
) represents all assets on the account, both available and blocked.availableBalance
) represents 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.Cryptocurrency virtual accounts
When you create a virtual account based on a cryptocurrency (for example, BTC or ETH), you have to provide the extended public key (xpub
) of the blockchain wallet that will be connected to this account.
NOTE: Adding xpub
to the virtual account does not connect any specific blockchain address to this account. xpub
is a generator of addresses, not an address itself.
Not all blockchains provide xpub
for wallets, or Tatum may not support wallets on some blockchains. In such cases, use the wallet address or the account address instead.
xpub
provided; use address
from the generated wallet instead.xpub
from the generated wallet.xpub
provided; use address
from the generated wallet instead.xpub
from the generated wallet instead.xpub
from the generated wallet instead.xpub
from the generated wallet.xpub
from the generated wallet.xpub
provided; use address
from the generated blockchain address instead.xpub
from the generated wallet.xpub
from the generated wallet.xpub
from the generated wallet.xpub
from the generated wallet.xpub
from the generated wallet.xpub
from the generated wallet.xpub
provided; use address
from the generated wallet instead.xpub
from the generated wallet.xpub
from the generated wallet.xpub
provided; use address
from the generated account instead.xpub
provided; use address
from the generated account instead.Connect a virtual account to the blockchain
xpub
, generate a new blockchain address for this account.xpub
, assign an existing blockchain address to this account.You can connect multiple blockchain addresses to one virtual account.
Digital assets:
0x2791bca1f2de4661ed88a30c99a7a9449aa84174
on Polygon mainnet.0x3c499c542cef5e3811e1192ce70d8cc03d5c3359
on Polygon mainnet.currency required | string [ 2 .. 40 ] characters The currency for the virtual account
|
xpub required | string [ 1 .. 192 ] characters Extended public key to generate addresses from. |
object (CustomerRegistration) 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. | |
compliant | boolean Enable compliant checks. If this is enabled, it is impossible to create account if compliant check fails. |
accountCode | string [ 1 .. 50 ] characters For bookkeeping to distinct account purpose. |
accountingCurrency | string (FiatCurrency) All transaction will be accounted in this currency for all accounts. Currency can be overridden per account level. If not set, customer accountingCurrency is used or EUR by default. ISO-4217 |
accountNumber | string [ 1 .. 50 ] characters Account number from external system. |
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "currency": "BTC",
- "xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid"
}
{- "id": "5e68c66581f2ee32bc354087",
- "balance": {
- "accountBalance": "1000000",
- "availableBalance": "1000000"
}, - "currency": "BTC",
- "frozen": false,
- "active": true,
- "customerId": "5e68c66581f2ee32bc354087",
- "accountNumber": "123456",
- "accountCode": "03_ACC_01",
- "accountingCurrency": "EUR",
- "xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}
Lists all accounts. Inactive accounts are also visible.
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.
Internal server error. There was an error on the server while processing the request.
[- {
- "id": "5e68c66581f2ee32bc354087",
- "balance": {
- "accountBalance": "1000000",
- "availableBalance": "1000000"
}, - "currency": "BTC",
- "frozen": false,
- "active": true,
- "customerId": "5e68c66581f2ee32bc354087",
- "accountNumber": "123456",
- "accountCode": "03_ACC_01",
- "accountingCurrency": "EUR",
- "xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}
]
Count of accounts that were found from /v3/ledger/account
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.
Internal server error. There was an error on the server while processing the request.
{- "total": 20
}
Creates new accounts for the customer in a batch call.
required | Array of objects (CreateAccount) | ||||||||||||
Array
|
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "accounts": [
- {
- "currency": "BTC"
}
]
}
[- {
- "id": "5e68c66581f2ee32bc354087",
- "balance": {
- "accountBalance": "1000000",
- "availableBalance": "1000000"
}, - "currency": "BTC",
- "frozen": false,
- "active": true,
- "customerId": "5e68c66581f2ee32bc354087",
- "accountNumber": "123456",
- "accountCode": "03_ACC_01",
- "accountingCurrency": "EUR",
- "xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}
]
Lists all accounts associated with a customer. Only active accounts are visible.
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.
Internal server error. There was an error on the server while processing the request.
[- {
- "id": "5e68c66581f2ee32bc354087",
- "balance": {
- "accountBalance": "1000000",
- "availableBalance": "1000000"
}, - "currency": "BTC",
- "frozen": false,
- "active": true,
- "customerId": "5e68c66581f2ee32bc354087",
- "accountNumber": "123456",
- "accountCode": "03_ACC_01",
- "accountingCurrency": "EUR",
- "xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}
]
Gets active account by ID. Displays all information regarding the given account.
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "id": "5e68c66581f2ee32bc354087",
- "balance": {
- "accountBalance": "1000000",
- "availableBalance": "1000000"
}, - "currency": "BTC",
- "frozen": false,
- "active": true,
- "customerId": "5e68c66581f2ee32bc354087",
- "accountNumber": "123456",
- "accountCode": "03_ACC_01",
- "accountingCurrency": "EUR",
- "xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}
Update account by ID. Only a small number of fields can be updated.
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{ }
{- "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 balance for the account.
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "accountBalance": "1000000",
- "availableBalance": "1000000"
}
Blocks an amount in an account. Any number of distinct amounts can be blocked in one account. Every new blockage has its own distinct ID, which is used as a reference. When the amount is blocked, it is debited from the available balance of the account. The account balance remains the same. The account balance represents the total amount of funds in the account. The available balance represents the total amount of funds that can be used to perform transactions. When an account is frozen, the available balance is set to 0 minus all blockages for the account.
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "amount": "5",
- "type": "DEBIT_CARD_OP"
}
{- "id": "5e68c66581f2ee32bc354087"
}
Unblocks a previously blocked amount in an account and invokes a ledger transaction from that account to a different recipient. If the request fails, the amount is not unblocked.
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "recipientAccountId": "5e6645712b55823de7ea82f2",
- "amount": "5"
}
{- "reference": "0c64cc04-5412-4e57-a51c-ee5727939bcb"
}
Unblocks a previously blocked amount in an account. Increases the available balance in the account where the amount was blocked.
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.
Internal server error. There was an error on the server while processing the request.
{- "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"
}
}
]
}
Gets blocked amounts for an account.
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.
Internal server error. There was an error on the server while processing the request.
[- {
- "id": "5e68c66581f2ee32bc354087",
- "accountId": "5e68c66581f2ee32bc354087",
- "amount": "5",
- "type": "DEBIT_CARD_OP",
- "description": "Card payment in the shop."
}
]
Gets blocked amount by id.
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.
Internal server error. There was an error on the server while processing the request.
{- "id": "5e68c66581f2ee32bc354087",
- "accountId": "5e68c66581f2ee32bc354087",
- "amount": "5",
- "type": "DEBIT_CARD_OP",
- "description": "Card payment in the shop."
}
Unblocks previously blocked amounts in an account. Increases the available balance in the account where the amount was blocked.
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "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"
}
}
]
}
Activates an account.
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 perform the required operation due a to logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "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"
}
}
]
}
Deactivates an account. Only accounts with account and available balances of zero can be deactivated. Deactivated accounts are not visible in the list of accounts, it is not possible to send funds to these accounts or perform transactions. However, they are still present in the ledger and all transaction histories.
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "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"
}
}
]
}
Disables all outgoing transactions. Incoming transactions to the account are available. When an account is frozen, its available balance is set to 0. This operation will create a new blockage of type ACCOUNT_FROZEN, which is automatically deleted when the account is unfrozen.
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "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"
}
}
]
}
Unfreezes a previously frozen account. Unfreezing a non-frozen account not affect the account.
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 perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "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"
}
}
]
}