Tatum
Powered by Redocly

Transaction

An endpoint used to create and list transactions within Tatum Private Ledger. A transaction is performed between 2 accounts with the same currency. To perform an exchange operation between accounts with different currencies, API calls from Order Book sections are available. Transactions in the ledger are instant, with a settlement time of below 200ms.
Tatum Private Ledger supports microtransactions - a transaction of an amount as little as 1e-30 (30 decimal places). Transactions are atomic.
When there is an insufficient balance in the sender account, or recipient account cannot receive funds, the transaction is not settled.

Send payment

4 credits per API call.


Sends a payment within Tatum Private Ledger. All assets are settled instantly.
When a transaction is settled, 2 transaction records are created, 1 for each of the participants. These 2 records are connected via a transaction reference, which is the same for both of them.
This method is only used for transferring assets between accounts within Tatum and will not send any funds to blockchain addresses.
If there is an insufficient balance in the sender account, no transaction is recorded.
It is possible to perform an anonymous transaction where the sender account is not visible for the recipient.
The FIAT currency value of every transaction is calculated automatically. The FIAT value is based on the accountingCurrency of the account connected to the transaction and is available in the marketValue parameter of the transaction.

SecurityX-API-Key
Request
Request Body schema: application/json
senderAccountId
required
string = 24 characters

Internal sender account ID within Tatum platform

recipientAccountId
required
string = 24 characters

Internal recipient account ID within Tatum platform

amount
required
string <= 38 characters ^[+]?((\d+(\.\d*)?)|(\.\d+))$

Amount to be sent.

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

OK

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/transaction
Request samples
application/json
{
  • "senderAccountId": "5e6645712b55823de7ea82f1",
  • "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"
}

Send payment in batch

2 + 2 * N per API call. (N - count of transactions)


Sends the N payments within Tatum Private Ledger. All assets are settled instantly.
When a transaction is settled, 2 transaction records are created, 1 for each of the participants. These 2 records are connected via a transaction reference, which is the same for both of them.
This method is only used for transferring assets between accounts within Tatum and will not send any funds to blockchain addresses.
If there is an insufficient balance in the sender account, no transaction is recorded.
It is possible to perform an anonymous transaction where the sender account is not visible for the recipient.
The FIAT currency value of every transaction is calculated automatically. The FIAT value is based on the accountingCurrency of the account connected to the transaction and is available in the marketValue parameter of the transaction.

SecurityX-API-Key
Request
Request Body schema: application/json
senderAccountId
required
string = 24 characters

Internal sender account ID within Tatum platform

Array of objects

Array of block seals.

Array
recipientAccountId
required
string = 24 characters

Internal recipient account ID within Tatum platform

amount
required
string <= 38 characters ^[+]?((\d+(\.\d*)?)|(\.\d+))$

Amount to be sent.

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

OK

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/transaction/batch
Request samples
application/json
{
  • "senderAccountId": "5e6645712b55823de7ea82f1",
  • "transaction": [
    ]
}
Response samples
application/json
[
  • {
    }
]

Find transactions for account.

1 credit per API call.


Finds transactions for the account identified by the given account ID.

SecurityX-API-Key
Request
query Parameters
pageSize
number [ 1 .. 50 ]

Max number of items per page is 50. Either count or pageSize is accepted.

Example: pageSize=10
offset
number

Offset to obtain the next page of data.

Example: offset=0
count
boolean

Get the total transaction count based on the filter. Either count or pageSize is accepted.

Example: count=true
Request Body schema: application/json
id
required
string = 24 characters

Account ID - source of transaction(s).

counterAccount
string = 24 characters

Counter account - transaction(s) destination account.

from
integer <int64> >= 0

Starting date to search for transactions from in UTC millis. If not present, search all history.

to
integer <int64> >= 0

Date until to search for transactions in UTC millis. If not present, search up till now.

currency
string [ 1 .. 50 ] characters

Currency of the transactions.

Array of objects

Amount of the transaction. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

currencies
Array of strings

List of currencies of the transactions.

transactionType
any

Type of payment

Enum: "FAILED" "DEBIT_PAYMENT" "CREDIT_PAYMENT" "CREDIT_DEPOSIT" "DEBIT_WITHDRAWAL" "CANCEL_WITHDRAWAL" "DEBIT_OUTGOING_PAYMENT" "EXCHANGE_BUY" "EXCHANGE_SELL" "DEBIT_TRANSACTION" "CREDIT_INCOMING_PAYMENT"
transactionTypes
Array of strings

