mintBlue offers its SDK functionality through a REST API. This JSON-RPC server allows you to use the SDK's functionalities without integrating the SDK package into your solution. MintBlue clients using the JSON-RPC server may utilize different programming languages when implementing the JSON-RPC specification.

You can decrease implementation time, allowing for an easy way to set up proof of concepts. Additionally, you can easily integrate mintBlue's functionality into non-JavaScript environments.

ℹ️ You can find the full specification of the SDK here.

Prerequisites

✅ Create an SDK Access Token (see Quick Start)
✅ Create a new project and copy your project ID
✅ Understand Output Types
✅ Install curl or use another tool or code snippet of choice to send API requests

Request format

The JSON-RPC server uses an SDK Access Token for authentication. Make sure to replace the <YOUR-SECRET> with the last part of your SDK Access Token. Provide the SDK Access Token in your HTTP headers under the key mintblue-sdk-token. Make sure your Content-Type is set to application/json. Below, a skeleton request is shown for curl.

curl --request POST 'https://api.mintblue.com/sdk/latest' \
--header 'mintblue-sdk-token: secret-token:mintBlue.com/sdk/<YOUR-SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '
{ 
    "id": "1", 
    "jsonrpc": "2.0", 
    "method": "<SDK-FUNCTION>", 
    "params": {}
}'

We recommend you send JSON-RPC requests to the latest version of the mintBlue SDK, indicated by the request URL .../sdk/latest. If you want to use a specific version of the SDK, you can target a version like this:

https://api.mintblue.com/sdk/v4.1.1

You can find an overview of all versions here: https://api.mintblue.com/sdk/versions. Next, let's learn to send requests for different output types.

Data output

Here's an example transaction that stores a customer order on the blockchain. We'll be using a Data Output to store textual information on the Bitcoin blockchain.

curl --request POST 'https://api.mintblue.com/sdk/latest' \
--header 'mintblue-sdk-token: secret-token:mintBlue.com/sdk/<YOUR-SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '
{ 
    "id": "1", 
    "jsonrpc": "2.0", 
    "method": "createTransaction", 
    "params": {
        "project_id": "900e008a-a661-4877-8d17-c1a083cf286e",
        "outputs": [
            {
                "type": "data",
                "value": {
                    "order_id": "order-123",
                    "order_date": "2021-10-10T10:25:31.719Z",
                    "order_items": [
                        {
                          "item_id": "item-1",
                          "item_price": 100
                        }
                    ]
                }
            }
        ]
    }
}'

We'll receive the following result for the request. It contains the transaction ID and raw transaction data. It's the same result as you would get when using the SDK.

{"jsonrpc":"2.0","id":"1","result":{"txid":"6d2d2b2b7b822b59a8ee8f72c7613ada3a3bfb78f01732b6c5d850176c31d774","rawtx":"0100000001079717f1bc7569399ddf0101218ec186165617f18a2d495c9a4d345faf02f3dc010000006a4730440220342fb464096fc29cdfda299088daa34c62259108f89744431e67567c015f3969022051041b69b1f7b843466632fb1787b5869ad0c235424827ef627d724c99a67ac6412103551661f55e4cb5ffecc99827c052d12c81417e192f03fb4fa038a3e05f6dcbc2ffffffff02000000000000000083006a04554e495616a2646d657461a06570726f746f686d696e74426c75654c63a3686f726465725f6964696f726465722d3132336a6f726465725f646174657818323032312d31302d31305431303a32353a33312e3731395a6b6f726465725f6974656d7381a2676974656d5f6964666974656d2d316a6974656d5f70726963651864be600000000000001976a914a25e605fa437f5b7104418f0ae3f99d4713fd05288ac00000000"}}

You can optionally sign and encrypt the transaction by adding these options. If you are unsure about the possible options, you can always look up the interface for the output type, like the DataOutput interface.

curl --request POST 'https://api.mintblue.com/sdk/latest' \
--header 'mintblue-sdk-token: secret-token:mintBlue.com/sdk/<YOUR-SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '
{ 
    "id": "1", 
    "jsonrpc": "2.0", 
    "method": "createTransaction", 
    "params": {
        "project_id": "900e008a-a661-4877-8d17-c1a083cf286e",
        "outputs": [
            {
                "type": "data",
                "value": "Invoice #1234",
                "sign": true,
                "encrypt": true
            }
        ]
    }
}'

Payment output

Here's an example of a Payment Output.

