How to send a Bitcoin transaction
With Tatum, you can choose from two options how to send a Bitcoin transaction:
- Enter a list of blockchain addresses from which the assets will be sent
- Enter specific Unspent Transaction Outputs (UTXO) which will be used to send the assets
Ensure that you fully understand how Bitcoin transactions work and how the transaction fees are charged.
The Bitcoin blockchain is not account-based but transaction-based. You operate with a list of previously received transactions and the assets within them. This means that you can use multiple transactions in one transaction as a source of your assets, not just one specific address. To learn more, see this Investopedia article.
- When you enter a list of addresses, all incoming transactions that have not been used previously are used as a source.
- When you enter a list of UTXOs, only specific unspent transactions that belong to you are used.
All of the assets that belong to the specific transaction are used as input, not only a fraction of them. To learn more about Bitcoin transactions, check out this article.
Before you actually make a transaction and send BTC, make sure that:
- You know how much BTC you want to send and to whom.
- You have defined a list of recipient addresses with the specific amounts that each address is to receive.
The sum of the assets that you send must be bigger than the sum of the assets that are expected to be received, and the difference must be sufficient to cover the transaction fee that will be paid to the network.
In other words, you must send more funds than expected to cover the transaction fees. This works similar to international wire transfers where you have to pay fees to the banks that handle your transaction.
For example, you want send 9 BTC to three recipients, each of which should receive 3 BTC. To cover the fees, you must send (3*3)+1=10 BTC. The fee will be 1 BTC.
You may not always be able to control exactly how much BTC is available to be sent, especially when you send assets from multiple addresses.
The difference between the sum of the assets that you send and the sum of the assets that are expected to be received may be considerable. You may not want to spend it all on the transaction fee.
In this situation, you can explicitly specify the fee amount that you are willing to pay and the blockchain address where any extra funds remaining after covering the fee will be sent.
The following sample request shows how to send BTC from a list of addresses and from a list of UTXOs, with the fee amount set to 0.00001 BTC (the
fee parameter) and the specified address to return any extra funds to (the changeAddress parameter):JavaScript
cURL: List of addresses as a source
cURL: List of UTXOs as a source
1
import { TatumBtcSDK } from '@tatumio/btc';
2
import { YOUR_API_KEY_HERE } from '@tatumio/shared-testing-common';
3
4
const btcSDK = TatumBtcSDK({ apiKey: YOUR_API_KEY_HERE });
5
6
// If the source is a list of blockchain addresses
7
8
const bodyFromAddress = {
9
fromAddress: [
10
{
11
address: 'mhuKgqf7SLRWPX8Sfrqn68i5YcdWsFMRXF',
12
privateKey: 'cNkXKkQ4YoNS2LmnvhtGqWBQKg7oo3BRaowPhSDPvTRjxXyGG6yr',
13
},
14
{
15
address: 'yxtely677ucyrrwt0k6ehzrm2gkztb1q9x2gqftthj',
16
privateKey: 'cQ1YZMep3CiAnMTA9y62ha6BjGaaTFsTvtDuGmucGvpAVmS89khV',
17
},
18
],
19
to: [
20
{
21
address: 'n1XD955iuticPuKoJJr8XfAjDw2gYadNrR',
22
value: 0.00015,
23
},
24
{
25
address: 'mgSXLa5sJHvBpYTKZ62aW9z2YWQNTJ59Zm',
26
value: 0.000009,
27
},
28
],
29
fee: '0.00001',
30
changeAddress: 'tb1q9x2gqftyxterwt0k6ehzrm2gkzthjly677ucyr',
31
};
32
33
// If the source is a list of UTXOs
34
35
const bodyFromUTXO = {
36
fromUTXO: [
37
{
38
txHash: '887dd5221800c65ada2a2081e65a14b5421b30600d4ab112421a44b17ded6ed4',
39
index: 0,
40
privateKey: 'cNkXKkQ4YoNS2LmnvhtGqWBQKg7oo3BRaowPhSDPvTRjxXyGG6yr',
41
},
42
{
43
txHash: 'b2dc763cf75373ad14c984c07846f5425c20ddf34606debb0a148cd770528ef9',
44
index: 1,
45
privateKey: 'cNUHqqs67WVhMZP9hH3i9nLQ1BGEasA87y6N6SQMsfYaBaPi9SEs',
46
},
47
],
48
to: [
49
{
50
address: 'n1XD955iuticPuKoJJr8XfAjDw2gYadNrR',
51
value: 0.00015,
52
},
53
{
54
address: 'mgSXLa5sJHvBpYTKZ62aW9z2YWQNTJ59Zm',
55
value: 0.000009,
56
},
57
],
58
fee: '0.00001',
59
changeAddress: 'tb1q9x2gqftyxterwt0k6ehzrm2gkzthjly677ucyr',
60
};
61
62
63
const txDataFromAddress = await btcSDK.transaction.sendTransaction(bodyFromAddress, { testnet: true });
64
const txDataFromUTXO = await btcSDK.transaction.sendTransaction(bodyFromUTXO, { testnet: true });
1
curl --location --request POST 'https://api.tatum.io/v3/bitcoin/transaction' \
2
--header 'x-api-key: YOUR_API_KEY_HERE' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"fromAddress": [
6
{
7
"address": "mhuKgqf7SLRWPX8Sfrqn68i5YcdWsFMRXF",
8
"privateKey": "cNkXKkQ4YoNS2LmnvhtGqWBQKg7oo3BRaowPhSDPvTRjxXyGG6yr"
9
},
10
{
11
"address": "yxtely677ucyrrwt0k6ehzrm2gkztb1q9x2gqftthj",
12
"privateKey": "cQ1YZMep3CiAnMTA9y62ha6BjGaaTFsTvtDuGmucGvpAVmS89khV"
13
}
14
],
15
"to": [
16
{
17
"address": "n1XD955iuticPuKoJJr8XfAjDw2gYadNrR",
18
"value": 0.00015
19
},
20
{
21
"address": "mgSXLa5sJHvBpYTKZ62aW9z2YWQNTJ59Zm",
22
"value": 0.000009
23
}
24
],
25
"fee": "0.00001",
26
"changeAddress": "tb1q9x2gqftyxterwt0k6ehzrm2gkzthjly677ucyr"
27
}'
1
curl --location --request POST 'https://api.tatum.io/v3/bitcoin/transaction' \
2
--header 'x-api-key: YOUR_API_KEY_HERE' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"fromUTXO": [
6
{
7
"txHash": "887dd5221800c65ada2a2081e65a14b5421b30600d4ab112421a44b17ded6ed4",
8
"index": 0,
9
"privateKey": "cNkXKkQ4YoNS2LmnvhtGqWBQKg7oo3BRaowPhSDPvTRjxXyGG6yr"
10
},
11
{
12
"txHash": "b2dc763cf75373ad14c984c07846f5425c20ddf34606debb0a148cd770528ef9",
13
"index": 1,
14
"privateKey": "cNUHqqs67WVhMZP9hH3i9nLQ1BGEasA87y6N6SQMsfYaBaPi9SEs"
15
}
16
],
17
"to": [
18
{
19
"address": "n1XD955iuticPuKoJJr8XfAjDw2gYadNrR",
20
"value": 0.00015
21
},
22
{
23
"address": "mgSXLa5sJHvBpYTKZ62aW9z2YWQNTJ59Zm",
24
"value": 0.000009
25
}
26
],
27
"fee": "0.00001",
28
"changeAddress": "tb1q9x2gqftyxterwt0k6ehzrm2gkzthjly677ucyr"
29
}'
When using this API, you must sign the transaction with the private key of the blockchain address from which the fee will be deducted.
Providing the private key in the API is not a secure way of signing transactions, because the private key can be stolen or exposed. Your private keys should never leave your security perimeter. You should use the private keys only for testing a solution you are building on the testnet of a blockchain.
For signing transactions on the mainnet, we strongly recommend that you use the Tatum Key Management System (KMS) and provide the signature ID instead of the private key in the API. Alternatively, you can use the Tatum JavaScript client.
The API returns the ID of the transaction, from which you can get information about the transaction:
1
{
2
"txId": "962e4ad3781e7036ff3af6d880744fd3f06131c32d1085254da3cfa77b0e933f"
3
}
Once you have the transaction ID, get the details of the transaction.
The following sample request shows how to get the details of the Bitcoin transaction:
JavaScript
cURL
1
import { TatumBtcSDK } from '@tatumio/btc';
2
import { YOUR_API_KEY_HERE } from '@tatumio/shared-testing-common';
3
4
const btcSDK = TatumBtcSDK({ apiKey: YOUR_API_KEY_HERE });
5
6
const tx = await btcSDK.blockchain.getTransaction(
7
'962e4ad3781e7036ff3af6d880744fd3f06131c32d1085254da3cfa77b0e933f',
8
)
1
curl -i -X GET \
2
'https://api.tatum.io/v3/bitcoin/transaction/962e4ad3781e7036ff3af6d880744fd3f06131c32d1085254da3cfa77b0e933f' \
3
-H 'x-api-key: YOUR_API_KEY_HERE'
The API returns the detailed information about the transaction:
1
{
2
"txid": "962e4ad3781e7036ff3af6d880744fd3f06131c32d1085254da3cfa77b0e933f",
3
"hash": "962e4ad3781e7036ff3af6d880744fd3f06131c32d1085254da3cfa77b0e933f",
4
"size": 374,
5
"vsize": 374,
6
"version": 2,
7
"locktime": 0,
8
"vin": [
9
{
10
"txid": "b2dc763cf75373ad14c984c07846f5425c20ddf34606debb0a148cd770528ef9",
11
"scriptSig": {
12
"asm": "30450...c238a",
13
"hex": "48304...c238a"
14
},
15
"sequence": 4294967295,
16
"vout": 0
17
},
18
{
19
"txid": "b2dc763cf75373ad14c984c07846f5425c20ddf34606debb0a148cd770528ef9",
20
"scriptSig": {
21
"asm": "30450...c238a",
22
"hex": "48304...c238a"
23
},
24
"sequence": 4294967295,
25
"vout": 1
26
}
27
],
28
"vout": [
29
{
30
"value": 6e-7,
31
"n": 0,
32
"scriptPubKey": {
33
"asm": "OP_DUP OP_HASH160 0a21a...7d3a9 OP_EQUALVERIFY OP_CHECKSIG",
34
"hex": "76a9140a21a1144fd4f6892c111c00141932608d17d3a988ac",
35
"type": "PUBKEYHASH",
36
"reqSigs": 1,
37
"addresses": [
38
"mgSXLa5sJHvBpYTKZ62aW9z2YWQNTJ59Zm"
39
]
40
}
41
},
42
{
43
"value": 0.000006,
44
"n": 1,
45
"scriptPubKey": {
46
"asm": "OP_DUP OP_HASH160 0a21a...7d3a9 OP_EQUALVERIFY OP_CHECKSIG",
47
"hex": "76a9140a21a1144fd4f6892c111c00141932608d17d3a988ac",
48
"type": "PUBKEYHASH",
49
"reqSigs": 1,
50
"addresses": [
51
"mgSXLa5sJHvBpYTKZ62aW9z2YWQNTJ59Zm"
52
]
53
}
54
}
55
],
56
"blockhash": null,
57
"confirmations": 0,
58
"time": 1605903228,
59
"blocktime": 0,
60
"hex": "02000...00000"
61
}
Last modified 6mo ago