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

The current rate limit is 3 requests every 15 seconds. Need more? Get in contact with us.

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>/utxos

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.

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 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

Broadcast transaction


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

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.