> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 报价货币转换

获取实时货币兑换报价，享受基于安全令牌的汇率，满足您的国际交易需求。

货币兑换报价 API 允许您获取不同货币之间的汇率，并收到一个安全令牌，该令牌会在指定时间内锁定报价汇率。这既能确保您后续交易的汇率稳定性，又能有效抵御市场波动的影响。

## 先决条件

在索取货币兑换报价之前，请确保您已具备以下条件：

* **具有货币兑换权限的有效 API 凭证**。
* **源货币和报价货币的有效账号**。

***

## API endpoint

要获取兑换报价，请向[获取外汇报价](https://docs.localpayment.com/zh/reference/currency-exchange-quote.md)endpoint 发送 `GET` 请求。

### endpoint

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
GET https://api.stage.localpayment.com/api/fx/currency-exchange/{type}
```

将 `{type}` 替换为与您的使用场景相符的交易类型：

| `{type}` | 何时使用 |
| - | - |
| `payin` | 您希望在收到付款前显示汇率。 |
| `payout` | 您希望在付款前显示汇率。 |
| `CurrencyExchange` | 你想在发送货币转换之前显示汇率。 |

### 验证

请在请求头中包含您的访问令牌：

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
```

### 关键请求参数

| 参数 | 类型 | 描述 |
| - | - | - |
| `sourceCurrency` | string | 您要转换的货币（例如 `"ARS"`、`"USDT"`） |
| `quoteCurrency` | string | 您要转换成的货币（例如 `"USD"`） |
| `accountNumber` | string | 您的 Localpayment 账户，其中持有**源货币**（即被扣款的账户） |
| `quoteAccountNumber` | string | 您的 Localpayment 账户，其中持有**目标货币**（即待入账账户） |

### 示例请求

> [tab] 本地货币（PayIn）
>
> ```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request GET \
>      --url 'https://api.stage.localpayment.com/api/fx/currency-exchange/payin?sourceCurrency=ARS&quoteCurrency=USD&accountNumber={{sourceAccountNumber}}&quoteAccountNumber={{quoteAccountNumber}}' \
>      --header 'Authorization: Bearer <your_access_token>' \
>      --header 'accept: application/json'
> ```

> [tab] 稳定币（USDC / USDT）
>
> ```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request GET \
>      --url 'https://api.stage.localpayment.com/api/fx/currency-exchange/CurrencyExchange?sourceCurrency=USDT&quoteCurrency=USD&accountNumber={{sourceAccountNumber}}&quoteAccountNumber={{quoteAccountNumber}}' \
>      --header 'Authorization: Bearer <your_access_token>' \
>      --header 'accept: application/json'
> ```

***

## 响应处理

### 成功响应

成功的请求会返回带有安全令牌的汇率信息：

> [tab] 本地货币（PayIn）
>
> ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> {
>   "exchangeRateToken": "5c3q89a7-f1bc-4ba5-a3b5-411ba0d144ca",
>   "transactionType": "PayIn",
>   "accountNumber": "{{sourceAccountNumber}}",
>   "sourceCurrency": "ARS",
>   "creationDate": "2024-12-27T21:33:32.6513692+00:00",
>   "expirationDate": "2024-12-28T05:33:32.6513692+00:00",
>   "quotes": [
>     {
>       "paymentMethodCode": "1005",
>       "rate": 0.0008369108482392735,
>       "quoteCurrency": "USD"
>     },
>     {
>       "paymentMethodCode": "1023",
>       "rate": 0.0008369108482392735,
>       "quoteCurrency": "USD"
>     },
>     {
>       "paymentMethodCode": "1000",
>       "rate": 0.0008369108482392735,
>       "quoteCurrency": "USD"
>     }
>   ]
> }
> ```

> [tab] 稳定币（USDC / USDT）
>
> ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> {
>   "accountNumber": "{{sourceAccountNumber}}",
>   "creationDate": "2026-01-15T21:03:06.2722727Z",
>   "exchangeRateToken": "b4eb8276-8edc-43e6-937d-97ecd98ea902",
>   "expirationDate": "2026-01-15T21:14:06.2722727Z",
>   "quotes": [
>     {
>       "paymentMethodCode": null,
>       "quoteAccountNumber": "{{quoteAccountNumber}}",
>       "quoteCurrency": "USD",
>       "rate": 1
>     }
>   ],
>   "sourceCurrency": "USDT",
>   "transactionType": "CurrencyExchange"
> }
> ```

#### 关键响应字段

| 字段 | 类型 | 描述 |
| - | - | - |
| `exchangeRateToken` | string | 用于后续交易的唯一令牌 |
| `transactionType` | string | 交易类型（PayIn、PayOut） |
| `accountNumber` | string | 源货币账户（借方账户） |
| `sourceCurrency` | string | 源货币代码 |
| `creationDate` | datetime | 报价创建时 |
| `expirationDate` | datetime | 报价到期时 |
| `quotes` | array | 可用的支付方式及其费率 |

### 错误响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "detail": "You do not have permission to perform this action."
}
```

***

## 最佳实践

### 安全与性能

* API 请求务必使用 HTTPS。
* 妥善保管访问令牌并定期轮换使用。
* 密切关注令牌过期时间。
* 请适当缓存报价，但须遵守过期时间。

### 重要提示：令牌过期

汇率令牌的有效期有限。请规划好您的交易流程，确保在有效期内完成。报价汇率仅在令牌有效期间内有效。

> [!NOTE]
>
> **专业提示**
>
> 不同的付款方式可能提供不同的汇率。请查看 `quotes` 数组中的所有可用选项，为您的使用场景选择最优惠的汇率。

***

## 集成工作流程

1. **获取报价**：请求您所需货币对的汇率。
2. **选择方式**：从报价中选择最佳付款方式。
3. **保存令牌**：保存 `exchangeRateToken`，用于您的交易。
4. **执行交易**：在支付 API 调用中使用该令牌。
5. **监控到期时间**：请在 `expirationDate` 之前完成交易。

***

## 后续步骤

> [card] [PayIn 处理](https://docs.localpayment.com/zh/reference/payins.md)
>
> 使用您转换后的货币处理收款。

> [card] [PayOut 处理](https://docs.localpayment.com/zh/reference/create-a-payout.md)
>
> 使用您转换后的货币处理付款。

> [card] [执行货币兑换](https://docs.localpayment.com/zh/reference/exchange-bulk.md)
>
> 使用您的汇率令牌执行货币转换。

> [!NOTE]
>
> **专业提示**
>
> 在我们的沙盒环境中对您的工作流程进行全面测试。这可以确保您的集成在正式上线前能够正确处理速率波动、令牌过期和各种错误情况。

***

> [!NOTE]
>
> **需要帮助吗？**
>
> 如果您遇到任何问题或需要集成方面的帮助，请联系我们的[支持团队](mailto:support@localpayment.com)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.