> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amberdata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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](http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). |

### 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:

```bash theme={null}
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 [support@amberdata.io](mailto:support@amberdata.io).

**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.