# Exchange rate

The method returns the **conversion rate** between two currencies for the specified project. Use it before calculating payment or payout amounts in another currency.

HTTP request format is in [API request format](./init-request.md).

## How it works

1. **Request** — your server calls `get_rate` with `partner_id`, `project_id`, `currency_from`, `currency_to`, and `sign` signature.
2. **Verification** — the API verifies the signature and partner access to the project.
3. **Response** — JSON with `rate`: how many units of `currency_to` correspond to one unit of `currency_from`.

## Technical details

| | |
| --- | --- |
| **Endpoint** | `https://api.1payment.com/get_rate` |
| **Method** | `GET` |
| **Response format** | JSON |
| **Authorization** | API Key — used in `sign` signature generation |

## Request parameters

### Required

| Parameter | Type | Description |
| --- | --- | --- |
| `partner_id` | Integer | Your unique ID in the 1Payment system. |
| `project_id` | Integer | Project identifier. |
| `currency_from` | String | Source currency (ISO code, e.g. `usdt`). |
| `currency_to` | String | Target currency (ISO code, e.g. `rub`). |
| `sign` | String | Request signature (see "Signature" section). |

## Signature generation (`sign`)

Signature: MD5, lowercase (hex). General rules — [API request format](./init-request.md#request-signature-sign).

**Formula:**

```text
MD5(get_rate + <parameters_without_sign_in_alphabetical_order_joined_by_&> + <API_KEY>)
```

**Example string before hashing:**

```text
get_ratecurrency_from=usdt&currency_to=rub&partner_id=1234&project_id=5678secret_key
```

### Signature verification in the documentation

{% signatureVerifier method="get_rate" preset="get_rate" /%}

## Request examples

{% codeTabs %}
{% tab label="Node.js" %}

```javascript
const crypto = require('crypto');
const axios = require('axios');

async function getRate(apiKey, partnerId, projectId, currencyFrom, currencyTo) {
  const params = {
    partner_id: partnerId,
    project_id: projectId,
    currency_from: currencyFrom,
    currency_to: currencyTo,
  };

  // 1. Сортировка параметров по алфавиту
  const sortedKeys = Object.keys(params).sort();
  const queryString = sortedKeys.map((key) => `${key}=${params[key]}`).join('&');

  // 2. Подпись с префиксом get_rate
  const baseString = `get_rate${queryString}${apiKey}`;
  params.sign = crypto.createHash('md5').update(baseString).digest('hex');

  // 3. GET-запрос
  const response = await axios.get('https://api.1payment.com/get_rate', { params });
  return response.data;
}

const apiKey = process.env.ONEPAYMENT_API_KEY;
getRate(apiKey, 1234, 5678, 'usdt', 'rub').then(console.log);
```

{% /tab %}
{% tab label="Python" %}

```python
import hashlib
import os
import requests

def get_rate(
    api_key: str,
    partner_id: int,
    project_id: int,
    currency_from: str,
    currency_to: str,
) -> dict:
    params = {
        "partner_id": partner_id,
        "project_id": project_id,
        "currency_from": currency_from,
        "currency_to": currency_to,
    }

    # 1. Сортировка параметров
    sorted_keys = sorted(params.keys())
    query_string = "&".join(f"{k}={params[k]}" for k in sorted_keys)

    # 2. Подпись get_rate
    base_string = f"get_rate{query_string}{api_key}"
    params["sign"] = hashlib.md5(base_string.encode("utf-8")).hexdigest()

    # 3. GET-запрос
    response = requests.get("https://api.1payment.com/get_rate", params=params)
    response.raise_for_status()
    return response.json()

api_key = os.environ["ONEPAYMENT_API_KEY"]
print(get_rate(api_key, 1234, 5678, "usdt", "rub"))
```

{% /tab %}
{% tab label="PHP" %}

```php
<?php

function getRate(
    string $apiKey,
    int $partnerId,
    int $projectId,
    string $currencyFrom,
    string $currencyTo
): string {
    $params = [
        'partner_id' => $partnerId,
        'project_id' => $projectId,
        'currency_from' => $currencyFrom,
        'currency_to' => $currencyTo,
    ];

    // 1. Сортировка параметров по алфавиту
    ksort($params, SORT_LOCALE_STRING);
    $tail = '';
    foreach ($params as $k => $v) {
        if ($k === 'sign') {
            continue;
        }
        $tail .= "{$k}={$v}&";
    }
    $tail = substr($tail, 0, -1);

    // 2. Формирование подписи (префикс get_rate)
    $params['sign'] = md5('get_rate' . $tail . $apiKey);

    // 3. Запрос к API
    $url = 'https://api.1payment.com/get_rate?' . http_build_query($params);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);

    return $response;
}

$apiKey = getenv('ONEPAYMENT_API_KEY');
echo getRate($apiKey, 1234, 5678, 'usdt', 'rub');
```

{% /tab %}
{% tab label="cURL" %}

```bash
# Подпись: md5("get_rate" + currency_from=usdt&currency_to=rub&partner_id=1234&project_id=5678 + API_KEY)

curl -sS "https://api.1payment.com/get_rate?partner_id=1234&project_id=5678&currency_from=usdt&currency_to=rub&sign=PASTE_MD5_HEX"
```

{% /tab %}
{% /codeTabs %}

## API response

Successful response (`200`):

```json
{
  "rate": 72.44
}
```

| Field | Type | Description |
| --- | --- | --- |
| `rate` | Number | Conversion rate `currency_from` → `currency_to`. |

Request error (`400`):

```json
{
  "error_code": 2
}
```

`error_code` meanings — in [Error codes (API)](./error-codes-api.md).

## Related sections

- [API request format](./init-request.md)
- [Balance request](./balance.md)
- [Payout types](./payout-types.md)