Account

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.

Create new account

2 credits per API call.

Creates a new account for the customer. This will create an account on Tatum Private Ledger. It is possible to create an account for every supported cryptocurrency, FIAT, any ERC20 token created within a Tatum instance, and Tatum virtual currencies. When the customer field is already present, the account is added to the customer's list of accounts. If the customer field is not present, a new customer is created along with the account.
Every account has its own balance. Tatum supports 2 types of balances - accountBalance and availableBalance. The account balance represents all assets in the account, both available and blocked. The available balance in the account represents account balance minus the blocked amount in the account. The available balance should be used to determine how much a customer can send or withdraw from the account.
An account is always created with a specific currency. Once the currency is set, it cannot be changed.
When an account's currency is blockchain-based, like BTC or ETH, the account is usually created with xpub. Xpub represents an extended public key of the blockchain wallet, which will be connected to this account. Adding xpub to the account does not connect any specific blockchain address to this account. Xpub is just a generator of addresses, not an address itself. Every blockchain has different types of xpubs:

BTC - xpub can be obtained from generate wallet
LTC - xpub can be obtained from generate wallet
DOGE - xpub can be obtained from generate wallet
BCH - xpub can be obtained from generate wallet
ADA - xpub can be obtained from generate wallet
ETH and ERC20 - xpub can be obtained from generate wallet
XRP - xpub is the address field from generate account
XLM - xpub is the address field from generate account
BNB - xpub is the address field from generate account
LUNA - xpub is the address field from generate account
BSC - xpub can be obtained from generate wallet
EGLD - no xpub, use address field from generate wallet
ALGO - no xpub, use address field from generate wallet
SOL - no xpub, use address field from generate wallet
MATIC - xpub can be obtained from generate wallet
KLAY - xpub can be obtained from generate wallet
XDC - xpub can be obtained from generate wallet
KCS - xpub can be obtained from generate wallet
CELO, cEUR, cUSD and ERC20 - xpub can be obtained from generate wallet
TRON and TRC tokens - xpub can be obtained from generate wallet
FLOW and FUSD - xpub can be obtained from generate wallet

There are 2 options for connecting an account to a blockchain:

If xpub is present in the account, addresses are generated for the account via Create new deposit address. This is the preferred mechanism.
If xpub is not present in the account, addresses for this account are assigned manually via Assign address. This feature is used when there are already existing addresses to be used in Tatum.

SecurityX-API-Key

Request

Request Body schema: application/json

currency

required

string [ 2 .. 40 ] characters

Account currency. Supported values are BTC, BNB, LTC, DOGE, BCH, ETH, XLM, LUNA, LUNA_KRW, LUNA_USD, XRP, TRON, BSC, SOL, MATIC, ALGO, KCS, EGLD, CELO, KLAY, XDC, KCS, Tatum Virtual Currencies started with VC_ prefix (this includes FIAT currencies), USDT, WBTC, LEO, LINK, GMC, UNI, FREE, MKR, USDC, BAT, TUSD, BUSD, PAX, PAXG, MMY, XCON, USDT_TRON, BETH, BUSD, BBTC, BADA, WBNB, BDOT, BXRP, BLTC, BBCH, CAKE, BUSD_BSC, ERC20, BEP20 or TRC-10/20 custom tokens registered in the Tatum Platform, XLM or XRP Assets created via Tatum Platform. ERC20 tokens and BEP20 tokens do not have Testnet blockchains, so it is impossible to use them in a non-production environment. You can emulate behaviour by registering your custom ERC20 token in the platform and receive tokens using https://erc20faucet.com/.

xpub

string [ 1 .. 192 ] characters

Extended public key to generate addresses from.

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

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 = 3 characters

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

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"

accountNumber

string [ 1 .. 50 ] characters

Account number from external system.

Responses

200

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 perform the required operation due to a logical error or invalid permissions.

500

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

post/v3/ledger/account

Request samples

application/json

{"currency": "BTC",
"xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid",
"customer": {"accountingCurrency": "USD",
"customerCountry": "US",
"externalId": "123654",
"providerCountry": "US"
},
"compliant": false,
"accountCode": "AC_1011_B",
"accountingCurrency": "USD",
"accountNumber": "123456"
}

