Authentication

Authentication with the Metamarkets API is performed via an “Authorization” header. Retrieve your token from the API token page and present it as follows:

  Authorization: Bearer <token>

Important security note: Carefully protect your API key. It grants the same data access as your regular Metamarkets username and password, so treat it as if you would your password. Do not add your API key to a code repository or share it in a screenshot.

If you think your key may have been shared accidentally, visit the API token page and revoke your token. This will eliminate all access via that token, and allow you to generate a fresh token.

Interval specification

All data queries require specification of a time window of interest. Data will be only included when it was timestamped within this interval. This is how you specify data ‘from the previous month’ or ‘from March 8 this year’. The interval parameter is specified in ISO 8601 format.

While there are other reference sources that give information about the ISO 8601 format,
note that:

• Dates are in YYYY-MM-DD format. You may use a hyphen or a minus sign to separate the components of the date.
• Separate the date, and an optional time, with a T.
• Times are in HH:MM:SS format. You can freely omit minutes or seconds, and the time will be treated as ending with 00:00.
• You can specify an optional time zone by appending a Z to the time for UTC, or an offset such as -07 (UTC – 7 hours) or +13 (UTC + 13 hours). An omitted time zone will be interpreted as UTC.
• Use 00 as the hours to specify midnight at the beginning of a day, and 24 to specify midnight at the end of a day.
• Durations can be specified as P3W (three weeks), P4D (four days), or PT5H (5 hours). Note the extra T for time durations.

There are four ways you may express a time interval:

Example time intervals

Some example intervals are:

Rate limits

Rate limits apply to all users of the API. These vary with the pricing plan you choose. We limit both the number of in-flight queries per key as well as the total number of calls per key per day. We include the following headers in all responses to explain these limits:

  X-RateLimit-Limit: <the number of requests permitted per window>
  X-RateLimit-Remaining: <the number of requests remaining in the current window>
  X-RateLimit-Reset: <the time, in epoch seconds, when the limit window next resets>

Versioning

We use Semantic Versioning 2.0.0 (see semver.org) to support changes in our API. You may specify the version you wish to use in a header. If you do not specify a version, the API will use the latest available version. Following semver.org, we use MAJOR.MINOR.PATCH to version our API, where MAJOR is incremented when we make incompatible API changes, MINOR is incremented with the addition of backwards-compatible functionality, and PATCH is incremented with backwards-compatible bug fixes.

Indicate the version you would like using an ‘Accept-Version’ header, for example:

Accept-Version: ~1     // for the latest minor and patch of major version 1
Accept-Version: <2.2.0 // for anything before 2.2.0
Accept-Version: *      // for the latest version (or just omit the header)

We do not expect most users to have to specify an API version.

Error Codes

We use HTTP response codes and status messages to provide rich, relevant information about failed queries. You may see the following error codes:

All errors with a 4xx or 5xx response code will include a JSON error message response of
the form:

  { "message": "Incorrect key" }