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

# 获取法币/法币报价

> 获取法币兑法币全球支付通道的实时汇率。可选择使用一次性 quoteId 锁定汇率。

使用 **GET** `/v2/user/fiat-quote` 接口获取通过 VelaFi 稳定币通道将一种法币兑换为另一种法币的实时汇率。请以查询参数的形式指定付款方和收款方的国家及币种。当您设置 `createQuoteId=true` 时，API 还会返回一个 `quoteId`，您可以将其附加到支付订单中以锁定该价格。此接口的调用频率限制为每个账户每分钟 500 次请求。

> [!WARNING]
>
> `quoteId` 在生产环境中有效期为 **20 秒**，在沙盒环境中为 **300 秒**。它与您的账户以及签发时对应的通道（入金国家和法币、出金国家和法币）绑定；针对其他通道的订单或在过期后提交的订单将被拒绝。`quoteId` 只能使用一次，即使创建订单的请求随后被拒绝，该 `quoteId` 也可能已被消耗。

## 请求

```text theme={null}
GET /v2/user/fiat-quote
```

### 请求头

| 请求头 | 值 | 必填 |
| - | - | - |
| `X-BH-TOKEN` | 通过 `GET /v2/token/generate` 获取的令牌 | ✓ |

### 查询参数

**onRampCountry** `string` *required*

付款方所在国家名称（例如 `"Mexico"`）。

**onRampFiat** `string` *required*

付款方（发送方）法币的 ISO 4217 代码（例如 `"MXN"`）。

**offRampCountry** `string` *required*

收款方所在国家名称（例如 `"Argentina"`）。

**offRampFiat** `string` *required*

收款方（接收方）法币的 ISO 4217 代码（例如 `"ARS"`）。

**createQuoteId** `boolean`

为 `true` 时，将预留所报汇率并返回 `quoteId`。创建支付订单时传入此 `quoteId` 即可锁定价格。默认为 `false`。

## 响应字段

**code** `number`

HTTP 风格的状态码。`200` 表示成功。

**msg** `string`

可读的状态信息，例如 `"SUCCESS"`。

**data** `object`

包含报价汇率及可选报价预留信息的对象。

**data**

**price** `string`

当前汇率，表示一单位 `onRampFiat` 可兑换多少单位 `offRampFiat`（例如 `"56.14266017"`）。除非请求了 `quoteId`，否则该汇率仅供参考，不保证最终成交价格。

**quoteId** `string`

预留汇率的唯一标识符（例如 `"e46836d68a4a4a6f8f2f609352cffb2f"`）。仅在 `createQuoteId=true` 时返回。在生产环境中有效期为 20 秒，在沙盒环境中为 300 秒；只能使用一次。

## 示例

> [tab] MXN → ARS（仅价格）
>
> 获取墨西哥比索兑阿根廷比索的当前汇率，不预留价格。
>
> ```bash cURL theme={null}
> curl --request GET \
>   --url 'https://api.velafi.com/v2/user/fiat-quote?onRampCountry=Mexico&onRampFiat=MXN&offRampCountry=Argentina&offRampFiat=ARS' \
>   --header 'X-BH-TOKEN: YOUR_TOKEN'
> ```
>
> ```json Response theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "price": "56.14266017"
>   }
> }
> ```

> [tab] ARS → MXN（带 quoteId）
>
> 获取阿根廷比索兑墨西哥比索的汇率，并通过 `quoteId` 预留该汇率。
>
> ```bash cURL theme={null}
> curl --request GET \
>   --url 'https://api.velafi.com/v2/user/fiat-quote?onRampCountry=Argentina&onRampFiat=ARS&offRampCountry=Mexico&offRampFiat=MXN&createQuoteId=true' \
>   --header 'X-BH-TOKEN: YOUR_TOKEN'
> ```
>
> ```json Response theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "price": "0.0160686",
>     "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f"
>   }
> }
> ```

> [!NOTE]
>
> `price` 字段是参考汇率。它反映当前市场汇率，但除非您持有有效的 `quoteId` 并在预留时间窗口内提交支付订单，否则不保证按该汇率成交。

> [!TIP]
>
> 请在提交支付订单之前立即请求新的报价，而不要缓存之前用户交互时获取的汇率。法币通道的汇率可能变动很快。


## Related topics

- [获取加密货币/法币报价](https://docs.velafi.com/cn/api-reference/quote/get-user-quote-for-crypto-fiat.md)
- [获取法币→法币交易对](https://docs.velafi.com/cn/api-reference/basic-configuration/get-fiat-fiat-pairs.md)
- [获取法币→加密货币交易对](https://docs.velafi.com/cn/api-reference/basic-configuration/get-fiat-crypto-pairs.md)
- [获取法币流水](https://docs.velafi.com/cn/api-reference/merchant/get-a-list-merchant-fiat-flow.md)
- [获取法币→法币支付方式](https://docs.velafi.com/cn/api-reference/basic-configuration/get-fiat-fiat-payment-methods.md)


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