Response samples

application/json

{"id": "5e68c66581f2ee32bc354087",
"balance": {"accountBalance": "1000000",
"availableBalance": "1000000"
},
"currency": "BTC",
"frozen": false,
"active": true,
"customerId": "5e68c66581f2ee32bc354087",
"accountCode": "03_ACC_01",
"accountingCurrency": "EUR",
"xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}

List all accounts

1 credit per API call.

Lists all accounts. Inactive accounts are also visible.

SecurityX-API-Key

Request

query Parameters

pageSize	number [ 1 .. 50 ] Max number of items per page is 50. Example: pageSize=20
page	number Page number Example: page=0
sort	string Direction of sorting. Can be asc or desc Enum: "asc" "desc" Example: sort=asc
sortBy	string Sort by Enum: "_id" "account_number" "account_balance" "available_balance" Example: sortBy=_id
active	boolean Filter only active or non active accounts Example: active=true
onlyNonZeroBalance	boolean Filter only accounts with non zero balances Example: onlyNonZeroBalance=true
frozen	boolean Filter only frozen or non frozen accounts Example: frozen=true
currency	string Filter by currency Example: currency=BTC
accountNumber	string [ 1 .. 50 ] characters Filter by account number Example: accountNumber=AC_1011_B

Responses

200

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.

500

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

get/v3/ledger/account

Request samples

curl -i -X GET \
  'https://api-eu1.tatum.io/v3/ledger/account?pageSize=20&page=0&sort=asc&sortBy=_id&active=true&onlyNonZeroBalance=true&frozen=true&currency=BTC&accountNumber=AC_1011_B' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

[{"id": "5e68c66581f2ee32bc354087",
"balance": {"accountBalance": "1000000",
"availableBalance": "1000000"
},
"currency": "BTC",
"frozen": false,
"active": true,
"customerId": "5e68c66581f2ee32bc354087",
"accountCode": "03_ACC_01",
"accountingCurrency": "EUR",
"xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}
]

Count of found entities for get accounts request

1 credit per API call.

Count of accounts that were found from /v3/ledger/account

SecurityX-API-Key

Request

query Parameters

pageSize	number [ 1 .. 50 ] Max number of items per page is 50. Example: pageSize=20
page	number Page number Example: page=0
sort	string Direction of sorting. Can be asc or desc Enum: "asc" "desc"
sortBy	string Sort by Enum: "_id" "account_number" "account_balance" "available_balance" Example: sortBy=_id
active	boolean Filter only active or non active accounts Example: active=true
onlyNonZeroBalance	boolean Filter only accounts with non zero balances Example: onlyNonZeroBalance=true
frozen	boolean Filter only frozen or non frozen accounts Example: frozen=true
currency	string Filter by currency Example: currency=BTC
accountNumber	string [ 1 .. 50 ] characters Filter by account number Example: accountNumber=AC_1011_B

Responses

200

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.

500

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

get/v3/ledger/account/count

Request samples

curl -i -X GET \
  'https://api-eu1.tatum.io/v3/ledger/account/count?pageSize=20&page=0&sort=asc&sortBy=_id&active=true&onlyNonZeroBalance=true&frozen=true&currency=BTC&accountNumber=AC_1011_B' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

{"total": 20
}

Create multiple accounts in a batch call

2 credits per API call + 1 credit for every account created.

Creates new accounts for the customer in a batch call.

SecurityX-API-Key

Request

Request Body schema: application/json

required

Array of objects (CreateAccount)

Array

currency required	string [ 2 .. 40 ] characters Account currency. Supported values are BTC, BNB, LTC, DOGE, BCH, ETH, XLM, LUNA, LUNA_KRW, LUNA_USD, XRP, TRON, BSC, SOL, MATIC, ALGO, KCS, EGLD, CELO, KLAY, XDC, KCS, Tatum Virtual Currencies started with VC_ prefix (this includes FIAT currencies), USDT, WBTC, LEO, LINK, GMC, UNI, FREE, MKR, USDC, BAT, TUSD, BUSD, PAX, PAXG, MMY, XCON, USDT_TRON, BETH, BUSD, BBTC, BADA, WBNB, BDOT, BXRP, BLTC, BBCH, CAKE, BUSD_BSC, ERC20, BEP20 or TRC-10/20 custom tokens registered in the Tatum Platform, XLM or XRP Assets created via Tatum Platform. ERC20 tokens and BEP20 tokens do not have Testnet blockchains, so it is impossible to use them in a non-production environment. You can emulate behaviour by registering your custom ERC20 token in the platform and receive tokens using https://erc20faucet.com/.
xpub	string [ 1 .. 192 ] characters Extended public key to generate addresses from.
	object (CustomerRegistration) If customer is filled then is created or updated.
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 = 3 characters 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 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"
accountNumber	string [ 1 .. 50 ] characters Account number from external system.

Responses

200

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 perform the required operation due to a logical error or invalid permissions.

500

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

post/v3/ledger/account/batch

Request samples

application/json

{"accounts": [{"currency": "BTC",
"xpub": "xpub6EsCk1uU6cJzqvP9CdsTiJwT2rF748YkPnhv5Qo8q44DG7nn2vbyt48YRsNSUYS44jFCW9gwvD9kLQu9AuqXpTpM1c5hgg9PsuBLdeNncid",
"customer": {"accountingCurrency": "USD",
"customerCountry": "US",
"externalId": "123654",
"providerCountry": "US"
},
"compliant": false,
"accountCode": "AC_1011_B",
"accountingCurrency": "USD",
"accountNumber": "123456"
}
]
}

Response samples

application/json

[{"id": "5e68c66581f2ee32bc354087",
"balance": {"accountBalance": "1000000",
"availableBalance": "1000000"
},
"currency": "BTC",
"frozen": false,
"active": true,
"customerId": "5e68c66581f2ee32bc354087",
"accountCode": "03_ACC_01",
"accountingCurrency": "EUR",
"xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}
]

List all customer accounts

1 credit per API call.

Lists all accounts associated with a customer. Only active accounts are visible.

SecurityX-API-Key

Request

path Parameters

required

string

Internal customer ID

Example: 5e68c66581f2ee32bc354087

query Parameters

pageSize required	number [ 1 .. 50 ] Max number of items per page is 50. Example: pageSize=10
offset	number Offset to obtain the next page of data. Example: offset=0
accountCode	string [ 1 .. 50 ] characters For bookkeeping to distinct account purpose. Example: accountCode=AC_1011_B

Responses

200

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.

500

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

get/v3/ledger/account/customer/{id}

Request samples

curl -i -X GET \
  'https://api-eu1.tatum.io/v3/ledger/account/customer/{id}?pageSize=10&offset=0&accountCode=AC_1011_B' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

[{"id": "5e68c66581f2ee32bc354087",
"balance": {"accountBalance": "1000000",
"availableBalance": "1000000"
},
"currency": "BTC",
"frozen": false,
"active": true,
"customerId": "5e68c66581f2ee32bc354087",
"accountCode": "03_ACC_01",
"accountingCurrency": "EUR",
"xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}
]

Get account by ID

1 credit per API call.

Gets active account by ID. Displays all information regarding the given account.

SecurityX-API-Key

Request

path Parameters

required

string

Account ID

Example: 5e68c66581f2ee32bc354087

Responses

200

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 perform the required operation due to a logical error or invalid permissions.

500

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

get/v3/ledger/account/{id}

Request samples

curl -i -X GET \
  'https://api-eu1.tatum.io/v3/ledger/account/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

{"id": "5e68c66581f2ee32bc354087",
"balance": {"accountBalance": "1000000",
"availableBalance": "1000000"
},
"currency": "BTC",
"frozen": false,
"active": true,
"customerId": "5e68c66581f2ee32bc354087",
"accountCode": "03_ACC_01",
"accountingCurrency": "EUR",
"xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka"
}

Update account

2 credits per API call.

Update account by ID. Only a small number of fields can be updated.

SecurityX-API-Key

Request

path Parameters

required

string

Account ID

Example: 5e68c66581f2ee32bc354087

Request Body schema: application/json

accountCode	string [ 1 .. 50 ] characters For bookkeeping to distinct account purpose.
accountNumber	string [ 1 .. 50 ] characters Account number from external system.

Responses

204

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 perform the required operation due to a logical error or invalid permissions.

500

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

put/v3/ledger/account/{id}

Request samples

application/json

{"accountCode": "AC_1011_B",
"accountNumber": "123456"
}

Response samples

application/json

{"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 account balance

1 credit per API call.

Get balance for the account.

SecurityX-API-Key

Request

path Parameters

required

string

Account ID

Example: 5e68c66581f2ee32bc354087

Responses

200

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 perform the required operation due to a logical error or invalid permissions.

500

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

get/v3/ledger/account/{id}/balance

Request samples

curl -i -X GET \
  'https://api-eu1.tatum.io/v3/ledger/account/{id}/balance' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

{"accountBalance": "1000000",
"availableBalance": "1000000"
}

Block an amount in an account

2 credits per API call.

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.

SecurityX-API-Key

Request

path Parameters

required

string

Account ID

Example: 5e6be89ee6aa436299950c3f

Request Body schema: application/json

amount required	string <= 38 characters ^[+]?((\d+(\.\d*)?)\|(\.\d+))$ Amount to be blocked on account.
type required	string [ 1 .. 100 ] characters Type of blockage.
description	string [ 1 .. 300 ] characters Description of blockage.

Responses

200

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 perform the required operation due to a logical error or invalid permissions.

500

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

post/v3/ledger/account/block/{id}

Request samples

application/json

{"amount": "5",
"type": "DEBIT_CARD_OP",
"description": "Card payment in the shop."
}

Response samples

application/json

{"id": "5e68c66581f2ee32bc354087"
}

Unblock an amount in an account and perform a transaction

2 credits per API call.

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.

SecurityX-API-Key

Request

path Parameters

required

string

Blockage ID

Example: 5e6be89ee6aa436299950c3f

Request Body schema: application/json

recipientAccountId required	string = 24 characters Internal recipient account ID within Tatum platform
amount required	string <= 38 characters ^[+]?((\d+(\.\d*)?)\|(\.\d+))$ Amount to be sent. Amount can be smaller then the blocked amount.
anonymous	boolean Default: false Anonymous transaction does not show sender account to recipient, default is false
compliant	boolean Enable compliant checks. Transaction will not be processed, if compliant check fails.
transactionCode	string [ 1 .. 100 ] characters For bookkeeping to distinct transaction purpose.
paymentId	string [ 1 .. 100 ] characters Payment ID, External identifier of the payment, which can be used to pair transactions within Tatum accounts.
recipientNote	string [ 1 .. 500 ] characters Note visible to both, sender and recipient
baseRate	number >= 0 Default: 1 Exchange rate of the base pair. Only applicable for Tatum's Virtual currencies Ledger transactions. Override default exchange rate for the Virtual Currency.
senderNote	string [ 1 .. 500 ] characters Note visible to sender

Responses

200

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 perform the required operation due to a logical error or invalid permissions.

500

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

put/v3/ledger/account/block/{id}

Request samples

application/json

{"recipientAccountId": "5e6645712b55823de7ea82f2",
"amount": "5",
"anonymous": false,
"compliant": false,
"transactionCode": "1_01_EXTERNAL_CODE",
"paymentId": "9625",
"recipientNote": "Private note",
"baseRate": 1,
"senderNote": "Sender note"
}

Response samples

application/json

{"reference": "0c64cc04-5412-4e57-a51c-ee5727939bcb"
}

Unblock a blocked amount in an account

1 credit per API call.

Unblocks a previously blocked amount in an account. Increases the available balance in the account where the amount was blocked.

SecurityX-API-Key

Request

path Parameters

required

string

Blockage ID

Example: 5e6be89ee6aa436299950c3f

Responses

204

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.

500

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

delete/v3/ledger/account/block/{id}

Request samples

curl -i -X DELETE \
  'https://api-eu1.tatum.io/v3/ledger/account/block/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

{"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 blocked amounts in an account

1 credit per API call.

Gets blocked amounts for an account.

SecurityX-API-Key

Request

path Parameters

required

string

Account ID

Example: 5e6be89ee6aa436299950c3f

query Parameters

pageSize required	number [ 1 .. 50 ] Max number of items per page is 50. Example: pageSize=10
offset	number Offset to obtain the next page of data. Example: offset=0

Responses

200

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.

500

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

get/v3/ledger/account/block/{id}

Request samples

curl -i -X GET \
  'https://api-eu1.tatum.io/v3/ledger/account/block/{id}?pageSize=10&offset=0' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

[{"id": "5e68c66581f2ee32bc354087",
"accountId": "5e68c66581f2ee32bc354087",
"amount": "5",
"type": "DEBIT_CARD_OP",
"description": "Card payment in the shop."
}
]

Get blocked amount by ID

1 credit per API call.

Gets blocked amount by id.

SecurityX-API-Key

Request

path Parameters

required

string

Blocked amount ID

Example: 5e6be89ee6aa436299950c3f

Responses

200

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.

500

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

get/v3/ledger/account/block/{id}/detail

Request samples

curl -i -X GET \
  'https://api-eu1.tatum.io/v3/ledger/account/block/{id}/detail' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

{"id": "5e68c66581f2ee32bc354087",
"accountId": "5e68c66581f2ee32bc354087",
"amount": "5",
"type": "DEBIT_CARD_OP",
"description": "Card payment in the shop."
}

Unblock all blocked amounts in an account

1 credit per API call, 1 credit for each deleted blockage. 1 API call + 2 blockages = 3 credits.

Unblocks previously blocked amounts in an account. Increases the available balance in the account where the amount was blocked.

SecurityX-API-Key

Request

path Parameters

required

string

Account ID

Example: 5e6be89ee6aa436299950c3f

Responses

204

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 perform the required operation due to a logical error or invalid permissions.

500

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

delete/v3/ledger/account/block/account/{id}

Request samples

curl -i -X DELETE \
  'https://api-eu1.tatum.io/v3/ledger/account/block/account/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

{"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"
}
}
]
}

Activate account

2 credits per API call.

Activates an account.

SecurityX-API-Key

Request

path Parameters

required

string

Account ID

Example: 5e68c66581f2ee32bc354087

Responses

204

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 perform the required operation due a to logical error or invalid permissions.

500

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

put/v3/ledger/account/{id}/activate

Request samples

curl -i -X PUT \
  'https://api-eu1.tatum.io/v3/ledger/account/{id}/activate' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

{"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"
}
}
]
}

