# 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

Encryption Algorithm can be gotten [here](https://developers.klasha.com/transfers/klasha-wire-api#encryption-algorithm)

#### **Generate a bearer token**

Use the token obtained [here](https://developers.klasha.com/~/revisions/9BaXSBqKHuDCUL5Mcat0/overview/authentication) as the Bearer token on all request headers here. 

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

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

| Name          | Value               |
| ------------- | ------------------- |
| Authorization | Bearer {{token}}    |
| x-auth-token  | MERCHANT PUBLIC KEY |

#### Request Body

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

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

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

{% endtab %}

{% 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

| Name          | Value               |
| ------------- | ------------------- |
| Authorization | Bearer {{token}}    |
| x-auth-token  | MERCHANT PUBLIC KEY |

#### Request Body

| Name                                         | Type   | Description                          |
| -------------------------------------------- | ------ | ------------------------------------ |
| quoteToken<mark style="color:red;">\*</mark> | String | 97f20109-54e8-4861-ba12-0ea7d32351e9 |

{% 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>

Make a GET call to the Fetch by swap reference to retrieve a swap transaction.

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

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

#### Headers

| Name          | Value               |
| ------------- | ------------------- |
| Authorization | Bearer {{token}}    |
| x-auth-token  | MERCHANT PUBLIC KEY |

{% 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**

## Fetch by token API to retrieve all your previously initiated quoted swaps.

<mark style="color:blue;">`GET`</mark> <mark style="color:red;">`{{env_url}}`</mark>`/wallet/swap/fetch/by/token/`<mark style="color:red;">`{{quoteToken}}`</mark>

Make a GET call to the Fetch by token 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.

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

#### Headers

| Name          | Value               |
| ------------- | ------------------- |
| Authorization | Bearer {{token}}    |
| x-auth-token  | MERCHANT PUBLIC KEY |

{% 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:

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


---

# 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/~/revisions/9BaXSBqKHuDCUL5Mcat0/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.