# Foreign Currency Exchange

## Overview

The Foreign Exchange module provides the infrastructure to carry out currency exchanges on behalf of customers —a particularly important feature for platforms that accommodate multiple currencies. This module includes a series of endpoints tailored to the needs of users looking to perform, monitor, and manage asset exchanges for their customers.

Offering functions from quoting to execution, along with detailed tracking mechanisms, the Foreign Exchange module endpoints include:

1. [**Get Available Currency Pairs**](#get-available-currency-pairs): Provides a full list of currency pairs available for exchange.
2. [**Get Account Details**](#get-account-details): This endpoint will return available source and destination accounts the customer can choose to do the exchange.
3. [**Get Quote for Exchange**](#get-quote-for-exchange)**:** Provides an estimate for an exchange, detailing the source and destination amount before the actual exchange is executed, ensuring that the customer is informed about the potential transaction.
4. [**Execute Exchange**](#execute-exchange)**:** Execute the quote exchange using the id received from the quote for exchange.

Overall, the Exchange module is designed to offer a seamless and secure experience for handling the exchange requirements of customers, ensuring that users can manage these operations effectively with great precision and control.

***

## Get Available Currency Pairs

Provides a full list of asset pairs enabled for the API user. The response will also include information on limits and minimums associated with each asset pair for exchanges.

* **Endpoint:** `/api/v1/customer/foreign-exchanges/pairs`
* **Method:** `GET`

{% openapi src="/files/LzwQu0gRokM1pqinJ26Q" path="/api/v1/customer/foreign-exchanges/pairs" method="get" %}
[publicapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-3f41179f70977055e3425370d7bea65077bb3152%2Fpublicapi.json?alt=media)
{% endopenapi %}

**Success Response Example:**

```json
{
    "id": 14107,
    "details": [
        {
            "baseAsset": "CNH",
            "exchangeAsset": "SGD"
        },        
        {
            "baseAsset": "EUR",
            "exchangeAsset": "CHF"
        },
        {
            "baseAsset": "GBP",
            "exchangeAsset": "SGD"
        },
        {
            "baseAsset": "USD",
            "exchangeAsset": "SGD"
        }
    ],
    "pageSize": 100,
    "pageNumber": 1,
    "numberOfPages": 1,
    "status": "1",
    "errors": []
}
```

## Get Account Details

Provides list of source and destination accounts based on the source and destination currency provided for the customer.

* **Endpoint:** `/api/v1/customer/foreign-exchanges/account-details`
* **Method:** `GET`

{% openapi src="/files/LzwQu0gRokM1pqinJ26Q" path="/api/v1/customer/foreign-exchanges/account-details" method="get" %}
[publicapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-3f41179f70977055e3425370d7bea65077bb3152%2Fpublicapi.json?alt=media)
{% endopenapi %}

**Success Response Example:**

```json
{
    "id": 14107,
    "details": {
        "sourceAsset": "GBP",
        "destinationAsset": "SGD",
        "fromAccounts": [
            {
                "accountID": "3140",
                "displayName": "GBP Account",
                "currencySymbol": "£",
                "balance": 5159.54
            }
        ],
        "toAccounts": [
            {
                "accountID": "3146",
                "displayName": "SGD Account",
                "currencySymbol": "S$",
                "balance": 2399.32
            }
        ]
    },
    "status": "1",
    "errors": []
}
```

## Get Quote for Exchange

This endpoint provides a quoted market price for a proposed asset exchange for a particular customer, detailing the source and destination amount for either a "Buy" or "Sell" exchange type. By specifying details of the desired trade, a customer can see the cost or proceeds they might expect from completing a transaction, including any applicable fees. This helps customers decide whether to proceed with an exchange based on real-time financial data.

* **Endpoint:** `/api/v1/customer/foreign-exchanges/quote`
* **Method:** POST

{% openapi src="/files/LzwQu0gRokM1pqinJ26Q" path="/api/v1/customer/foreign-exchanges/quote" method="post" %}
[publicapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-3f41179f70977055e3425370d7bea65077bb3152%2Fpublicapi.json?alt=media)
{% endopenapi %}

**Request Example:**

```json
{
    "SourceCurrency": "GBP",
    "DestinationCurrency": "SGD",
    "SourceAmount": "100",
    "SourceAccountId": 3140,
    "DestinationAccountId":3146
}
```

**Success Response Example:**

```json
{
    "id": 1,
    "details": {
        "sourceAmount": 100,
        "destinationAmount": null,
        "quoteSourceAmount": null,
        "quoteDestinationAmount": 167.89,
        "sourceAmountLessFees": 99.5,
        "comissionFees": 0.5,
        "totalFees": 0.5,
        "quotedFXRate": "1.687312",
        "quotedFXRateID": 1423,
        "quotedFxRateExpiry": "2024-08-19T14:13:22.6153953Z"
    },
    "status": "1",
    "errors": []
}
```

#### Possible Error Codes

<table><thead><tr><th width="268">Error Message Code</th><th>Description</th></tr></thead><tbody><tr><td>Required</td><td>Named field missing or zero</td></tr><tr><td>Invalid</td><td>Value given for named field is invalid</td></tr><tr><td>No_Account</td><td>No source account details found</td></tr><tr><td>Insufficient_Funds</td><td>Source account do not have enough funds to performa the exchange</td></tr></tbody></table>

***

## Execute Exchange

This endpoint is designed to initiate a sell exchange, allowing a customer to sell an asset at a given price or for a specific amount.

* **Endpoint:** `/api/v1/customer/foreign-exchanges/executeexchange`
* **Method:** `POST`

{% openapi src="/files/LzwQu0gRokM1pqinJ26Q" path="/api/v1/customer/foreign-exchanges/executeexchange" method="post" %}
[publicapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-3f41179f70977055e3425370d7bea65077bb3152%2Fpublicapi.json?alt=media)
{% endopenapi %}

#### Request Body Example:

```json
{
    "FxRateId": 1423,
    "PurposeCode": "test"
}
```

#### Success Response Example:

```json
{
    "id": 14589,
    "details": {},
    "status": "1",
    "errors": []
}
```

#### Possible Error Codes

| Error Message Code       | Description                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| Required                 | Named field missing or zero                                       |
| Invalid                  | Value given for named field is invalid                            |
| Documents\_Not\_Verified | Cannot perform this action for this customer due to the KYC state |

***

```json
```


---

# 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://customer-api-docs.ibanera.com/api-endpoints/fx-exchanges.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.