# Overview

## Endpoints

Learn more about the different endpoints of the Swap API:

* [GET /rfq/pool](https://docs.clipper.exchange/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/pool) - Get information about a blockchain network supported by Clipper.
* [POST /rfq/quote](https://docs.clipper.exchange/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/quote) - Generate potential asset swap quotes. Obtain pricing and essential details for informed decision-making.
* [POST /rfq/sign](https://docs.clipper.exchange/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/sign) - Facilitates blockchain transaction preparation and security by returning the required signature and data. Use it for efficient and secure asset swaps.

## Authorization

To prevent abuse of the API, we implement rate limits on requests. If you need to bypass these limits as an aggregator, please contact our support team to get API credentials (username and password) [here](mailto:aggregators@shipyardsoftware.org).

These credentials are used to authorize requests made to the following endpoints: <mark style="color:orange;">`/rfq/pool`</mark> , <mark style="color:orange;">`/rfq/quote`</mark> and <mark style="color:orange;">`/rfq/sign`</mark>

#### Basic Authentication

{% hint style="danger" %}
DEPRECATED: If you are using Basic Authentication, please contact us to receive an API key.
{% endhint %}

The API uses the Basic authentication method, where you must include the credentials (<mark style="color:orange;">`username:password`</mark>) in the headers in <mark style="color:orange;">`Base64`</mark> format.

**Example:**

If your username is "<mark style="color:orange;">`clipper`</mark>" and your password is "<mark style="color:orange;">`clipperdocs`</mark>", the Base64 encoded string for <mark style="color:orange;">`clipper:clipperdocs`</mark> is <mark style="color:orange;">`Y2xpcHBlcjpjbGlwcGVyZG9jcw==`</mark>.

```bash
curl --location 'https://api.clipper.exchange/rfq/quote' \
--header 'Authorization: Basic Y2xpcHBlcjpjbGlwcGVyZG9jcw==' \
--header 'Content-Type: application/json' \
--data '{
  "input_amount": "780000000000000",
  "input_asset_symbol": "ETH",
  "output_asset_symbol": "DAI",
  "time_in_seconds": 60,
  "chain_id": 1
}
'
```

#### Api Key Authentication

The API uses the API KEY authentication method. You have to include the credentials in the header <mark style="color:orange;">`x-api-key`</mark>.

Example: If your api key is <mark style="color:orange;">TzuiYrpRgN2</mark>

```bash
curl --location 'https://api.clipper.exchange/rfq/quote' \
--header 'x-api-key: TzuiYrpRgN2' \
--header 'Content-Type: application/json' \
--data '{
  "input_amount": "780000000000000",
  "input_asset_symbol": "ETH",
  "output_asset_symbol": "DAI",
  "time_in_seconds": 60,
  "chain_id": 1
}
'
```

{% hint style="danger" %}
The API v1 currently supports both API Key and Basic Authentication. However, Basic Authentication will be deprecated in the future. \
\
**Note**: The Pool endpoint currently only supports Basic Authentication. To use API Key authentication, use the [Pool V2](https://docs.clipper.exchange/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/pool-v2) endpoint.
{% endhint %}

### Errors

#### Common Error Codes

<table><thead><tr><th width="118">Code</th><th>Reason</th></tr></thead><tbody><tr><td>400</td><td>Bad Request - Invalid data in the request</td></tr><tr><td>401</td><td>Unauthorized</td></tr><tr><td>403</td><td>Forbidden Error</td></tr><tr><td>500</td><td>Internal Server Error</td></tr><tr><td>503</td><td>External Service Error</td></tr></tbody></table>

#### Error Format

```json
{
    "errorMessage": "Description of the error",
    "errorType": "Type of the error",
    "errorCode": 422,  // it is returned only when we have a clipper code for the error
    "data": []  // is is returned only when the input data is invalid
}
```

{% hint style="warning" %} <mark style="color:orange;">`error_code`</mark> and <mark style="color:orange;">`data`</mark> are not always present
{% endhint %}

*Examples*&#x20;

1. If we make a request to [quote](https://docs.clipper.exchange/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/quote) endpoint and the body does not have the field <mark style="color:orange;">`chain_id`</mark> (required param), the API response will look like similar to this:

```json
{
    "errorMessage": "Invalid input data",
    "errorType": "BadData",
    "errorCode": 422,
    "data": [
        {
            "type": "missing",
            "loc": [
                "chain_id"
            ],
            "msg": "Field required",
            "input": {
                "input_amount": "18000",
                "input_asset_symbol": "ETH",
                "output_asset_symbol": "WBTC",
                "time_in_seconds": 60
            },
            "url": "https://errors.pydantic.dev/2.1/v/missing"
        }
    ]
}
```

2. If we make a request to [quote](https://docs.clipper.exchange/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/quote) endpoint and we send an <mark style="color:orange;">`input_asset_symbol`</mark> that clipper does not support, the API response will look like similar to this

```json
{
    "errorMessage": "input_asset_symbol: INVALIDASSET is not supported",
    "errorType": "BadData"
}
```

3. If we make a request to [quote](https://docs.clipper.exchange/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/quote) endpoint and we send invalid credentials

```json
{
    "errorMessage": "Auth: Access is forbidden",
    "errorType": "Forbidden"
}
```

#### Clipper Error Codes

These codes appear in the field <mark style="color:orange;">`errorCode`</mark>

<table><thead><tr><th width="112">Code</th><th>Reason</th></tr></thead><tbody><tr><td>422</td><td>Invalid input data</td></tr><tr><td>409</td><td>Quote problems</td></tr></tbody></table>