JSON-RPC

One HTTP endpoint that exposes the SDK functions, for languages the JavaScript package does not cover.

Current SDK generation. This page documents the HTTP surface that ships today. Addressing and discovery are specified by the open SDX Protocol. Read the specification

Generations sets out which document applies to the code you installed.

The JSON-RPC server exposes the SDK's functions over one HTTP endpoint, so a service written in a language the JavaScript package does not cover can create and read transactions without embedding the SDK. It is also the shortest route to a working proof of concept, because a request is a curl command rather than a build step.

Before you start

You need an SDK access token from Access Tokens in the console, a project ID from Projects, and something that speaks HTTP. Output types is the page that says what goes in outputs.

The request

Every call is a POST to one URL, with a JSON-RPC 2.0 body. The token goes in the mintblue-sdk-token header, and it is the last part of the SDK access token that fills <YOUR-SECRET>.

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": {}
}'

method names an SDK function and params is that function's options object, so the JSON-RPC body and the JavaScript call take the same arguments under the same names. The generated declarations for every function are published at mintblue.gitlab.io/sdk.

Methods

`method`	`params`	Returns
`createTransaction`	`project_id`, `outputs`, optional `metadata` and `rawtx`	`txid` and `rawtx`
`getTransaction`	`txid`, optional `parse` and `secret`	The transaction and its outputs

These two are the methods this page documents and shows working requests for. The endpoint is a front for the SDK client rather than a hand-written API, so other client functions are reachable by name in the same way; check the generated reference for the exact options object before you rely on one.

Versions

/sdk/latest follows the newest published version. To pin, name the version in the path instead:

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

The versions the endpoint currently serves are listed at api.mintblue.com/sdk/versions. That list is its own numbering line and does not track the npm package version, so pin against the list rather than against the version you have installed.

Create a transaction with a data output

This one stores a customer order.

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
                        }
                    ]
                }
            }
        ]
    }
}'

The result carries the transaction ID and the raw transaction data, which is the same result the SDK returns. The raw transaction is long, and is cut short here:

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

Add sign and encrypt to the output to sign and encrypt the value:

--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
            }
        ]
    }
}'

Other output types

A payment output:

{
    "type": "payment",
    "to": "12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX",
    "satoshis": 1000
}

A file output. Over HTTP there is no buffer type, so every buffer value is sent as base64 in a string prefixed with base64:. The string {key: "value"} becomes base64:eyJrZXkiOiJ2YWx1ZSJ9:

{
    "type": "file",
    "value": {
        "contentType": "text/plain",
        "content": "base64:eyJrZXkiOiJ2YWx1ZSJ9"
    }
}

The declared file value also carries fileName beside contentType and content.

A Peppol output, with the same base64 rule on value:

{
    "type": "peppol",
    "version": 1,
    "pubKey": "0451e5f5d3b4d8bc236dc406d31404074e7d112dc8922c2549120f3dc24e32215999880deb21a76be8ed401749f711e8be9652215b2dd3d99654c6f72d443b0d28",
    "value": "base64:dGVzdA=="
}

Outputs combine here exactly as they do in the SDK: put more than one in the array.

"outputs": [
    {
        "type": "data",
        "value": "Invoice #1234",
        "sign": true,
        "encrypt": true
    },
    {
        "type": "payment",
        "to": "12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX",
        "satoshis": 1000
    }
]

Read a transaction back

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"
    }
}'

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

getTransaction takes a txid. The SDK's declaration carries two more options: parse, which asks for the outputs of the fetched transaction to be parsed and returned in an outputs field, and secret, which is only needed when the content was encrypted to a key other than your own. Records encrypted with your account's keys decrypt without one.