NAV Navbar
shell javascript

Introduction

MatterCloud is a Bitcoin SV blockchain API for developers.

Query wallet addresses, transactions, and broadcast transactions with the REST API.

Features:

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:

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:

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.