> ## 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.

# API 概览

> 了解 VelaFi REST API：基础 URL、JSON 请求格式、标准响应结构、速率限制以及主要资源章节的链接。

VelaFi REST API 让你能够以编程方式管理法币到加密货币的入金 (On-Ramp)、加密货币到法币的出金 (Off-Ramp)，以及基于稳定币通道的法币到法币全球支付。该 API 遵循 RESTful 规范——每个资源都可以通过 URL 访问，每次交互都使用标准 HTTP 方法，每个响应体都是 JSON。所有通信均通过 HTTPS 进行，并使用标准 HTTP 状态码表示每个请求的结果。

## 基础 URL

请根据你的集成阶段选择相应的环境。开发和测试时请使用沙盒环境，以免转移真实资金。只有在准备正式上线时才切换到生产环境 URL。

| 环境 | 基础 URL |
| - | - |
| 生产环境 | `https://api.velafi.com` |
| 沙盒环境 | `https://api-test.velafi.com` |

> [!NOTE]
>
> 沙盒环境和生产环境的凭证**不能**互换使用。请使用为你所调用环境签发的 API key、API secret 和令牌。

## 请求格式

所有请求体均以 JSON 格式发送，并相应设置 `Content-Type` 请求头：

```http theme={null}
Content-Type: application/json
```

每个访问受保护资源的请求还必须在 `X-BH-TOKEN` 请求头中包含业务令牌。使用你的 API key 和 API secret 对请求签名，通过 `GET /v2/token/generate` 获取令牌。详情请参见[认证](https://docs.velafi.com/cn/api-reference/authentication.md)页面。

**请求示例**

```bash theme={null}
curl --request GET \
  --url https://api.velafi.com/v2/user/account \
  --header "X-BH-TOKEN: your_token"
```

## 响应结构

成功的响应会包装在以下 JSON 结构中。错误响应包含 `code` 和 `msg`，但不包含 `data`；参见[错误码](https://docs.velafi.com/cn/docs/error-codes.md)。

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": { ... }
}
```

**code** `number`

成功时为 `200`（少数接口返回 `0`）。出错时，`code` 为错误码（除 `30012` 外均为负数）。它与 HTTP 状态码并不对应：携带错误 `code` 的响应使用 HTTP `400` 或 `500`。参见[错误码](https://docs.velafi.com/cn/docs/error-codes.md)。

**msg** `string`

概括结果的简短可读信息，例如 `"SUCCESS"` 或错误描述。

**data** `object | array | null`

接口返回的数据。其结构因接口而异，并在各个参考页面中分别说明。

## HTTP 状态码

下表列出了 API 返回的 HTTP 状态码。

| 代码 | 含义 |
| - | - |
| `200 OK` | 请求成功。 |
| `400 Bad Request` | 任何认证、校验、速率限制或业务错误。响应体包含错误 `code` 和 `msg`，对于大多数错误，该代码还会在 `error_code` 响应头中重复返回。 |
| `404 Not Found` | 路径不存在。 |
| `405 Method Not Allowed` | 该路径不接受此 HTTP 方法。 |
| `500 Internal Server Error` | 发生了意外错误。响应体包含代码 `-1001`。 |

> [!WARNING]
>
> 缺少令牌、令牌无效或已过期时，返回 `400` 及代码 `-1002` 或 `-1022`，而不是 `401`。超出速率限制时返回 `400` 及代码 `-1006`，而不是 `429`。请始终根据 `code` 字段进行分支处理。有关所有错误码以及哪些错误码表示结果未知，请参见[错误码](https://docs.velafi.com/cn/docs/error-codes.md)。

## 速率限制

以下接口设有默认速率限制，按 VelaFi 账户计数，且每个接口单独计算。一分钟的时间窗口从你的第一个请求开始，一分钟后重置。

| 接口 | 默认限制 |
| - | - |
| `GET /v2/user/crypto-quote` | 每分钟 500 次请求 |
| `GET /v2/user/fiat-quote` | 每分钟 500 次请求 |
| `POST /v2/order/fiat_to_crypto` | 每分钟 500 次请求 |
| `POST /v2/order/crypto_to_fiat` | 每分钟 500 次请求 |
| `POST /v2/order/fiat_to_fiat` | 每分钟 500 次请求 |
| `GET /v2/merchant/check/alias` | 每分钟 100 次请求 |
| `GET /v2/merchant/check/cvu` | 每分钟 100 次请求 |

> [!NOTE]
>
> 超出限制的请求会被拒绝，并返回 HTTP `400` 及代码 `-1006`（`Execution status unknown.`），而不是 `429`。此外，任何接口在收到过多并发请求时都可能返回代码 `30012`（HTTP `400`）。请在重试前进行退避。对于创建订单的调用，请遵循[错误码](https://docs.velafi.com/cn/docs/error-codes.md)中“结果未知：重试前先检查”一节的说明，因为 `-1006` 也用于其他失败情况。

其他接口可能有各自的限制。如果你的业务场景需要更高的吞吐量额度，请联系 [VelaFi 支持团队](mailto:support@velafi.com)。

## 主要章节

使用下方卡片直接跳转到你需要的资源分组。

> [card] [商户](https://docs.velafi.com/cn/api-reference/merchant/create-merchant.md)
>
> 配置商户资料、获取商户详情并管理商户级设置。

> [card] [订单](https://docs.velafi.com/cn/api-reference/order/create-a-fiat-to-crypto-order.md)
>
> 创建、查询和管理入金、出金以及法币到法币支付订单。

> [card] [收款人](https://docs.velafi.com/cn/api-reference/beneficiary/get-payment-templates.md)
>
> 添加和管理接收付款的银行账户和加密货币钱包。

> [card] [Webhook](https://docs.velafi.com/cn/api-reference/webhooks/webhook-setup.md)
>
> 订阅订单状态变更等事件的实时通知。


## Related topics

- [认证](https://docs.velafi.com/cn/api-reference/authentication.md)
- [生成令牌](https://docs.velafi.com/cn/api-reference/generate-token.md)
- [简介](https://docs.velafi.com/cn/docs/introduction.md)


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