Types of payment

Items Enum: "FAILED" "DEBIT_PAYMENT" "CREDIT_PAYMENT" "CREDIT_DEPOSIT" "DEBIT_WITHDRAWAL" "CANCEL_WITHDRAWAL" "DEBIT_OUTGOING_PAYMENT" "EXCHANGE_BUY" "EXCHANGE_SELL" "DEBIT_TRANSACTION" "CREDIT_INCOMING_PAYMENT"
opType
string

Type of operation

Enum: "PAYMENT" "WITHDRAWAL" "BLOCKCHAIN_TRANSACTION" "EXCHANGE" "FAILED" "DEPOSIT" "MINT" "REVOKE"
transactionCode
string [ 1 .. 100 ] characters

For bookkeeping to distinct transaction purpose.

paymentId
string [ 1 .. 100 ] characters

Payment ID defined in payment order by sender.

recipientNote
string [ 1 .. 500 ] characters

Recipient note defined in payment order by sender.

senderNote
string [ 1 .. 500 ] characters

Sender note defined in payment order by sender.

Responses
200

OK

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.

post/v3/ledger/transaction/account
Request samples
application/json
{
  • "id": "5e6be8e9e6aa436299950c41",
  • "counterAccount": "5e6be8e9e6aa436299950c41",
  • "from": 1571833231000,
  • "to": 1571833231000,
  • "currency": "BTC",
  • "amount": [
    ],
  • "currencies": [
    ],
  • "transactionType": "FAILED",
  • "transactionTypes": [
    ],
  • "opType": "PAYMENT",
  • "transactionCode": "1_01_EXTERNAL_CODE",
  • "paymentId": "65426",
  • "recipientNote": "65426",
  • "senderNote": "65426"
}
Response samples
application/json
[ ]

Find transactions for a customer across all of the customer's accounts.

1 credit per API call.


Finds transactions for all accounts of the customer identified by the given internal customer ID.

SecurityX-API-Key
Request
query Parameters
pageSize
number [ 1 .. 50 ]

Max number of items per page is 50. Either count or pageSize is accepted.

Example: pageSize=10
offset
number

Offset to obtain the next page of data.

Example: offset=0
count
boolean

Get total transaction count based on the filter. Either count or pageSize is accepted.

Example: count=true
Request Body schema: application/json
id
required
string = 24 characters

Customer internal ID to search for.

account
string = 24 characters

Source account - source of transaction(s).

counterAccount
string = 24 characters

Counter account - transaction(s) destination account.

currency
string [ 1 .. 50 ] characters

Currency of the transactions.

from
integer <int64> >= 0

Starting date to search for transactions from in UTC millis. If not present, search all history.

to
integer <int64> >= 0

Date until to search for transactions in UTC millis. If not present, search up till now.

Array of objects

Amount of the transaction. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

currencies
Array of strings

List of currencies of the transactions.

transactionType
any

Type of payment

Enum: "FAILED" "DEBIT_PAYMENT" "CREDIT_PAYMENT" "CREDIT_DEPOSIT" "DEBIT_WITHDRAWAL" "CANCEL_WITHDRAWAL" "DEBIT_OUTGOING_PAYMENT" "EXCHANGE_BUY" "EXCHANGE_SELL" "DEBIT_TRANSACTION" "CREDIT_INCOMING_PAYMENT"
transactionTypes
Array of strings

Types of payment

Items Enum: "FAILED" "DEBIT_PAYMENT" "CREDIT_PAYMENT" "CREDIT_DEPOSIT" "DEBIT_WITHDRAWAL" "CANCEL_WITHDRAWAL" "DEBIT_OUTGOING_PAYMENT" "EXCHANGE_BUY" "EXCHANGE_SELL" "DEBIT_TRANSACTION" "CREDIT_INCOMING_PAYMENT"
opType
string

Type of operation.

Enum: "PAYMENT" "WITHDRAWAL" "BLOCKCHAIN_TRANSACTION" "EXCHANGE" "FAILED" "DEPOSIT" "MINT" "REVOKE"
transactionCode
string [ 1 .. 100 ] characters

For bookkeeping to distinct transaction purpose.

paymentId
string [ 1 .. 100 ] characters

Payment ID defined in payment order by sender.

recipientNote
string [ 1 .. 500 ] characters

Recipient note defined in payment order by sender.