curl --request POST 'https://api.mintblue.com/sdk/latest' \
--header 'mintblue-sdk-token: secret-token:mintBlue.com/sdk/<YOUR-SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '
{ 
    "id": "1", 
    "jsonrpc": "2.0", 
    "method": "createTransaction", 
    "params": {
        "project_id": "900e008a-a661-4877-8d17-c1a083cf286e",
        "outputs": [
            {
                "type": "payment",
                "to": "1FoXXU8xneLzkS1Hrhg8Hck7MJLvy3Uzyx",
                "satoshis": 1000
            }
        ]
    }
}'

File output

You can store a File Output on the blockchain. However, there's one caveat:

danger

All buffer values need to be converted to base64, and provided as a string preceded by base64:

Example: base64:ZXhhbXBsZSB0ZXh0IGJhc2U2NCBmb3JtYXQ=

Here's an example where we convert a string {key: "value"} to a Buffer and represented it as a base64 string: eyJrZXkiOiJ2YWx1ZSJ9

curl --request POST 'https://api.mintblue.com/sdk/latest' \
--header 'mintblue-sdk-token: secret-token:mintBlue.com/sdk/<YOUR-SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '
{ 
    "id": "1", 
    "jsonrpc": "2.0", 
    "method": "createTransaction", 
    "params": {
        "project_id": "900e008a-a661-4877-8d17-c1a083cf286e",
        "outputs": [
            {
                "type": "file",
                "value": {
                    "contentType": "text/plain",
                    "content": "base64:eyJrZXkiOiJ2YWx1ZSJ9"
                }
            }
        ]
    }
}'

Peppol output

Here's an example of a peppol output type, including a base64 buffer string.

curl --request POST 'https://api.mintblue.com/sdk/latest' \
--header 'mintblue-sdk-token: secret-token:mintBlue.com/sdk/<YOUR-SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '
{ 
    "id": "1", 
    "jsonrpc": "2.0", 
    "method": "createTransaction", 
    "params": {
        "project_id": "900e008a-a661-4877-8d17-c1a083cf286e",
        "outputs": [
            {
                "type": "peppol",
                "version": 1,
                "pubKey": "0451e5f5d3b4d8bc236dc406d31404074e7d112dc8922c2549120f3dc24e32215999880deb21a76be8ed401749f711e8be9652215b2dd3d99654c6f72d443b0d28",
                "value": "base64:dGVzdA=="
            }
        ]
    }
}'

Combine output types

And lastly, you can combine different outputs.

curl --request POST 'https://api.mintblue.com/sdk/latest' \
--header 'mintblue-sdk-token: secret-token:mintBlue.com/sdk/<YOUR-SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '
{ 
    "id": "1", 
    "jsonrpc": "2.0", 
    "method": "createTransaction", 
    "params": {
        "project_id": "900e008a-a661-4877-8d17-c1a083cf286e",
        "outputs": [
            {
                "type": "data",
                "value": "Invoice #1234",
                "sign": true,
                "encrypt": true
            },
            {
                "type": "payment",
                "to": "1FoXXU8xneLzkS1Hrhg8Hck7MJLvy3Uzyx",
                "satoshis": 1000
            }
        ]
    }
}'

Get a transaction by ID

You can use other methods the SDK exposes, like retrieving a transaction.

curl --request POST 'https://api.mintblue.com/sdk/latest' \
--header 'mintblue-sdk-token: secret-token:mintBlue.com/sdk/<YOUR-SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '
{ 
    "id": "1", 
    "jsonrpc": "2.0", 
    "method": "getTransaction", 
    "params": {
        "txid": "8129fe3c4cf04a15bb02846ef3c1247c38e838ae055e10931c278ae035d61e35"
    }
}'

# result
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": [
    {
      "type": "payment",
      "to": "1FoXXU8xneLzkS1Hrhg8Hck7MJLvy3Uzyx",
      "satoshis": 1000
    },
    {
      "type": "payment",
      "to": "1Juc9Tjmb6wc6yCaWFuB9QdEEQ621992ks",
      "satoshis": 23827
    }
  ]
}

If you are unsure of the expected input parameters, you can look up the getTransaction function in the mintBlue SDK reference docs. Here's the interface for the GetTransactionOptions. As you can see, it expects a txid and an optional secret.

GetTransactionOptions

Prerequisites

Request format

Data output​

Payment output​

File output​

Peppol output​

Combine output types​

Get a transaction by ID​