Links

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:
curl -X POST https://api.taal.com/api/v1/broadcast
curl -X POST https://api.taal.com/api/v1/batchBroadcast
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
{
"rawTx": "bitcoin transaction in hex..."
}
Response, if successful:
201 Created
text/plain
<32 byte TXID in 64 hexadecimal characters>
Response, if not successful
400 Bad request
application/json
{
"status": number,
"code": number,
"error": "string"
}
These are the exact responses returned by the bitcoin node.

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

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

/api/v1/batchBroadcast (application/json)

Request body
[
{
"rawTx": "bitcoin transaction in hex..."
},
{
"rawTx": "bitcoin transaction in hex..."
},
....
]

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

Request body
one or more bitcoin transactions as a stream of bytes (binary)
Response for both text and binary requests:
200 OK
application/json
{
"txs": [
{
"txid": "<32 byte TXID in 64 hexadecimal characters>",
"returnResult": "success or failure",
"resultDescription": "string"
}
],
"failureCount": number
}
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:
mkdir example
cd example
npm init -y
npm install [email protected]
npm install request
  1. 1.
    Save the following code to a main.js in your example folder:
const fs = require('fs')
const bsv = require('bsv')
// Random key produced each time...
const newKey = bsv.PrivateKey()
console.log(`Private key: ${newKey.toString()}`)
console.log(`Mainnet address: ${newKey.toAddress('mainnet').toString()}`)
console.log(`
1. Create a funding transaction by sending 1000 satoshis (0.00001 BSV) to ${newKey.toAddress('mainnet').toString()}.
2. Add your Taal apiKey, and funding transaction txid and vout to 'generated.js'.
3. Execute the generated code:
node generated.js
`)
fs.writeFileSync('generated.js', `
const bsv = require('bsv')
var request = require('request')
const privKey = bsv.PrivateKey('${newKey}')
const apiKey = "" // Add Taal mainnet API Key
const fundingTxid = "" // Add the funding transaction txid
const fundingVout = -1 // Replace with funding transaction vout
const returnAddress = "" // The address to return the 1000 satoshis (less fees)
if (apiKey === "" || fundingTxid === "" || fundingVout === -1 || returnAddress === "") {
console.log('This generated file needs an apiKey, a fundingTxid, a fundingVout and a returnAddress')
process.exit(1)
}
const utxo1 = {
txId: fundingTxid,
outputIndex: fundingVout,
address: privKey.toAddress('mainnet').toString(),
script: bsv.Script.buildPublicKeyHashOut(privKey.publicKey).toHex(),
satoshis: 1000
}
const tx1 = bsv.Transaction()
.from(utxo1)
.to(privKey.toAddress('mainnet').toString(), 800)
.change(returnAddress)
.sign(privKey)
const utxo2 = {
txId: tx1.hash,
outputIndex: 0,
address: privKey.toAddress('mainnet').toString(),
script: bsv.Script.buildPublicKeyHashOut(privKey.publicKey).toHex(),
satoshis: 800
}
const tx2 = bsv.Transaction()
.from(utxo2)
.change(returnAddress)
.sign(privKey)
const txBuffer = Buffer.concat([
tx1.toBuffer(),
tx2.toBuffer()
])
// Send the transaction to Taal API...
request.post({
url: 'https://api.taal.com/api/v1/batchBroadcast',
headers: {
'Authorization': apiKey,
'Content-Type': 'application/octet-stream'
},
body: txBuffer
}, function(error, response, body) {
console.log(error, response.statusCode, body)
})
`)
  1. 1.
    Execute the code and follow the onscreen instructions:
node main.js