> ## 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/crypto-quote` 端点获取加密货币与法币之间的实时兑换汇率。`price` 始终以每 1 单位加密货币对应的法币数量表示。使用 `from` 和 `to` 选择方向：当 `from` 是给定 `country` 的法币时，返回用于入金（`fiat_to_crypto`）订单的买入汇率；否则 `from` 被视为加密货币，返回用于出金（`crypto_to_fiat`）订单的卖出汇率。当您设置 `createQuoteId=true` 时，API 还会返回一个 `quoteId`，您可以将其附加到订单中以锁定该价格。默认情况下，此端点的限制为每个账户每分钟 500 次请求。

> [!WARNING]
>
> 默认情况下，`quoteId` 在生产环境中有效期为 **10 秒**，在沙盒环境中为 **300 秒**，且仅可使用一次。它与您的账户以及签发时的 `country`、加密货币和法币绑定；如果订单将其用于不同的组合，或在过期后使用，将被拒绝。即使创建订单的请求随后被拒绝，该请求也可能已消耗掉 `quoteId`。

## 请求

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

### 请求头

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

### 查询参数

**country** `string` *required*

请求报价的国家名称（例如 `"Mexico"`）。

**from** `string` *required*

源货币符号。加密货币兑法币报价使用加密货币代码（例如 `"USDT"`），法币兑加密货币报价使用法币代码（例如 `"MXN"`）。

**to** `string` *required*

目标货币符号。加密货币兑法币报价使用法币代码（例如 `"MXN"`），法币兑加密货币报价使用加密货币代码（例如 `"USDT"`）。

**createQuoteId** `boolean`

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

## 响应字段

**code** `number`

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

**msg** `string`

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

**data** `object`

包含报价汇率及可选报价锁定信息的对象。

**data**

**price** `string`

以每 1 单位加密货币对应的法币数量表示的汇率（例如每 USDT 为 `"21.3707"` MXN），无论 `from` 和 `to` 如何设置。当 `from` 为法币时，这是买入汇率；当 `from` 为加密货币时，这是卖出汇率。如果没有 `quoteId`，该汇率仅供参考，订单将在创建时定价。

**quoteId** `string`

锁定汇率的唯一标识符（例如 `"e46836d68a4a4a6f8f2f609352cffb2f"`）。仅在 `createQuoteId=true` 时返回。在生产环境中有效期为 10 秒，在沙盒环境中为 300 秒；默认仅可使用一次。

## 示例

> [tab] 加密货币 → 法币（仅价格）
>
> 获取 USDT 兑墨西哥比索的当前汇率，不锁定价格。
>
> ```bash cURL theme={null}
> curl --request GET \
>   --url 'https://api.velafi.com/v2/user/crypto-quote?country=Mexico&from=USDT&to=MXN' \
>   --header 'X-BH-TOKEN: YOUR_TOKEN'
> ```
>
> ```json Response theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "price": "21.3707"
>   }
> }
> ```

> [tab] 法币 → 加密货币（含 quoteId）
>
> 获取以墨西哥比索支付购买 USDT 的买入汇率，并通过 `quoteId` 锁定。价格仍以每 USDT 对应的 MXN 表示。
>
> ```bash cURL theme={null}
> curl --request GET \
>   --url 'https://api.velafi.com/v2/user/crypto-quote?country=Mexico&from=MXN&to=USDT&createQuoteId=true' \
>   --header 'X-BH-TOKEN: YOUR_TOKEN'
> ```
>
> ```json Response theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "price": "21.4104",
>     "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f"
>   }
> }
> ```

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

> [!TIP]
>
> 为尽可能在 `quoteId` 过期前使用它，请在提交订单前立即请求报价，而不是在用户输入过程中请求。


## Related topics

- [获取加密货币→法币交易对](https://docs.velafi.com/cn/api-reference/basic-configuration/get-crypto-fiat-pairs.md)
- [获取加密货币→法币支付方式](https://docs.velafi.com/cn/api-reference/basic-configuration/get-crypto-fiat-payment-methods.md)
- [获取法币→加密货币交易对](https://docs.velafi.com/cn/api-reference/basic-configuration/get-fiat-crypto-pairs.md)
- [获取加密货币列表](https://docs.velafi.com/cn/api-reference/basic-configuration/get-list-of-crypto-currencies.md)
- [获取加密货币提现记录](https://docs.velafi.com/cn/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)


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