senderNote
string [ 1 .. 500 ] characters

Sender note defined in payment order by sender.

Responses
200

OK

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.

post/v3/ledger/transaction/customer
Request samples
application/json
{
  • "id": "5e6be8e9e6aa436299950c41",
  • "account": "5e6be8e9e6aa436299950c41",
  • "counterAccount": "5e6be8e9e6aa436299950c41",
  • "currency": "BTC",
  • "from": 1571833231000,
  • "to": 1571833231000,
  • "amount": [
    ],
  • "currencies": [
    ],
  • "transactionType": "FAILED",
  • "transactionTypes": [
    ],
  • "opType": "PAYMENT",
  • "transactionCode": "1_01_EXTERNAL_CODE",
  • "paymentId": "65426",
  • "recipientNote": "65426",
  • "senderNote": "65426"
}
Response samples
application/json
[ ]

Find transactions within the ledger.

1 credit per API call.


Find transactions across whole ledger.

SecurityX-API-Key
Request
query Parameters
pageSize
number [ 1 .. 50 ]

Max number of items per page is 50. Either count or pageSize is accepted.

Example: pageSize=10
offset
number

Offset to obtain the next page of data.

Example: offset=0
count
boolean

Get the total transaction count based on the filter. Either count or pageSize is accepted.

Example: count=true
Request Body schema: application/json
account
string = 24 characters

Source account - source of transaction(s).

counterAccount
string = 24 characters

Counter account - transaction(s) destination account.

currency
string [ 1 .. 50 ] characters

Currency of the transactions.

from
integer <int64> >= 0

Starting date to search for transactions from in UTC millis. If not present, search all history.

Array of objects

Amount of the transaction. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

currencies
Array of strings

List of currencies of the transactions.

transactionType
any

Type of payment

Enum: "FAILED" "DEBIT_PAYMENT" "CREDIT_PAYMENT" "CREDIT_DEPOSIT" "DEBIT_WITHDRAWAL" "CANCEL_WITHDRAWAL" "DEBIT_OUTGOING_PAYMENT" "EXCHANGE_BUY" "EXCHANGE_SELL" "DEBIT_TRANSACTION" "CREDIT_INCOMING_PAYMENT"
transactionTypes
Array of strings

Types of payment

Items Enum: "FAILED" "DEBIT_PAYMENT" "CREDIT_PAYMENT" "CREDIT_DEPOSIT" "DEBIT_WITHDRAWAL" "CANCEL_WITHDRAWAL" "DEBIT_OUTGOING_PAYMENT" "EXCHANGE_BUY" "EXCHANGE_SELL" "DEBIT_TRANSACTION" "CREDIT_INCOMING_PAYMENT"
opType
string

Type of operation.

Enum: "PAYMENT" "WITHDRAWAL" "BLOCKCHAIN_TRANSACTION" "EXCHANGE" "FAILED" "DEPOSIT" "MINT" "REVOKE"
transactionCode
string [ 1 .. 100 ] characters

For bookkeeping to distinct transaction purpose.

paymentId
string [ 1 .. 100 ] characters

Payment ID defined in payment order by sender.

recipientNote
string [ 1 .. 500 ] characters

Recipient note defined in payment order by sender.

senderNote
string [ 1 .. 500 ] characters

Sender note defined in payment order by sender.

to
integer <int64> >= 0

Date until to search for transactions in UTC millis. If not present, search up till now.

Responses
200

OK

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.

post/v3/ledger/transaction/ledger
Request samples
application/json
{
  • "account": "5e6be8e9e6aa436299950c41",
  • "counterAccount": "5e6be8e9e6aa436299950c41",
  • "currency": "BTC",
  • "from": 1571833231000,
  • "amount": [
    ],
  • "currencies": [
    ],
  • "transactionType": "FAILED",
  • "transactionTypes": [
    ],
  • "opType": "PAYMENT",
  • "transactionCode": "1_01_EXTERNAL_CODE",
  • "paymentId": "65426",
  • "recipientNote": "65426",
  • "senderNote": "65426",
  • "to": 1571833231000
}
Response samples
application/json
[ ]

Find transactions with a given reference across all accounts.

1 credit per API call.


Finds transactions for all accounts with the given reference.

SecurityX-API-Key
Request
path Parameters
reference
required
string [ 20 .. 100 ] characters
Responses
200

OK

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/transaction/reference/{reference}
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/ledger/transaction/reference/{reference}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]
➔ Next to Customer