API Fundamentals

The Amberdata API delivers comprehensive market and on-chain data through RESTful endpoints. This guide outlines the key concepts and best practices to help you integrate our API quickly and effectively.

Authentication

All requests to our servers require a unique user-specific API Key. Requests without a valid API Key will be refused.

Usage

Every request (with the exception of WebSockets) requires the x-api-key header:

curl --request GET 
     --url 'https://api.amberdata.com/markets/spot/trades/eth_usd' 
     --header 'Accept-Encoding: gzip, deflate, br' 
     --header 'Accept: application/json'
     --header 'x-api-key: YOUR_API_KEY'

HTTP Response Structure

The body of every response includes the following fields:

Field	Description
description	Description of the response.
payload	The object containing the actual data requested.
status	The status of the response.
title	The human readable name associated with the HTTP status according to the HTTP Status Code Registry.

Response Codes

In an erroneous response, the description field will indicate the reason for the error.

Status Code	Description
200	Successful Request
400	Bad Request – Invalid request format or query results exceed 10 MB limit
401	Unauthorized – Invalid or missing API Key
403	Forbidden – Access to endpoint is not authorized
404	Not Found – instrument or address does not exist for example
429	Too Many Requests – rate limit was exceeded
5xx	Internal Server Error – We had a problem with our server
502	Bad Gateway
504	Gateway Timeout – Exceeded 28 second limit

API Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. To set the API version on a specific request, use the api-version header:

curl --request GET 
     --url 'https://api.amberdata.com/markets/spot/trades/eth_usd' 
     --header 'Accept-Encoding: gzip, deflate, br' 
     --header 'Accept: application/json'
     --header 'api-version: 2023-09-30' 
     --header 'x-api-key: YOUR_API_KEY'

Backwards Compatible Changes

Amberdata considers the following changes to be backwards-compatible:

• Adding new API resources
• Adding new optional request parameters to existing API methods
• Adding new properties to existing API responses
• Changing the order of properties in existing API responses
• Changing the length or format of opaque, Amberdata generated strings, such as object IDs, error messages, and other human-readable strings

Note: Trading pairs, instruments, asset symbols etc. are not considered opaque. Such strings could only be modified with a new dated version.

Rate Limits

Subscription	API Key Type	Description	Rate Limits / Daily Quotas
Trial Access	UAT	Temporary access to all API endpoints and datasets.	15 calls/sec - 20k / day
On-Demand Order	UAO	Paid subscription for production usage of data (for select markets/exchanges only, ie. Spot/Coinbase, Options/Deribit, etc.)	20 calls/sec - 250k / day
Enterprise	UAK	Paid subscription for production usage of data.	60 calls/sec

On-Demand Order Subscriptions

On-Demand order subscriptions are provisioned upon successful payment after completing the order form. Customers must pay upfront via credit card, and API keys are typically provisioned within 24-48 business hours.

On-Demand order subscriptions are limited to Market Data endpoints and do not include white-glove support services. Customers requiring assistance can contact [e-mail].

Examples of Supported and Unsupported API Calls:

On-Demand order subscriptions are restricted to specific markets and exchanges. For example, if a customer purchases a subscription for Spot GDAX:

Supported Calls:

• /markets/spot/tickers?exchange=gdax
• /markets/spot/trades?exchange=gdax&pair=btc_usd
• /markets/spot/order-book-snapshots/btc_usd?exchange=gdax

Unsupported Calls:

• /markets/spot/tickers (missing exchange=gdax)
• /markets/spot/trades?exchange=kraken (subscription is for GDAX only)
• /markets/futures/tickers?exchange=gdax (subscription does not include Futures)

Specify the correct exchange and use endpoints in your subscription to avoid issues.