Deactivate account

2 credits per API call.

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.

SecurityX-API-Key

Request

path Parameters

required

string

Account ID

Example: 5e68c66581f2ee32bc354087

Responses

204

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 perform the required operation due to a logical error or invalid permissions.

500

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

put/v3/ledger/account/{id}/deactivate

Request samples

curl -i -X PUT \
  'https://api-eu1.tatum.io/v3/ledger/account/{id}/deactivate' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

{"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"
}
}
]
}

Freeze account

2 credits per API call.

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.

SecurityX-API-Key

Request

path Parameters

required

string

Account ID

Example: 5e68c66581f2ee32bc354087

Responses

204

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 perform the required operation due to a logical error or invalid permissions.

500

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

put/v3/ledger/account/{id}/freeze

Request samples

curl -i -X PUT \
  'https://api-eu1.tatum.io/v3/ledger/account/{id}/freeze' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

{"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"
}
}
]
}

Unfreeze account

2 credits per API call.

Unfreezes a previously frozen account. Unfreezing a non-frozen account not affect the account.

SecurityX-API-Key

Request

path Parameters

required

string

Account ID

Example: 5e68c66581f2ee32bc354087

Responses

204

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 perform the required operation due to a logical error or invalid permissions.

500

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

put/v3/ledger/account/{id}/unfreeze

Request samples

curl -i -X PUT \
  'https://api-eu1.tatum.io/v3/ledger/account/{id}/unfreeze' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Response samples

application/json

{"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"
}
}
]
}

➔ Next to Transaction