Withdrawal

Store withdrawal

2 credits per API call.


Create a withdrawal from Tatum Ledger account to the blockchain.

BTC, LTC, DOGE, BCH

When withdrawal from Tatum is executed, all deposits, which are not processed yet are used as an input and change is moved to pool address 0 of wallet for defined account's xpub. If there are no unspent deposits, only last pool address 0 UTXO is used. If balance of wallet is not sufficient, it is impossible to perform withdrawal from this account -> funds were transferred to another linked wallet within system or outside of Tatum visibility.
For the first time of withdrawal from wallet, there must be some deposit made and funds are obtained from that. Since there is no withdrawal, there was no transfer to pool address 0 and thus it is not present in vIn. Pool transfer is identified by missing data.address property in response. When last not cancelled withdrawal is not completed and thus there is no tx id of output transaction given, we cannot perform next withdrawal.

ETH

Withdrawal from Tatum can be processed only from 1 account. In Ethereum Blockchain, each address is recognized as an account and only funds from that account can be sent in 1 transaction. Example: Account A has 0.5 ETH, Account B has 0.3 ETH. Account A is linked to Tatum Account 1, Account B is linked to Tatum Account 2. Tatum Account 1 has balance 0.7 Ethereum and Tatum Account 2 has 0.1 ETH. Withdrawal from Tatum Account 1 can be at most 0.5 ETH, even though balance in Tatum Private Ledger is 0.7 ETH. Because of this Ethereum Blockchain limitation, withdrawal request should always contain sourceAddress, from which withdrawal will be made. To get available balances for Ethereum wallet accounts, use hint endpoint.

XRP

XRP withdrawal can contain DestinationTag except of address, which is placed in attr parameter of withdrawal request. SourceTag of the blockchain transaction should be withdrawal ID for autocomplete purposes of withdrawals.

XLM

XLM withdrawal can contain memo except of address, which is placed in attr parameter of withdrawal request. XLM blockchain does not have possibility to enter source account information. It is possible to create memo in format 'destination|source', which is supported way of memo in Tatum and also there is information about the sender account in the blockchain.


When withdrawal is created, all other withdrawals with the same currency are pending, unless the current one is marked as complete or cancelled.
Tatum ledger transaction is created for every withdrawal request with operation type WITHDRAWAL. The value of the transaction is the withdrawal amount + blockchain fee, which should be paid. In the situation, when there is withdrawal for ERC20, XLM, or XRP based custom assets, the fee is not included in the transaction because it is paid in different assets than the withdrawal itself.

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

Sender account ID

address
required
string [ 1 .. 10000 ] characters

Blockchain address to send assets to. For BTC, LTC, DOGE and BCH, it is possible to enter list of multiple recipient blockchain addresses as a comma separated string.

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

Amount to be withdrawn to blockchain.

attr
string [ 1 .. 64 ] characters

Used to parametrize withdrawal. Used for XRP withdrawal to define destination tag of recipient, or XLM memo of the recipient, if needed.
For Bitcoin, Litecoin, Bitcoin Cash, used as a change address for left coins from transaction.

compliant
boolean

Compliance check, if withdrawal is not compliant, it will not be processed.

fee
required
string^[+]?((\d+(\.\d*)?)|(\.\d+))$

Fee to be submitted as a transaction fee to blockchain.

multipleAmounts
Array of strings

For BTC, LTC, DOGE and BCH, it is possible to enter list of multiple recipient blockchain amounts. List of recipient addresses must be present in the address field and total sum of amounts must be equal to the amount field.

paymentId
string [ 1 .. 100 ] characters

Identifier of the payment, shown for created Transaction within Tatum sender account.

senderNote
string [ 1 .. 500 ] characters

Note visible to owner of withdrawing account

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

500

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

post/v3/offchain/withdrawal
Request samples
application/json
{
  • "senderAccountId": "5e68c66581f2ee32bc354087",
  • "address": "mpTwPdF8up9kidgcAStriUPwRdnE9MRAg7",
  • "amount": "0.001",
  • "attr": "12345",
  • "compliant": false,
  • "fee": "0.0005",
  • "multipleAmounts": [
    ],
  • "paymentId": "12345",
  • "senderNote": "Sender note"
}
Response samples
application/json
{
  • "reference": "5e6be8e9e6aa436299950c41",
  • "data": [
    ],
  • "id": "5e68c66581f2ee32bc354087"
}

