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

Javascript SDK

Contact

Contact us for feedback and questions, we love to hear your feedback.

@MatterCloud

mattercloud@protonmail.com

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.

MatterCloud Development Plans

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 is application/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 Documentation

Filepay is a simple library to post data and upload files to the Bitcoin SV blockchain.

Example file:

File data

Block Explorer

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.