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 stablev1
version and clients will need to migrate simply by changing the API resource path or package dependency.