Coin Metrics formats time in accordance with the ISO 8601 standard. As such, the following formats for time parameters in the query string are supported:
Note the Z suffix in requests is optional. All dates in the query parameters are in the UTC timezone by default. All responses are always in the UTC timezone and with nanoseconds precision.
Monetary amounts are provided as strings and with the same order of magnitude as the one used for pricing. For Bitcoin, the primary format is the native BTC unit (e.g., 1 BTC, 0.29938 BTC) as opposed to any subformat, such as satoshis, which represent one hundred millionth of a Bitcoin.
Large lists may be split into pages. In accordance with Coin Metrics' API v4, page size has a default value of 100 and can be changed using a
page_sizeparameter. The maximum page size supported is 10,000.
If a response contains the
next_page_urlfield at the top level of the JSON response, it means the client can request the next page of results by fetching the provided URL without any modifications.
Coin Metrics' API v4 API uses the HTTP/2 protocol.
To ensure the quality of Coin Metrics services, our API is subject to rate limiting. If you reach the limit, the API will begin to return
429 Too Many RequestsHTTP response status. The API also provides
X-RateLimit-*response headers formatted according to https://tools.ietf.org/html/draft-polli-ratelimit-headers-03.
The community version of API has a limit of 1,000 requests per 10 minutes sliding window for an IP address. It corresponds to 1.6 RPS.
The paid version of API has a limit of 6,000 requests per 20 seconds sliding window for an API key. It corresponds to 300 RPS.
We use the default WS protocol ping/pong mechanism. There are some restarts occasionally because it goes through Cloudflare, so you should have some logic in place to automatically reconnect.
- Backward incompatible changes increase the major number.
- Backward compatible changes increase the minor number.
- Backward compatible bug fixes increase the patch number.
Major versions of the API are run in parallel. The choice of what major API version to use is up to the client, although clients are advised to use the highest stable version.
Major versions can be marked as either stable or unstable. As backward-incompatible changes can be introduced only in unstable or development major versions, no breakage is expected when using fixed, stable major API versions (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 a (generally long-term) deprecation schedule. This should give clients time to adapt their implementations to the new major version.
Minor and patch releases replace old minor/patch API versions, under the same major version. Old minor/patch API versions become inaccessible following these releases.
Recently introduced versions of the API may be explicitly labeled "unstable". Unstable API versions are fully tested, usable by clients, and have complete documentation. However, an unstable API version is not covered by the backward compatibility rules below and can receive arbitrary changes at any time without any warning. Unstable API versions should be used only for evaluation of new features. It is not advised to use unstable versions in production systems.
New major versions of the API are expected to be marked unstable, and after a period of stabilization and testing become permanently stable.
The newest version of the API may be explicitly labeled "development". Development API versions may receive arbitrary changes at any time and may also have wrong/incomplete implementation, documentation, or other critical issues. Generally, development API versions should be completely avoided, as there are no guarantees about how well it works, or whether it works at all.
A change is considered backward compatible when an API client built for an old version of the API still works with the new version. Hence, it is important that clients use correct assumptions about what details of the API they can rely on.
Generally, changes to the API interface and functionality will follow this policy as outlined above. However, breaking changes may still be made without introducing a new major version, if it is needed for continuous operation of Coin Metrics' services, for security reasons, or for other reasons, if following this policy is deemed to be infeasible. That may include, but is not limited to, the following: introducing or changing request rate limits, applying specific limits per specific API key, immediate disabling of specific methods or features, etc. Changes also can be made to this policy.
Such emergency changes are expected to be rare exceptions and would be conducted only after careful assessment of the impact to clients. In the event of such a change, Coin Metrics would provide as much advance notice as possible.