Get withdrawals

1 credit per API call.


Get withdrawals.

SecurityX-API-Key
Request
query Parameters
currency
string [ 2 .. 30 ] characters

Currency of the withdrawal

Example: currency=BTC
status
string

Status of the withdrawal

Enum: "InProgress" "Done" "Cancelled"
Example: status=Done
pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

Example: pageSize=10
offset
number

Offset to obtain next page of the data.

Example: offset=0
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/offchain/withdrawal
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/offchain/withdrawal?currency=BTC&status=Done&pageSize=10&offset=0' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Complete withdrawal

2 credits per API call.


Invoke complete withdrawal as soon as blockchain transaction ID is available. All other withdrawals for the same currency will be pending unless the last one is processed and marked as completed.

SecurityX-API-Key
Request
path Parameters
id
required
string [ 10 .. 50 ] characters

ID of created withdrawal

txId
required
string [ 10 .. 80 ] characters

Blockchain transaction ID of created withdrawal

Responses
204

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

500

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

put/v3/offchain/withdrawal/{id}/{txId}
Request samples
curl -i -X PUT \
  'https://api-eu1.tatum.io/v3/offchain/withdrawal/{id}/{txId}' \
  -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": [
    ]
}

Cancel withdrawal

1 credit per API call.


This method is helpful if you need to cancel the withdrawal if the blockchain transaction fails or is not yet processed. This does not cancel already broadcast blockchain transaction, only Tatum internal withdrawal, and the ledger transaction, that was linked to this withdrawal.
By default, the transaction fee is included in the reverted transaction. There are situations, like sending ERC20 on ETH, TRC token on TRON, XLM or XRP based assets, when the fee should not be reverted, because e.g. the fee is in calculated in Ethereum and transaction was in ERC20 currency. In this situation, only the transaction amount should be reverted, not the fee.

SecurityX-API-Key
Request
path Parameters
id
required
string = 24 characters

ID of created withdrawal

query Parameters
revert
boolean
Default: true

Defines whether fee should be reverted to account balance as well as amount. Defaults to true. Revert true would be typically used when withdrawal was not broadcast to blockchain. False is used usually for Ethereum based currencies when gas was consumed but transaction was reverted.

Example: revert=true
Responses
204

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

500

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

delete/v3/offchain/withdrawal/{id}
Request samples
curl -i -X DELETE \
  'https://api-eu1.tatum.io/v3/offchain/withdrawal/{id}?revert=true' \
  -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": [
    ]
}

Broadcast signed transaction and complete withdrawal

2 credits per API call.


Broadcast signed raw transaction end complete withdrawal associated with it. When broadcast succeeded but it is impossible to complete withdrawal, transaction id of transaction is returned and withdrawal must be completed manually.

SecurityX-API-Key
Request
Request Body schema: application/json
currency
required
string [ 2 .. 40 ] characters

Currency of signed transaction to be broadcast, BTC, LTC, DOGE, BNB, XLM, TRX, BCH, ETH, XRP, ERC20, TRC20

txData
required
string [ 1 .. 500000 ] characters

Raw signed transaction to be published to network.

withdrawalId
string = 24 characters

Withdrawal ID to be completed by transaction broadcast

signatureId
string <uuid> = 36 characters

ID of prepared payment template to sign. This is should be stored on a client side to retrieve ID of the blockchain transaction, when signing application signs the transaction and broadcasts it to the blockchain.

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

500

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

post/v3/offchain/withdrawal/broadcast
Request samples
application/json
{
  • "currency": "BTC",
  • "txData": "62BD544D1B9031EFC330A3E855CC3A0D51CA5131455C1AB3BCAC6D243F65460D",
  • "withdrawalId": "5e68c66581f2ee32bc354087",
  • "signatureId": "1f7f7c0c-3906-4aa1-9dfe-4b67c43918f6"
}
Response samples
application/json
{
  • "completed": true,
  • "txId": "62BD544D1B9031EFC330A3E855CC3A0D51CA5131455C1AB3BCAC6D243F65460D"
}