Introduction
MatterCloud is a Bitcoin SV blockchain API for developers.
Query wallet addresses, transactions, and broadcast transactions with the REST API.
Features:
- Query utxos and balances for addresses and scripthashes
- Transaction history
- Send and broadcast transactions
Contact
Contact us for feedback and questions, we love to hear your feedback.
Authentication
Get your API credentials at https://www.mattercloud.net with 'Get API Key' to generate a new key.
The param api_key
must be passed in as URL query params or HTTP headers.
Example:
GET https://api.mattercloud.net/api/v3/main/address/12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX/utxo?api_key=your-api-key
HTTP headers:
api_key: YOUR_API_KEY
GET https://api.mattercloud.net/api/v3/main/address/12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX/balance?api_key=your-api-key
Rate Limits
See Plans page for rate limits.
Address
Get balance
curl "https://api.mattercloud.net/api/v3/main/address/12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX/balance" -H "api_key: your-api-key"
const matter = require('mattercloudjs');
const result = await matter.getBalance('12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX');
The above command returns JSON structured like this:
{
"address": "12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX",
"confirmed": 30055,
"unconfirmed": 0
}
This endpoint retrieves balance for a specific address.
HTTP Request
GET https://api.mattercloud.net/api/v3/main/address/<address>/balance
URL Parameters
Parameter | Description |
---|---|
address | The address to retrieve balance for |
Get balance batch
curl -X POST https://api.mattercloud.net/api/v3/main/address/balance -H 'Content-Type: application/json' \
-H 'Content-Type: application/json' \
-H "api_key: your-api-key" \
-d '{ "addrs": "1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H,12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX"}'
curl -X 'POST' "https://api.mattercloud.net/api/v3/main/address/balance" -H "api_key: your-api-key"
const matter = require('mattercloudjs');
const result = await matter.getBalanceBatch(['1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H', '12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX']);
The above command returns JSON structured like this:
[
{
"address": "1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H",
"confirmed": 0,
"unconfirmed": 0
},
{
"address": "12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX",
"confirmed": 30055,
"unconfirmed": 0
}
]
This endpoint retrieves balances for multiple addresses at same time
HTTP Request
POST https://api.mattercloud.net/api/v3/main/address/balance
Request Body
Parameter | Description |
---|---|
addrs | The addresses to retrieve balance for. Comma-seperated values. |
Get utxos
curl "https://api.mattercloud.net/api/v3/main/address/12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX/utxo" -H "api_key: your-api-key"
const matter = require('mattercloudjs');
const result = await matter.getUtxos('12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX');
The above command returns JSON structured like this:
[
{
"address": "12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX",
"txid": "5e3014372338f079f005eedc85359e4d96b8440e7dbeb8c35c4182e0c19a1a12",
"vout": 0,
"amount": 0.00015399,
"satoshis": 15399,
"value": 15399,
"height": 576168,
"confirmations": 34992,
"scriptPubKey": "76a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac",
"script": "76a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac",
"outputIndex": 0
}
]
This endpoint retrieves utxos for a specific address.
HTTP Request
GET https://api.mattercloud.net/api/v3/main/address/<address>/utxo
URL Parameters
Parameter | Description |
---|---|
address | The address to retrieve utxos for |
Get utxos batch
curl -X POST https://api.mattercloud.net/api/v3/main/address/utxo -H 'Content-Type: application/json' \
-H 'Content-Type: application/json' \
-H "api_key: your-api-key" \
-d '{ "addrs": "1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H,12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX"}'
const matter = require('mattercloudjs');
const result = await matter.getUtxosBatch(['1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H', '12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX']);
The above command returns JSON structured like this:
[
{
"address": "12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX",
"txid": "5e3014372338f079f005eedc85359e4d96b8440e7dbeb8c35c4182e0c19a1a12",
"vout": 0,
"amount": 0.00015399,
"satoshis": 15399,
"value": 15399,
"height": 576168,
"confirmations": 34993,
"scriptPubKey": "76a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac",
"script": "76a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac",
"outputIndex": 0
}
]
This endpoint retrieves utxos for multiple addresses
HTTP Request
POST https://api.mattercloud.net/api/v3/main/address/utxo
Request Body
Parameter | Description |
---|---|
addrs | The addresses to retrieve utxos for. Comma-seperated values. |
Get history
curl "https://api.mattercloud.net/api/v3/main/address/12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX/history" -H "api_key: your-api-key"
const matter = require('mattercloudjs');
const result = await matter.getHistory('12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX');
The above command returns JSON structured like this:
{
"from": 0,
"to": 20,
"results": [
{
"txid": "5e3014372338f079f005eedc85359e4d96b8440e7dbeb8c35c4182e0c19a1a12",
"height": 576168
},
{
"txid": "bdf6f49776faaa4790af3e41b8b474a7d0d47df540f8d71c3579dc0addd64c45",
"height": 576025
},
{
"txid": "d834682a5d29646427e5627d38c10224036535fa7e3066ae2f7a163a96550e27",
"height": 576025
},
{
"txid": "96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6",
"height": 576025
}
]
}
This endpoint retrieves history for a specific address.
HTTP Request
GET https://api.mattercloud.net/api/v3/main/address/<address>/history
URL Parameters
Parameter | Description |
---|---|
address | The address to retrieve history for |
Get history batch
curl -X POST https://api.mattercloud.net/api/v3/main/address/history -H 'Content-Type: application/json' \
-H 'Content-Type: application/json' \
-H "api_key: your-api-key" \
-d '{ "addrs": "1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H,12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX"}'
const matter = require('mattercloudjs');
const result = await matter.getHistoryBatch(['1GJ3x5bcEnKMnzNFPPELDfXUCwKEaLHM5H', '12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX']);
The above command returns JSON structured like this:
{
"from": 0,
"to": 20,
"results": [
{
"height": 576168,
"txid": "5e3014372338f079f005eedc85359e4d96b8440e7dbeb8c35c4182e0c19a1a12"
},
{
"height": 576025,
"txid": "bdf6f49776faaa4790af3e41b8b474a7d0d47df540f8d71c3579dc0addd64c45"
},
{
"height": 576025,
"txid": "d834682a5d29646427e5627d38c10224036535fa7e3066ae2f7a163a96550e27"
},
{
"height": 576025,
"txid": "96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6"
}
]
}
This endpoint retrieves history for multiple addresses
HTTP Request
POST https://api.mattercloud.net/api/v3/main/address/history
Request Body
Parameter | Description |
---|---|
addrs | The addresses to retrieve history for. Comma-seperated values. |
ScriptHash
Get utxos
curl "https://api.mattercloud.net/api/v3/main/scripthash/03b508a9da0879dd55619e06f5bd656696f77ba879aaa99e0eb22cedd7dd4846/utxo" -H "api_key: your-api-key"
const matter = require('mattercloudjs');
const result = await matter.getScriptHashUtxos('03b508a9da0879dd55619e06f5bd656696f77ba879aaa99e0eb22cedd7dd4846');
The above command returns JSON structured like this:
[
{
"scripthash": "03b508a9da0879dd55619e06f5bd656696f77ba879aaa99e0eb22cedd7dd4846",
"txid": "dc36f3baa9b7e96827928760c07a160579b0a531814e3a3900c1c4112c4a92e7",
"vout": 0,
"amount": 0.00004363,
"satoshis": 4363,
"value": 4363,
"height": 625311,
"confirmations": 72,
"outputIndex": 0
}
]
This endpoint retrieves utxos for a specific scripthash.
HTTP Request
GET https://api.mattercloud.net/api/v3/main/scripthash/<scripthash>/utxo
URL Parameters
Parameter | Description |
---|---|
scripthash | Script hash: sha256 hash of the binary bytes of the locking script (ScriptPubKey), expressed as a hexadecimal string. |
Get history
curl "https://api.mattercloud.net/api/v3/main/scripthash/03b508a9da0879dd55619e06f5bd656696f77ba879aaa99e0eb22cedd7dd4846/history" -H "api_key: your-api-key"
const matter = require('mattercloudjs');
const result = await matter.getScriptHashHistory('03b508a9da0879dd55619e06f5bd656696f77ba879aaa99e0eb22cedd7dd4846');
The above command returns JSON structured like this:
{
"from": 0,
"to": 20,
"results": [
{
"height": 625311,
"txid": "dc36f3baa9b7e96827928760c07a160579b0a531814e3a3900c1c4112c4a92e7"
}
]
}
This endpoint retrieves history for a specific scripthash.
HTTP Request
GET https://api.mattercloud.net/api/v3/main/scripthash/<scriphash>/history
URL Parameters
Parameter | Description |
---|---|
scripthash | Script hash: sha256 hash of the binary bytes of the locking script (ScriptPubKey), expressed as a hexadecimal string. |
Transaction
Get transaction
curl "https://api.mattercloud.net/api/v3/main/tx/96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6" -H "api_key: your-api-key"
const matter = require('mattercloudjs');
const result = await matter.getTx('96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6');
The above command returns JSON structured like this:
{
"txid": "96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6",
"hash": "96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6",
"size": 301,
"version": 1,
"locktime": 0,
"vin": [
{
"value": 0.00015058,
"valueSat": 15058,
"txid": "d834682a5d29646427e5627d38c10224036535fa7e3066ae2f7a163a96550e27",
"vout": 1,
"n": 0,
"scriptSig": {
"asm": "30440220132f6d484de9d34d314aec945865af5da95f35cf4c7cc271d40bc99f8d7f12e3022051fcb2ce4461d1c6e8a778f5e4dcb27c8461d18e0652f68a7a09a98e95df5cb7[ALL|FORKID] 044e2c1e2c055e7aefc291679882382c35894a6aa6dd95644f598e506c239f9d83b1d9671c1d9673e3c2b74f07e8032343f3adc21367bd4cffae92fe31efcd598a",
"hex": "4730440220132f6d484de9d34d314aec945865af5da95f35cf4c7cc271d40bc99f8d7f12e3022051fcb2ce4461d1c6e8a778f5e4dcb27c8461d18e0652f68a7a09a98e95df5cb74141044e2c1e2c055e7aefc291679882382c35894a6aa6dd95644f598e506c239f9d83b1d9671c1d9673e3c2b74f07e8032343f3adc21367bd4cffae92fe31efcd598a"
},
"addr": "12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX",
"address": "12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX",
"sequence": 4294967295
}
],
"vout": [
{
"value": 0,
"valueSat": 0,
"n": 0,
"scriptPubKey": {
"asm": "OP_RETURN 31394878696756345179427633744870515663554551797131707a5a56646f417574 1717859169 746578742f6d61726b646f776e 5554462d38 616e6f74686572",
"hex": "6a2231394878696756345179427633744870515663554551797131707a5a56646f41757404617364660d746578742f6d61726b646f776e055554462d3807616e6f74686572",
"type": "nulldata"
},
"spentTxId": null,
"spentIndex": null,
"spentHeight": null
},
{
"value": 0.00014656,
"valueSat": 14656,
"n": 1,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 10bdcba3041b5e5517a58f2e405293c14a7c70c1 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX"
]
},
"spentTxId": null,
"spentIndex": null,
"spentHeight": null
}
],
"blockhash": "0000000000000000078f34d9cd3f48e4948aef4c79548ec777050e1c8953a85c",
"confirmations": 35137,
"time": 1554007897,
"blocktime": 1554007897,
"valueIn": 0.00015058,
"fees": 0.00000402,
"valueOut": 0.00014656,
"rawtx": "0100000001270e55963a167a2fae66307efa3565032402c1387d62e5276464295d2a6834d8010000008a4730440220132f6d484de9d34d314aec945865af5da95f35cf4c7cc271d40bc99f8d7f12e3022051fcb2ce4461d1c6e8a778f5e4dcb27c8461d18e0652f68a7a09a98e95df5cb74141044e2c1e2c055e7aefc291679882382c35894a6aa6dd95644f598e506c239f9d83b1d9671c1d9673e3c2b74f07e8032343f3adc21367bd4cffae92fe31efcd598affffffff020000000000000000456a2231394878696756345179427633744870515663554551797131707a5a56646f41757404617364660d746578742f6d61726b646f776e055554462d3807616e6f7468657240390000000000001976a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac00000000"
}
This endpoint retrieves specific transaction
HTTP Request
GET https://api.mattercloud.net/api/v3/main/tx/<txid>
URL Parameters
Parameter | Description |
---|---|
txid | The txid to retrieve transaction for |
Get Raw Transaction
curl "https://api.mattercloud.net/api/v3/main/tx/96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6" -H "api_key: your-api-key"
const matter = require('mattercloudjs');
const result = await matter.getTxRaw('96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6');
The above command returns JSON structured like this:
{
"rawtx": "0100000001270e55963a167a2fae66307efa3565032402c1387d62e5276464295d2a6834d8010000008a4730440220132f6d484de9d34d314aec945865af5da95f35cf4c7cc271d40bc99f8d7f12e3022051fcb2ce4461d1c6e8a778f5e4dcb27c8461d18e0652f68a7a09a98e95df5cb74141044e2c1e2c055e7aefc291679882382c35894a6aa6dd95644f598e506c239f9d83b1d9671c1d9673e3c2b74f07e8032343f3adc21367bd4cffae92fe31efcd598affffffff020000000000000000456a2231394878696756345179427633744870515663554551797131707a5a56646f41757404617364660d746578742f6d61726b646f776e055554462d3807616e6f7468657240390000000000001976a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac00000000"
}
This endpoint retrieves specific raw transaction
HTTP Request
GET https://api.mattercloud.net/api/v3/main/rawtx/<txid>
URL Parameters
Parameter | Description |
---|---|
txid | The txid to retrieve transaction for |
Get transaction batch
curl -X POST https://api.mattercloud.net/api/v3/main/tx -H 'Content-Type: application/json' \
-H 'Content-Type: application/json' \
-H "api_key: your-api-key" \
-d '{ "txids": "96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6,bdf6f49776faaa4790af3e41b8b474a7d0d47df540f8d71c3579dc0addd64c45"}'
const matter = require('mattercloudjs');
const result = await matter.getTxBatch([
'96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6',
'bdf6f49776faaa4790af3e41b8b474a7d0d47df540f8d71c3579dc0addd64c45'
]);
The above command returns JSON structured like this:
[
{
"txid": "96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6",
"hash": "96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6",
"size": 301,
"version": 1,
"locktime": 0,
"vin": [
{
"value": 0.00015058,
"valueSat": 15058,
"txid": "d834682a5d29646427e5627d38c10224036535fa7e3066ae2f7a163a96550e27",
"vout": 1,
"n": 0,
"scriptSig": {
"asm": "30440220132f6d484de9d34d314aec945865af5da95f35cf4c7cc271d40bc99f8d7f12e3022051fcb2ce4461d1c6e8a778f5e4dcb27c8461d18e0652f68a7a09a98e95df5cb7[ALL|FORKID] 044e2c1e2c055e7aefc291679882382c35894a6aa6dd95644f598e506c239f9d83b1d9671c1d9673e3c2b74f07e8032343f3adc21367bd4cffae92fe31efcd598a",
"hex": "4730440220132f6d484de9d34d314aec945865af5da95f35cf4c7cc271d40bc99f8d7f12e3022051fcb2ce4461d1c6e8a778f5e4dcb27c8461d18e0652f68a7a09a98e95df5cb74141044e2c1e2c055e7aefc291679882382c35894a6aa6dd95644f598e506c239f9d83b1d9671c1d9673e3c2b74f07e8032343f3adc21367bd4cffae92fe31efcd598a"
},
"addr": "12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX",
"address": "12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX",
"sequence": 4294967295
}
],
"vout": [
{
"value": 0,
"valueSat": 0,
"n": 0,
"scriptPubKey": {
"asm": "OP_RETURN 31394878696756345179427633744870515663554551797131707a5a56646f417574 1717859169 746578742f6d61726b646f776e 5554462d38 616e6f74686572",
"hex": "6a2231394878696756345179427633744870515663554551797131707a5a56646f41757404617364660d746578742f6d61726b646f776e055554462d3807616e6f74686572",
"type": "nulldata"
},
"spentTxId": null,
"spentIndex": null,
"spentHeight": null
},
{
"value": 0.00014656,
"valueSat": 14656,
"n": 1,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 10bdcba3041b5e5517a58f2e405293c14a7c70c1 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"12XXBHkRNrBEb7GCvAP4G8oUs5SoDREkVX"
]
},
"spentTxId": null,
"spentIndex": null,
"spentHeight": null
}
],
"blockhash": "0000000000000000078f34d9cd3f48e4948aef4c79548ec777050e1c8953a85c",
"confirmations": 35137,
"time": 1554007897,
"blocktime": 1554007897,
"valueIn": 0.00015058,
"fees": 0.00000402,
"valueOut": 0.00014656,
"rawtx": "0100000001270e55963a167a2fae66307efa3565032402c1387d62e5276464295d2a6834d8010000008a4730440220132f6d484de9d34d314aec945865af5da95f35cf4c7cc271d40bc99f8d7f12e3022051fcb2ce4461d1c6e8a778f5e4dcb27c8461d18e0652f68a7a09a98e95df5cb74141044e2c1e2c055e7aefc291679882382c35894a6aa6dd95644f598e506c239f9d83b1d9671c1d9673e3c2b74f07e8032343f3adc21367bd4cffae92fe31efcd598affffffff020000000000000000456a2231394878696756345179427633744870515663554551797131707a5a56646f41757404617364660d746578742f6d61726b646f776e055554462d3807616e6f7468657240390000000000001976a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac00000000"
}
]
This endpoint retrieves specific transaction
HTTP Request
POST https://api.mattercloud.net/api/v3/main/tx
Request Body
Parameter | Description |
---|---|
txids | The txids to retrieve transactions for |
Send Raw Transaction (deprecated)
Note: Use the newer Merchant Service for broadcast capabilities.
curl -X POST https://api.mattercloud.net/api/v3/main/tx/send -H 'Content-Type: application/json' \
-H 'Content-Type: application/json' \
-H "api_key: your-api-key" \
-d '{ "rawtx": "0100000001270e55963a167a2fae66307efa3565032402c1387d62e5276464295d2a6834d8010000008a4730440220132f6d484de9d34d314aec945865af5da95f35cf4c7cc271d40bc99f8d7f12e3022051fcb2ce4461d1c6e8a778f5e4dcb27c8461d18e0652f68a7a09a98e95df5cb74141044e2c1e2c055e7aefc291679882382c35894a6aa6dd95644f598e506c239f9d83b1d9671c1d9673e3c2b74f07e8032343f3adc21367bd4cffae92fe31efcd598affffffff020000000000000000456a2231394878696756345179427633744870515663554551797131707a5a56646f41757404617364660d746578742f6d61726b646f776e055554462d3807616e6f7468657240390000000000001976a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac00000000"}'
const matter = require('mattercloudjs');
const result = await matter.sendRawTx('0100000001270...');
The above command returns JSON structured like this:
{
"txid": "96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6"
}
This endpoint retrieves balances for multiple addresses at same time
HTTP Request
POST https://api.mattercloud.net/api/v3/main/tx/send
Request Body
Parameter | Description |
---|---|
rawtx | Transaction raw hex to broadcast |
Broadcast Transaction
(Deprecated). Use the newer Merchant API instead.
curl -X POST https://api.mattercloud.net/api/v3/main/merchants/tx/broadcast -H 'Content-Type: application/json' \
-H 'Content-Type: application/json' \
-H "api_key: your-api-key" \
-d '{ "rawtx": "0100000001270e55963a167a2fae66307efa3565032402c1387d62e5276464295d2a6834d8010000008a4730440220132f6d484de9d34d314aec945865af5da95f35cf4c7cc271d40bc99f8d7f12e3022051fcb2ce4461d1c6e8a778f5e4dcb27c8461d18e0652f68a7a09a98e95df5cb74141044e2c1e2c055e7aefc291679882382c35894a6aa6dd95644f598e506c239f9d83b1d9671c1d9673e3c2b74f07e8032343f3adc21367bd4cffae92fe31efcd598affffffff020000000000000000456a2231394878696756345179427633744870515663554551797131707a5a56646f41757404617364660d746578742f6d61726b646f776e055554462d3807616e6f7468657240390000000000001976a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac00000000"}'
const matter = require('mattercloudjs');
const result = await matter.merchantTxBroadcast('0100000001270...');
The above command returns JSON structured like this:
{
"success": true,
"result": {
"txid": "96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6",
}
}
}
Errors will be of the form:
{
"success": false,
"error": "TXN_MEMPOOL_CONFLICT",
}
Where error
can be:
- TXN_ALREADY_KNOWN (suppressed - returns as success: true)
- TXN_MEMPOOL_CONFLICT
- TXN_ALREADY_IN_MEMPOOL (suppressed - returns as success: true)
- NON_FINAL_POOL_FULL
- TOO_LONG_NON_FINAL_CHAIN
- BAD_TXNS_INPUTS_TOO_LARGE
- BAD_TXNS_INPUTS_SPENT
- NON_BIP68_FINAL
- TOO_LONG_VALIDATION_TIME
- BAD_TXNS_NONSTANDARD_INPUTS
- ABSURDLY_HIGH_FEE
- DUST
- TX_FEE_TOO_LOW
This endpoint broadcasts a transaction to the network
HTTP Request
POST https://api.mattercloud.net/api/v3/main/merchants/tx/broadcast
Request Body
Parameter | Description |
---|---|
rawtx | Transaction raw hex to broadcast |
Get Transaction Status
(Deprecated). Use the newer Merchant API instead.
curl https://api.mattercloud.net/api/v3/main/merchants/tx/status/96b3dc5941ce97046d4af6e7a69f4b38c48f05ef071c2a33f88807b89ab51da6 -H 'Content-Type: application/json' \
-H 'Content-Type: application/json' \
-H "api_key: your-api-key"
const matter = require('mattercloudjs');
const result = await matter.merchantTxStatus('0100000001270...');
The above command returns JSON structured like this:
{
"success": true,
"result": {
"txid": "349a217f3a9eac4611688e44f3d5508cf8c711e6b583bb08bcff54dcda124ee5",
"blockhash": "0000000000000000012c4624da90017fc6b636b926675be0c6f46e178ddc92b7", // Set only if in block
"blocktime": 1582991571, // Set only if in block
"time": 1582991571,
"fees": 0.00000615,
"size": 515,
"valueIn": 0.003,
"valueOut": 0.00299385,
"networkStatus": { // 'networkStatus' is only available if 'blockhash' is undefined (ie: it's not yet in a block)
"minersAcceptedMempoolCount": 34, // Future: Show number of known miners with the transaction in mempool
"minersAcceptedMempoolHashpowerPercent": 0.79, // Future: Show percentage of hash power of known miners with tx in the mempool
"doubleSpendDetected": false, // Future: Show whether a double spend of the inputs was detected
"doubleSpendTx": "" // Future: Provide double spend txid if a double spend is detected
}
}
}
Errors will be of the form:
{
"success": false,
"error": "TX_NOT_FOUND",
}
Where error
can be:
- TX_NOT_FOUND
This endpoint checks the status of a transaction
HTTP Request
GET https://api.mattercloud.net/api/v3/main/merchants/tx/status/:txid
Merchant API
Note: You can use 3rd party API clients such as Minercraft to interact with the Merchant API endpoint at https://merchantapi.mattercloud.net/mapi/feeQuote
For example:
brfc-merchantapi specification
This protocol uses the JSON envelopes BRFC as well as the Fee Spec BRFC.
Get fee quote
curl https://merchantapi.mattercloud.net/mapi/feeQuote -H 'Content-Type: application/json'
// Using matterclouudjs
const matter = require('mattercloudjs');
const result = await matter.mapi.feeQuote('0100000001270...');
// Using minercraft
const miner = new Minercraft({
"url": "https://merchantapi.mattercloud.net"
});
let rate = await miner.fee.rate()
The above command returns JSON structured like this:
{
"payload": "{\"apiVersion\":\"0.1.0\",\"timestamp\":\"2020-01-28T11:15:03.722Z\",\"expiryTime\":\"2020-01-28T11:25:03.722Z\",\"minerId\":\"03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031\",\"currentHighestBlockHash\":\"000000000000000001cedc3dec00ecd29943a275498e812e72b2afdf5df8814a\",\"currentHighestBlockHeight\":619574,\"minerReputation\":\"N/A\",\"fees\":[{\"feeType\":\"standard\",\"miningFee\":{\"satoshis\":1,\"bytes\":1},\"relayFee\":{\"satoshis\":1,\"bytes\":1}},{\"feeType\":\"data\",\"miningFee\":{\"satoshis\":1,\"bytes\":1},\"relayFee\":{\"satoshis\":1,\"bytes\":1}}]}",
"signature": "304402202a7f70855739a6948c00c2a85dd733f087c4f1ae4beb256c225eadab767d5e1d02207870c57728166f61b0334bd89640d6d6c26f31ada4aac42b29971ebfa5c414e1",
"publicKey": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
"encoding": "UTF-8",
"mimetype": "application/json"
}
Purpose:
This endpoint returns a JSONEnvelope with a payload that contains the fees charged by a specific BSV miner. The purpose of the envelope is to ensure strict consistency in the message content for the purpose of signing responses.
Returns:
{
"payload": "{\"apiVersion\":\"0.1.0\",\"timestamp\":\"2020-01-28T11:15:03.722Z\",\"expiryTime\":\"2020-01-28T11:25:03.722Z\",\"minerId\":\"03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031\",\"currentHighestBlockHash\":\"000000000000000001cedc3dec00ecd29943a275498e812e72b2afdf5df8814a\",\"currentHighestBlockHeight\":619574,\"minerReputation\":\"N/A\",\"fees\":[{\"feeType\":\"standard\",\"miningFee\":{\"satoshis\":1,\"bytes\":1},\"relayFee\":{\"satoshis\":1,\"bytes\":1}},{\"feeType\":\"data\",\"miningFee\":{\"satoshis\":1,\"bytes\":1},\"relayFee\":{\"satoshis\":1,\"bytes\":1}}]}",
"signature": "304402202a7f70855739a6948c00c2a85dd733f087c4f1ae4beb256c225eadab767d5e1d02207870c57728166f61b0334bd89640d6d6c26f31ada4aac42b29971ebfa5c414e1",
"publicKey": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
"encoding": "UTF-8",
"mimetype": "application/json"
}
field | function |
---|---|
payload |
main data payload encoded in a specific format type |
signature |
signature on payload string. This may be null. |
publicKey |
public key to verify signature. This may be null. |
encoding |
encoding type |
mimetype |
Multipurpose Internet Mail Extensions type |
Payload:
{
"apiVersion": "0.1.0",
"timestamp": "2020-01-28T11: 15: 03.722Z",
"expiryTime": "2020-01-28T11: 25: 03.722Z",
"minerId": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
"currentHighestBlockHash": "000000000000000001cedc3dec00ecd29943a275498e812e72b2afdf5df8814a",
"currentHighestBlockHeight": 619574,
"minerReputation": null,
"fees": [
{
"feeType": "standard",
"miningFee": {
"satoshis": 1,
"bytes": 1
},
"relayFee": {
"satoshis": 1,
"bytes": 1
}
},
{
"feeType": "data",
"miningFee": {
"satoshis": 1,
"bytes": 1
},
"relayFee": {
"satoshis": 1,
"bytes": 1
}
}
]
}
field | function |
---|---|
apiVersion |
version of merchant api spec |
timestamp |
timestamp of payload document |
expiryTime |
expiry time of quote |
minerId |
minerID / public key of miner. This may be null. |
currentHighestBlockHash |
hash of current blockchain tip |
currentHighestBlockHeight |
hash of current blockchain tip |
minerReputation |
reputation of miner |
fees |
fees charged by miner (feeSpec BRFC) |
Submit transaction
curl -X POST https://merchantapi.mattercloud.net/mapi/tx -H 'Content-Type: application/json' \
-d '{ "rawtx": "0100000001270e55963a167a2fae66307efa3565032402c1387d62e5276464295d2a6834d8010000008a4730440220132f6d484de9d34d314aec945865af5da95f35cf4c7cc271d40bc99f8d7f12e3022051fcb2ce4461d1c6e8a778f5e4dcb27c8461d18e0652f68a7a09a98e95df5cb74141044e2c1e2c055e7aefc291679882382c35894a6aa6dd95644f598e506c239f9d83b1d9671c1d9673e3c2b74f07e8032343f3adc21367bd4cffae92fe31efcd598affffffff020000000000000000456a2231394878696756345179427633744870515663554551797131707a5a56646f41757404617364660d746578742f6d61726b646f776e055554462d3807616e6f7468657240390000000000001976a91410bdcba3041b5e5517a58f2e405293c14a7c70c188ac00000000"}'
// Using matterclouudjs
const matter = require('mattercloudjs');
const result = await matter.mapi.submitTx('0100000001270...');
// Using minercraft
const miner = new Minercraft({
"url": "https://merchantapi.mattercloud.net"
});
let result = await miner.tx.push('0100000001270....')
Purpose:
This endpoint is used to send a raw transaction to a miner for inclusion in the next block that the miner creates.
body when
Content-Type
isapplication/json
:
{
"rawtx": "0200000001f56216b33513cf621839d584f0e31566059537ef184070733a56c3b5c41d0d6d0000000049483045022100cddd5c304ff87f1733262d34b56a90061aa4b97fdc0b0e42fc3065c04e231ca402202f0c65cb6d04c2b8fc82bdcfcfd7295b6e0f717362ec395e02f6905c68ac7b7741ffffffff01805b6d29010000001976a9142a5acfb9a647a03a758afaa5c359284d4b95c0be88ac00000000"
}
When Content-Type is application/octet-stream, it is possible to upload the rawtx as a binary stream. For large transactions, this is half the size of the hexadecimal equivalent although this gain is largely minimized through the use of gzip encoding of hex data.
Returns:
{
"payload": "{\"apiVersion\":\"0.1.0\",\"timestamp\":\"2020-01-15T11:40:29.826Z\",\"txid\":\"6bdbcfab0526d30e8d68279f79dff61fb4026ace8b7b32789af016336e54f2f0\",\"returnResult\":\"success\",\"resultDescription\":\"\",\"minerId\":\"03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031\",\"currentHighestBlockHash\":\"71a7374389afaec80fcabbbf08dcd82d392cf68c9a13fe29da1a0c853facef01\",\"currentHighestBlockHeight\":207,\"txSecondMempoolExpiry\":0}",
"signature": "3045022100f65ae83b20bc60e7a5f0e9c1bd9aceb2b26962ad0ee35472264e83e059f4b9be022010ca2334ff088d6e085eb3c2118306e61ec97781e8e1544e75224533dcc32379",
"publicKey": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
"encoding": "UTF-8",
"mimetype": "application/json"
}
field | function |
---|---|
payload |
main data payload encoded in a specific format type |
signature |
signature on payload string. This may be null. |
publicKey |
public key to verify signature. This may be null. |
encoding |
encoding type |
mimetype |
Multipurpose Internet Mail Extensions type |
Payload:
{
"apiVersion": "0.1.0",
"timestamp": "2020-01-15T11:40:29.826Z",
"txid": "6bdbcfab0526d30e8d68279f79dff61fb4026ace8b7b32789af016336e54f2f0",
"returnResult": "success",
"resultDescription": "",
"minerId": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
"currentHighestBlockHash": "71a7374389afaec80fcabbbf08dcd82d392cf68c9a13fe29da1a0c853facef01",
"currentHighestBlockHeight": 207,
"txSecondMempoolExpiry": 0
}
field | function |
---|---|
apiVersion |
version of merchant api spec |
timestamp |
timestamp of payload document |
txid |
transaction ID |
returnResult |
will contain either success or failure |
resultDescription |
will contain the error on failure or empty on success |
minerId |
minerId public key of miner |
currentHighestBlockHash |
hash of current blockchain tip |
currentHighestBlockHeight |
hash of current blockchain tip |
txSecondMempoolExpiry |
Duration (minutes) Tx will be kept in secondary mempool |
Query transaction status
curl https://merchantapi.mattercloud.net/mapi/tx/5e3014372338f079f005eedc85359e4d96b8440e7dbeb8c35c4182e0c19a1a12 -H 'Content-Type: application/json'
// Using matterclouudjs
const matter = require('mattercloudjs');
const result = await matter.mapi.getTx('5e3014372338f079f005eedc85359e4d96b8440e7dbeb8c35c4182e0c19a1a12');
// Using minercraft
const miner = new Minercraft({
"url": "https://merchantapi.mattercloud.net"
});
let result = await miner.tx.status('5e3014372338f079f005eedc85359e4d96b8440e7dbeb8c35c4182e0c19a1a12')
Purpose:
This endpoint is used to check the current status of a previously submitted transaction.
Returns:
{
"payload": "{\"apiVersion\":\"0.1.0\",\"timestamp\":\"2020-01-15T11:41:29.032Z\",\"returnResult\":\"failure\",\"resultDescription\":\"Transaction in mempool but not yet in block\",\"blockHash\":\"\",\"blockHeight\":0,\"minerId\":\"03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031\",\"confirmations\":0,\"txSecondMempoolExpiry\":0}",
"signature": "3045022100f78a6ac49ef38fbe68db609ff194d22932d865d93a98ee04d2ecef5016872ba50220387bf7e4df323bf4a977dd22a34ea3ad42de1a2ec4e5af59baa13258f64fe0e5",
"publicKey": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
"encoding": "UTF-8",
"mimetype": "application/json"
}
field | function |
---|---|
payload |
main data payload encoded in a specific format type |
signature |
signature on payload string. This may be null. |
publicKey |
public key to verify signature. This may be null. |
encoding |
encoding type |
mimetype |
Multipurpose Internet Mail Extensions type |
Payload:
{
"apiVersion": "0.1.0",
"timestamp": "2020-01-15T11:41:29.032Z",
"returnResult": "failure",
"resultDescription": "Transaction in mempool but not yet in block",
"blockHash": "",
"blockHeight": 0,
"minerId": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
"confirmations": 0,
"txSecondMempoolExpiry": 0
}
field | function |
---|---|
apiVersion |
version of merchant api spec |
timestamp |
timestamp of payload document |
returnResult |
will contain either success or failure |
resultDescription |
will contain the error on failure or empty on success |
blockHash |
hash of tx block |
blockHeight |
hash of tx block |
minerId |
minerId public key of miner |
confirmations |
number of block confirmations |
txSecondMempoolExpiry |
Duration (minutes) Tx will be kept in secondary mempool |
OR
{
"payload": "{\"apiVersion\":\"0.1.0\",\"timestamp\":\"2020-01-15T12:09:37.394Z\",\"returnResult\":\"success\",\"resultDescription\":\"\",\"blockHash\":\"745093bb0c80780092d4ce6926e0caa753fe3accdc09c761aee89bafa85f05f4\",\"blockHeight\":208,\"minerId\":\"03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031\",\"confirmations\":2,\"txSecondMempoolExpiry\":0}",
"signature": "3045022100c9a712a124ff3100e26f7bbcc87204848cc2ff1effacd8d8e8daac5d81bce74c02201dd661aad00d2cde443a076475cfb7d6523e0ef98a1112e938af002ca5222fbe",
"publicKey": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
"encoding": "UTF-8",
"mimetype": "application/json"
}
field | function |
---|---|
payload |
main data payload encoded in a specific format type |
signature |
signature on payload string. This may be null. |
publicKey |
public key to verify signature. This may be null. |
encoding |
encoding type |
mimetype |
Multipurpose Internet Mail Extensions type |
Payload:
{
"apiVersion": "0.1.0",
"timestamp": "2020-01-15T12:09:37.394Z",
"returnResult": "success",
"resultDescription": "",
"blockHash": "745093bb0c80780092d4ce6926e0caa753fe3accdc09c761aee89bafa85f05f4",
"blockHeight": 208,
"minerId": "03fcfcfcd0841b0a6ed2057fa8ed404788de47ceb3390c53e79c4ecd1e05819031",
"confirmations": 2,
"txSecondMempoolExpiry": 0
}
Miner ID
MatterPool and MatterCloud supports Miner ID specification
https://minerid.matterpool.io/minerid/MATTERPOOL
Filepay
Filepay is a simple library to post data and upload files to the Bitcoin SV blockchain.
Example file:
const privateKey = [YOUR PRIVATE KEY HERE];
// Upload File or object
require('filepay').putFile({
file: {
content: 'Hello world!',
contentType: 'text/plain',
encoding: 'utf8',
name: 'hello.txt'
},
pay: { key: "58Jd09..." }
});
// Upload arbitrary OP_RETURN
filepay.send({
data: ["0x6d02", "Hello from filepay"],
pay: { key: privateKey }
});
Errors
The MatterCloud API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- The resource is forbidden. |
404 | Not Found -- The specified resource could not be found. |
405 | Method Not Allowed -- You tried to access a resource with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't json. |
410 | Gone -- The resource requested has been removed from our servers. |
418 | I'm a teapot. |
429 | Too Many Requests -- You're requesting too many resources! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |