Coin Metrics API Versioning Policy

The list of currently available versions is available at API documentation home page.

What version to use?

If you just started working with Coin Metrics API, use the latest stable version.

If you are already using some stable version, you are encouraged to switch to the latest stable version eventually. Later stable version usually provides more features and other improvements. You can also use multiple versions simultaneously.

In any case no development version should be ever used in production.


Major versions of API are run in parallel. The choice of what major API version to use is up to a client.

Major versions can be marked as stable or unstable. As backward incompatible changes can be introduced only in unstable or development major version, no breakage is expected when using fixed stable major API version (and adhering to safety guidelines below).

New major API releases are to be added alongside old major API versions, so clients of old (stable) versions are not affected. Old major API versions may be gradually deprecated and removed, following (generally long-term) deprecation schedule, giving clients time to adapt their implementations to new major version.

Minor and patch releases replace old minor/patch API version, under the same major version. Old minor/patch API version becomes inaccessible.

Unstable major versions

Recently introduced version of API may be explicitly labeled "unstable". Unstable API version is meant to be fully tested, usable by clients, and have complete documentation. However unstable API is not covered by the backward compatibility rules below, and can receive arbitrary changes at any time without any warning. It is advised to not use it in production. Use it only for evaluation of new features.

New major versions of API are expected to be marked unstable, and after period of stabilization and testing become permanently stable.

Development major versions

The newest version of API may be explicitly labeled "development". Development API version is not only may receive arbitrary changes at any time, but it also can have wrong/incomplete implementation, documentation, or other critical issues. Generally development API version should be completely avoided, as there's no guarantees at all about how well it works, or whether it works at all.

Backward compatible changes

Change is backward compatible when an API client built for old version of API still works with new version. Hence it is important that API clients use correct assumptions about what details of API they can rely on.

Changes considered backward-compatible (can be introduced in minor or patch API version)

These changes can be introduced in minor or patch API version. Please follow the recommendations below to not get your integration broken.

Changes considered backward-incompatible

These changes can only be introduced in new major API version, or unstable major API version. It is safe to assume it will not happen while you use fixed stable major API version.

Emergency changes

Generally changes to API interface and functionality will follow this policy as outlined above. However breaking changes may still be made without introducing new major version, if it is needed for continuous operation of our services, for security reasons, or for other reasons, if following this policy is not deemed possible. That may include, but not limited to, the following: introducing or changing request rate limits, applying specific limits per specific API key, immediate disabling of specific method or feature, and so on. Changes also can be made to this policy.

Such emergency changes are expected to be an exception, not a rule, and should be conducted only after assessment of impact for clients, and with as much advance notice as possible.