BLOCKCLOCK mini

Buy yours at store.coinkite.com

BLOCKCLOCK mini “Push” API

This document describes the PUSH API for sending data to the BLOCKCLOCK mini. In normal operation, out of the box, the BLOCKCLOCK mini uses a completely different “pull” protocol to get and display values.

Quick Examples

These examples assume your BLOCKCLOCK mini is using IP address: 10.0.0.104

% curl "http://10.0.0.104/api/pick/cm.markets.price"

% curl "http://10.0.0.104/api/show/text/Hello"

% curl "http://10.0.0.104/api/show/number/12999?pair=USD/BTC&sym=bitcoin"

% curl --digest -u :PASSWORD "http://10.0.0.104/api/status"
{
    "tags": [
        "binance.BTCBUSD.ask",
        "binance.BTCBUSD.bid",
        "binance.BTCUSDC.ask",
        "aqua.BTC-USD.bid",
        ...
    ],
    "version": "0.2.1",
    "rendered": {
        "number": 8261.1,
        "pair": [
            "BTC",
            "GBP"
        ],
        "tl_text": "Coinbase BTC-GBP Spot",
        "label": "Coinbase BTC-GBP Spot",
        "contents": [
            "/BTC/GBP",
            "\u00a3",
            "8",
            "2",
            "6",
            "1",
            "/.10"
        ],
        "string": null,
        "br_text": null,
        "is_error": false,
        "tag": "coinbase.BTC-GBP.spot"
    },
    "menu_active": false
}


Displaying Your Custom Data

When your program sends data to the BLOCKCLOCK mini using this API, it is displayed immediately. When the clock would normally update your API data will be replaced (top of the next 5 minute interval or less often). Set the update rate to “manual” if you want to exclusively push data to it.

Displaying Numbers

Displaying Text

Decoration

You may add query string arguments to either of those urls to change how the value is shown:

Arbitrary Displays

You may also upload a small JSON document which controls the display more precisely. The details of that are not yet documented, so please ask for help.

Rate Limiting

Because of the limited update rate of the EInk displays, you should only update the display every five minutes and no more frequently. If you exceed a rate of once per minute, your program will receive a 429 error and a message about required delay.

Read Display

You can get currently displayed value, and other status information, using: /api/status

For example:

% curl --digest -u :PASSWORD "http://10.0.0.104/api/status"
{
    "tags": [
        "datetime.world.a",
        "datetime.world.b",
        "electrum.BTC.block_height",
        "coinbase.BTC-GBP.spot",
        "bylls.sell.price",
        "cm.markets.price"
    ],
    "showing": "coinbase.BTC-GBP.spot",
    "version": "0.2.1",
    "rendered": {
        "number": 8261.1,
        "pair": [
            "BTC",
            "GBP"
        ],
        "tl_text": "Coinbase BTC-GBP Spot",
        "label": "Coinbase BTC-GBP Spot",
        "contents": [
            "/BTC/GBP",
            "\u00a3",
            "8",
            "2",
            "6",
            "1",
            "/.10"
        ],
        "string": null,
        "br_text": null,
        "is_error": false,
        "tag": "coinbase.BTC-GBP.spot"
    },
    "menu_active": false
}

The values are defined as follows:

Show Specific Data From Backend

/api/pick/next - move the next data tag in programmed sequence

/api/pick/cm.markets.price - display the indicated tag (it need not be in your list already) - can fail with 404 if unknown/undefined tag (display is affected)

/api/pick/redraw - redraw the current tag - good means to recover from a failed /api/pick/bad.tag

Other functions over API

These endpoints perform immediate functions: