Introduction

General

The Mnemonic API is organized around gRPC/Protobuf and REST. Our API has predictable resource-oriented structure and URLs, returns JSON-encoded or Protobuf-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

All endpoints by default support both encodings and transports, and you can learn more about using gRPC and REST on their respective pages.

Authentication

The Mnemonic API uses API keys to authenticate requests. You can view your your API keys in the Mnemonic Developer Portal.

Currently, only one API key is allowed per account, however, we are working on extending this functionality to multiple keys per account and teams.

Be sure to keep your API keys secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

The API key must be set per-request using X-API-Key HTTP header or as part of the outgoing context metadata in case of gRPC with the key x-api-key.

All REST API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. All gRPC connections must use TLS transport configuration.

Errors

Mnemonic uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., an invalid argument provided, a required parameter was missing, etc.). Codes in the 5xx range indicate an error with Mnemonic's servers, and are generally rare.

Read more about Errors handling.

Pagination

Most Mnemonic APIs support pagination, except those where a singular result is expected. All APIs that support pagination share a common structure, taking at least two parameters: limit and offset. In some cases, a timestamp is used as a third parameter to indicate the starting point for pagination, example is Transfers and blockTimestampGt parameter.

In order to scroll through all available results simply increment offset parameter by limit value and continue requesting until no results are returned.

Versioning

We take versioning and backwards-compatibility very seriously. When backwards-compatible changes are made to the API, a new, dated version is released. Clients who use Protobuf and gRPC should pull a new version from our buf repository.

All changes are documented and published in our API changelog.

Any backwards-incompatible changes are introduced only under new versioned packages (i.e. v1beta2 etc).

Note: Later this year our v1beta1 APIs will be promoted to stable v1 version and clients will need to migrate simply by changing the API resource path or package dependency.