# Currency Exchange Endpoint

## Currency Exchange

<mark style="color:blue;">`GET`</mark> `api-stg.onekeypayments.com/v3/exchange_rates?country={country}&amount={amount}`

The **`exchange_rates`** endpoint allow you to get the exchange of any currency compared against **USD**.

#### Query Parameters

| Name    | Type   | Description                                                               |
| ------- | ------ | ------------------------------------------------------------------------- |
| country | string | Country ISO code in whose local currency the amount will be converted to. |
| amount  | number | Amount to convert in USD. If none is specified, **`1`** will be assumed.  |

#### Headers

| Name          | Type   | Description                   |
| ------------- | ------ | ----------------------------- |
| Authorization | string | "Bearer " + Read-Only API Key |

{% tabs %}
{% tab title="200 Currency exchange correctly returned." %}

```java
{
  "fx_rate":5.8829,
  "currency":"BRL",
  "converted_amount":58.829
}
```

{% endtab %}

{% tab title="400 The country specified was incorrect" %}

```
```

{% endtab %}

{% tab title="401 Invalid credentials error" %}

```java
{
    "code": 100,
    "description": "Invalid credentials"
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
Please find all the country codes in the [Countries Specifications](https://apidocs.onekeypayments.com/knowledge-base/countries-specifications#details) section.
{% endhint %}

## Description

The **currency exchange** endpoint allows you to check the exchange of any currency against USD.

## Request

In order to start using the Currency Exchange endpoint, you need to:

1. Send the request with **GET** method.
2. Specify a [valid country code](https://apidocs.onekeypayments.com/knowledge-base/countries-specifications#countries-and-currencies) in the request as **QUERY PARAMS**.
3. Optionally, you can send the **amount in USD** you want to convert. Otherwise we will return the exchange for USD 1.
4. Send the **Authorization** header with your read-only API Key as Bearer as follows:

> Authorization: Bearer *your\_read\_only\_key\_here*

### Example request

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

```bash
curl --location --request GET 'https://api-stg.onekeypayments.com/v3/exchange_rates?country=BR&amount=10' \
--header 'Authorization: Bearer your_read_only_key_here'


```

{% endtab %}

{% tab title="JAVA" %}

```java
import java.io.*;
import okhttp3.*;

public class main {
  public static void main(String []args) throws IOException{
    OkHttpClient client = new OkHttpClient().newBuilder()
      .build();
    Request request = new Request.Builder()
      .url("https://api-stg.onekeypayments.com/v3/exchange_rates?country=BR&amount=10")
      .method("GET", null)
      .addHeader("Authorization", "Bearer your_read_only_key_here")
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
  }
}


```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using RestSharp;

namespace HelloWorldApplication {
    class HelloWorld {
        static void Main(string[] args) {
            var client = new RestClient("https://api-stg.onekeypayments.com/v3/exchange_rates?country=BR&amount=10");
            client.Timeout = -1;
            var request = new RestRequest(Method.GET);
            request.AddHeader("Authorization", "Bearer your_read_only_key_here");
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}


```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.onekeypayments.com/v3/exchange_rates?country=BR&amount=10",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer your_read_only_key_here"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;



```

{% endtab %}
{% endtabs %}

## Example Response

```java
{
  "fx_rate":5.8829,
  "currency": "BRL",
  "converted_amount":58.829
}
```

###

### Response fields

| Field name         | Format | Description                                                                                                                             |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `fx_rate`          | Number | Currency exchange                                                                                                                       |
| `currency`         | String | [Currency](https://apidocs.onekeypayments.com/knowledge-base/countries-specifications#countries-and-currencies) used for the conversion |
| `converted_amount` | Number | Amount resulting from multiplying the `amount` you sent with the `fx_rate`                                                              |