TAAL Transaction Endpoints
The simplest way to broadcast transactions to BSV is to use the broadcast and the batchBroadcast endpoints. /api/v1/broadcast expects a single transaction whilst /api/v1/batchBroadcast expects a batch of them.
With both of these it is possible to send your request as text with the application/json mimetype or binary with the application/octet-stream mimetype (discussed below).
The binary format has 2 advantages:
  1. 1.
    The size of the request payload is half of the text equivalent.
  2. 2.
    Unlike with JSON, the 1st transaction in the binary stream can be processed before the entire payload has been received.
The endpoints are:
1
curl -X POST https://api.taal.com/api/v1/broadcast
2
curl -X POST https://api.taal.com/api/v1/batchBroadcast
Copied!
Please note that these endpoints require a Taal APIKey that can be obtained for free by registering at https://console.taal.com

/api/v1/broadcast (application/json)

Request body
1
{
2
"rawTx": "bitcoin transaction in hex..."
3
}
Copied!
Response, if successful:
1
201 Created
2
text/plain
3
<32 byte TXID in 64 hexadecimal characters>
Copied!
Response, if not successful
1
400 Bad request
2
application/json
3
{
4
"status": number,
5
"code": number,
6
"error": "string"
7
}
Copied!
These are the exact responses returned by the bitcoin node.

/api/v1/broadcast (application/octet-stream)

Request body
1
bitcoin transaction as a stream of bytes (binary)
Copied!
Response, if successful:
1
201 Created
2
text/plain
3
<32 byte TXID in 64 hexadecimal characters>
Copied!

/api/v1/batchBroadcast (application/json)

Request body
1
[
2
{
3
"rawTx": "bitcoin transaction in hex..."
4
},
5
{
6
"rawTx": "bitcoin transaction in hex..."
7
},
8
....
9
]
Copied!

/api/v1/batchBroadcast (application/octet-stream)

Request body
1
one or more bitcoin transactions as a stream of bytes (binary)
Copied!
Response for both text and binary requests:
1
200 OK
2
application/json
3
{
4
"txs": [
5
{
6
"txid": "<32 byte TXID in 64 hexadecimal characters>",
7
"returnResult": "success or failure",
8
"resultDescription": "string"
9
}
10
],
11
"failureCount": number
12
}
Copied!
The resultDescription contains the exact responses returned by the bitcoin node for each transaction.

Javascript example using version 1 of bsv.js and request modules

  1. 1.
    Create a new nodejs project:
1
mkdir example
2
cd example
3
npm init -y
4
npm install [email protected]
5
npm install request
Copied!
  1. 1.
    Save the following code to a main.js in your example folder:
1
const fs = require('fs')
2
const bsv = require('bsv')
3
4
// Random key produced each time...
5
const newKey = bsv.PrivateKey()
6
7
console.log(`Private key: ${newKey.toString()}`)
8
console.log(`Mainnet address: ${newKey.toAddress('mainnet').toString()}`)
9
10
console.log(`
11
1. Create a funding transaction by sending 1000 satoshis (0.00001 BSV) to ${newKey.toAddress('mainnet').toString()}.
12
13
2. Add your Taal apiKey, and funding transaction txid and vout to 'generated.js'.
14
15
3. Execute the generated code:
16
17
node generated.js
18
19
`)
20
21
22
fs.writeFileSync('generated.js', `
23
const bsv = require('bsv')
24
var request = require('request')
25
26
const privKey = bsv.PrivateKey('${newKey}')
27
28
const apiKey = "" // Add Taal mainnet API Key
29
const fundingTxid = "" // Add the funding transaction txid
30
const fundingVout = -1 // Replace with funding transaction vout
31
const returnAddress = "" // The address to return the 1000 satoshis (less fees)
32
33
if (apiKey === "" || fundingTxid === "" || fundingVout === -1 || returnAddress === "") {
34
console.log('This generated file needs an apiKey, a fundingTxid, a fundingVout and a returnAddress')
35
process.exit(1)
36
}
37
38
const utxo1 = {
39
txId: fundingTxid,
40
outputIndex: fundingVout,
41
address: privKey.toAddress('mainnet').toString(),
42
script: bsv.Script.buildPublicKeyHashOut(privKey.publicKey).toHex(),
43
satoshis: 1000
44
}
45
46
const tx1 = bsv.Transaction()
47
.from(utxo1)
48
.to(privKey.toAddress('mainnet').toString(), 800)
49
.change(returnAddress)
50
.sign(privKey)
51
52
const utxo2 = {
53
txId: tx1.hash,
54
outputIndex: 0,
55
address: privKey.toAddress('mainnet').toString(),
56
script: bsv.Script.buildPublicKeyHashOut(privKey.publicKey).toHex(),
57
satoshis: 800
58
}
59
60
const tx2 = bsv.Transaction()
61
.from(utxo2)
62
.change(returnAddress)
63
.sign(privKey)
64
65
66
const txBuffer = Buffer.concat([
67
tx1.toBuffer(),
68
tx2.toBuffer()
69
])
70
71
// Send the transaction to Taal API...
72
request.post({
73
url: 'https://api.taal.com/api/v1/batchBroadcast',
74
headers: {
75
'Authorization': apiKey,
76
'Content-Type': 'application/octet-stream'
77
},
78
body: txBuffer
79
}, function(error, response, body) {
80
console.log(error, response.statusCode, body)
81
})
82
`)
Copied!
  1. 1.
    Execute the code and follow the onscreen instructions:
1
node main.js
Copied!
Export as PDF
Copy link
Contents