# Swap API

### Integration step

You can swap money in three easy steps:

1. Generate a bearer token (see [authentication](https://developers.klasha.com/~/revisions/9BaXSBqKHuDCUL5Mcat0/overview/authentication))
2. Generate a quote for the swap
3. Confirm swap

{% hint style="info" %}
All requests sent to these APIs must be encrypted. The encryption Algorithm can be gotten [here](https://developers.klasha.com/transfers/klasha-wire-api#encryption-algorithm)
{% endhint %}

### **Generate a bearer token**

Use the authentication API [here](https://developers.klasha.com/~/revisions/9BaXSBqKHuDCUL5Mcat0/overview/authentication) to generate a bearer token and set your `Authorization` header to the token obtained.

You’d also need to set your public key as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

In summary, the request headers of all the requests sent to the APIs below should contain the data specified below;

| Name          | Value               | Description                                 |
| ------------- | ------------------- | ------------------------------------------- |
| Authorization | Bearer {{token}}    | token generated from the authentication API |
| x-auth-token  | MERCHANT PUBLIC KEY | public key retrieved from the dashboard     |

### **Generate a quote**

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">{{env\_url}}/wallet/swap/generate/quote</mark>

Call the Create Quote API to generate your quote. See an example of the payload you need to encrypt and send in order to generate your quote.

The encrypted JSON body for the request can be found in the Postman [link](https://api.postman.com/collections/8963555-81a5d469-e054-4630-b7af-827b6d261eef?access_key=PMAT-01J546H4YV5MTX9ZDYTMET8VG7) as well as other APIs.

#### Headers&#x20;

> As specified above

#### Request Body (plain)

| Name                                                  | Type   | Description                                                                                                                  |
| ----------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| sourceCurrency<mark style="color:red;">\*</mark>      | String | Example: NGN                                                                                                                 |
| destinationCurrency<mark style="color:red;">\*</mark> | String | Example: USD                                                                                                                 |
| destinationAmount                                     | String | Amount received by the recipient. Example: 1000.00                                                                           |
| sourceAmount<mark style="color:red;">\*</mark>        | String | Amount sent from the sender. Example: 100.00                                                                                 |
| mode                                                  | String | When the mode is set to "SOURCE", the system will utilize the `sourceAmount`, making the `destinationAmount` field optional. |

#### Request Body (encrypted)

{% tabs %}
{% tab title="Encrypted Request" %}

```json
{
  "message": "encrypted request"
}
```

{% endtab %}
{% endtabs %}

#### Response

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "id": 1,
        "sourceCurrency": "NGN",
        "sourceAmount": 1697792.87,
        "destinationCurrency": "USD",
        "destinationAmount": 1000,
        "destinationFees": 20,
        "sourceFees": 33955.86,
        "rate": 0.000589,
        "transactionStatus": "PENDING",
        "transactionReference": "swap-9b1e2c71-43a2-490b-a0be-e4a0337d0911",
        "quoteToken": "97f20109-54e8-4861-ba12-0ea7d32351e9",
        "createdAt": "2024-08-07T18:56:28.633",
        "updatedAt": "2024-08-07T18:56:28.633"
    }
}
```

{% endtab %}
{% endtabs %}

### **Confirm swap**

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">{{env\_url}}/wallet/swap/initiate</mark>

Call the Confirm swap API to convert your quote into wallet swap transaction.&#x20;

See an example of the payload you need to encrypt and send in order to generate your quote.

The encrypted JSON body for the request can be found in the Postman [link](https://api.postman.com/collections/8963555-81a5d469-e054-4630-b7af-827b6d261eef?access_key=PMAT-01J546H4YV5MTX9ZDYTMET8VG7) as well as other APIs

#### Headers

> As specified above

#### Request Body

| Name                                         | Type   | Description                                          |
| -------------------------------------------- | ------ | ---------------------------------------------------- |
| quoteToken<mark style="color:red;">\*</mark> | String | quote token return from the generate quote API above |

{% tabs %}
{% tab title="Encrypted Request" %}

```json
{
  "message": "encrypted request"
}
```

{% endtab %}

{% tab title="200: OK" %}

```json
Response
{
    "message": "success",
    "error": null,
    "data": {
        "id": 1,
        "sourceCurrency": "NGN",
        "sourceAmount": 1697792.87,
        "destinationCurrency": "USD",
        "destinationAmount": 1000,
        "destinationFees": 20,
        "sourceFees": 33955.86,
        "rate": 0.000589,
        "transactionStatus": "SUCCESSFUL",
        "transactionReference": "swap-9b1e2c71-43a2-490b-a0be-e4a0337d0911",
        "quoteToken": "97f20109-54e8-4861-ba12-0ea7d32351e9",
        "createdAt": "2024-08-07T18:56:28.633",
        "updatedAt": "2024-08-07T18:58:38.426"
    }
}
```

{% endtab %}
{% endtabs %}

### **Fetch all your payments**

> <mark style="color:green;">**GET**</mark> - <mark style="color:$primary;">{{env\_url}}/wallet/swap/fetch/by/reference/{{transactionReference}}</mark>

Call this API to retrieve a swap transaction associated to a swap reference

You’d need to pass the `transactionReference` you obtained when you initiated the swap, as a path variable.

#### Headers

> As specified above

#### Response

{% tabs %}
{% tab title="200: OK " %}

```json
Response
{
    "message": "success",
    "error": null,
    "data": {
        "id": 1,
        "sourceCurrency": "NGN",
        "sourceAmount": 1697792.87,
        "destinationCurrency": "USD",
        "destinationAmount": 1000,
        "destinationFees": 20,
        "sourceFees": 33955.86,
        "rate": 0.000589,
        "transactionStatus": "SUCCESSFUL",
        "transactionReference": "swap-9b1e2c71-43a2-490b-a0be-e4a0337d0911",
        "quoteToken": "97f20109-54e8-4861-ba12-0ea7d32351e9",
        "createdAt": "2024-08-07T18:56:28.633",
        "updatedAt": "2024-08-07T18:58:38.426"
    }
}
```

{% endtab %}
{% endtabs %}

### **Fetch a single payment by quote token**

> <mark style="color:green;">**GET**</mark> - <mark style="color:$primary;">{{env\_url}}/wallet/swap/fetch/by/token/{{quoteToken}}</mark>

Make a call to this API to retrieve all your previously initiated quoted swaps.

You’d need to pass the `quoteToken` you obtained when you initiated the swap, as a path variable.

#### Headers

> As specified above

#### **Response**

{% tabs %}
{% tab title="200: OK " %}

```json
Response
{
    "message": "success",
    "error": null,
    "data": {
        "id": 1,
        "sourceCurrency": "NGN",
        "sourceAmount": 1697792.87,
        "destinationCurrency": "USD",
        "destinationAmount": 1000,
        "destinationFees": 20,
        "sourceFees": 33955.86,
        "rate": 0.000589,
        "transactionStatus": "SUCCESSFUL",
        "transactionReference": "swap-9b1e2c71-43a2-490b-a0be-e4a0337d0911",
        "quoteToken": "97f20109-54e8-4861-ba12-0ea7d32351e9",
        "createdAt": "2024-08-07T18:56:28.633",
        "updatedAt": "2024-08-07T18:58:38.426"
    }
}
```

{% endtab %}
{% endtabs %}

&#x20;

{% hint style="info" %}
Notes

Klasha Swap Statuses

When you generate a quote and confirm the swap, one of the field in the response body is <mark style="color:red;">`transactionStatus`</mark>, here you can find all the possible cases and explanation:

* <mark style="color:orange;">PENDING</mark>: this is the status when a swap gets initialised through the API. This is not a final status.
* <mark style="color:green;">SUCCESSFUL</mark>: the swap was executed successfully. Final status.
* <mark style="color:red;">CANCELLED</mark>: The swap has been cancelled from the Klasha finance/operation team, in result of previous communication with the merchant. Final status.
* <mark style="color:red;">FAILED</mark>: the initiated swap failed to be executed. Final status.
  {% endhint %}

**Quote expiry logic**

After you proceeded generating your quote, you can now convert that quote to confirm a swap transactions.

The confirmation would be successful if the quote is <mark style="color:red;">NOT</mark> expired.

A quote does not expire because of time but just if the rate in our system changed.

{% hint style="info" %}
**Example**

&#x20;If you generate a quote on 1st Oct at 11am and at 3pm the rate changes, you can convert your quote into a initiated payment until 2:59:59pm. Right after, then the rate get updated at 3pm, you won’t be able to confirm the swap with that quote and you’d have to generate a new quote.
{% endhint %}

In case you try to initiate a payment with an expired quote, you’d have a Bad Request response with the the following body:

{% tabs %}
{% tab title="400" %}

```json
{
    "message": "Rate has changed!",
    "error": "RateChangeException",
    "data": null
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.klasha.com/transfers/swap-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.