Krist Documentation

Appearance

KristQL ​

KristQL is an API allowing you to run arbitrary SQL queries against the Krist database. This allows you to create rich and complex queries to gather statistical information about the Krist network.

Of course, you can only run SELECT queries - you cannot modify the database.

IMPORTANT

KristQL is NOT intended for scraping large amounts of data from the Krist network, or automated queries. It is intended for simple, single-use queries to gather aggregate and statistical information.

The rate limits on KristQL are very strict for this reason and if you use it for automated or bulk scraping you may find your IP blocked.

To scrape data from the Krist database (e.g. transaction history), use the Krist API - the rate limits are much friendlier and the results are more useful.

WARNING

KristQL has very strict rate limits. Make sure you test your SQL queries are valid before running them.

PRIVACY

KristQL queries are logged alongside your IP address and User-Agent for 30 days.

Table of Contents ​

Available Tables ​

Addresses ​

The addresses table contains all addresses known to Krist, as well as their balances, and when they were first seen. It has the following fields:

  • id - The ID of the address.
  • address - The address itself.
  • balance - The amount of Krist stored in the address.
  • firstseen - The time and date the address was first seen by the Krist server. In JSON, this is an ISO 8601 string. In CSV, this is a Unix timestamp in milliseconds.

Transactions ​

The transactions table contains all transactions that have been made. It has the following fields:

  • id - The ID of this transaction.
  • from - The address that sent this transaction. This value can be null.
  • to - The address that this transaction was sent to. If this transaction was a name purchase, this value will be name. For A record changes on a name, this value will be a.
  • value - The amount of Krist transferred in this transaction. For A record changes on a name, this value can be 0.
  • time - The time that this transaction occured. In JSON, this is an ISO 8601 string. In CSV, this is a Unix timestamp in milliseconds.
  • name - The name associated with this transaction. This can be set for name purchases, A record changes, name transfers, or paying to names. If value is 0, then it is a name transfer. Otherwise, it is money being paid the owner of a name.
  • meta - The metadata of this transaction. For A record changes, this is the new A record of the name.

Names ​

The names table contains all names that have been purchased. It has the following fields:

  • id - The ID of this name.
  • name - The name itself.
  • owner - The address that currently owns this name.
  • registered - The date and time that this name was registered. In JSON, this is an ISO 8601 string. In CSV, this is a Unix timestamp in milliseconds.
  • updated - The date and time that this name was last transferred, or its A record was last updated.
  • a - The A record of this name.
  • unpaid - Currently unused.

The API ​

The API endpoint root is https://query.krist.dev.

You can use GET or POST to /query, and supply the query as a query (?q=) or body parameter (q=).

Formats ​

There are three return formats supported: JSON, compact JSON, and CSV.

JSON ​

JSON is the default, but you can explicitly set it with Accepts: application/json. Output will look like this:

json
{
  "ok": true,
  "count": 2,
  "results": [
    {
      "id": 1,
      "from": null,
      "to": "0000000000",
      "value": 50,
      "time": "2015-02-14T16:44:40.000Z",
      "name": null,
      "meta": null
    },
    ...
  ]
}

Compact JSON ​

You can also get compact JSON with the ?compact query string parameter. It will return a fields array, and the results will be an array of arrays:

json
{
  "ok": true,
  "count": 2,
  "fields": [ "id", "from", "to", "value", "time", "name", "meta" ],
  "results": [
    [ 1, null, "0000000000", 50, "2015-02-14T16:44:40.000Z", null, null ],
    [ 2, null, "a5dfb396d3", 50, "2015-02-14T20:42:30.000Z", null, null ]
  ]
}

CSV ​

Alternatively, you can get the results as CSV. You can either do this by specifying the ?csv query string parameter, or with the Accepts: text/csv header. Null values will be empty cells:

csv
id,from,to,value,time,name,meta
1,,0000000000,50,1423932280000,,
2,,a5dfb396d3,50,1423946550000,,

Errors ​

The API will return the appropriate HTTP status code for all requests. Additionally, if you are using the JSON format, responses will contain the ok parameter. If ok: false, it should also contain an error message:

json
{
  "ok": false,
  "error": "You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near '\"' at line 1"
}

Examples ​

Get the last 100 transactions ​

GET /query?q=SELECT * FROM `transactions` ORDER BY `id` DESC LIMIT 100

json
{
  "ok": true,
  "count": 100,
  "results": [
    {
      "id": 914947,
      "from": null,
      "to": "kya197vexi",
      "value": 1,
      "time": "2019-01-13T17:07:01.000Z",
      "name": null,
      "meta": null
    },
    ...
  ]
}