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

# 快速开始

> 按照本分步快速入门指南，在 15 分钟内设置 VelaFi 账户、生成 API key 并发送你的第一个已认证 API 请求。

本快速入门将引导你完成通过 VelaFi API 认证并成功发起请求所需的最少步骤。完成后，你将拥有一个可用的 API key、一个已验证的账户，以及来自 `/v2/user/account` 接口的实时响应。如果你想在正式上线前无风险地探索 API，最后一步会引导你使用沙盒环境。

**1. 创建 VelaFi 账户**

访问 [velafi.com/signup](https://www.velafi.com/signup) 并填写注册表单。按照屏幕上的提示验证你的邮箱地址并完成账户创建。

注册完成后，VelaFi 会为你分配一个唯一的**用户 ID (UID)**。该 UID 是与你账户关联的所有商户、API key 和交易的顶级标识符。请妥善保存 —— 你会在控制台和 API 响应中多处看到它。

> [!TIP]
>
> 注册后请立即登录 VelaFi 控制台，在进行商户设置之前先熟悉账户结构。

**2. 创建商户并完成 KYC/KYB**

VelaFi 要求每项支付操作都必须在经过验证的**商户**实体下执行。商户可以代表你自己的企业，也可以代表你正在接入的个人客户。

创建商户：

1. 在控制台中，打开 **Merchants** 部分并点击 **Create Merchant**。
2. 选择实体类型 —— **Individual**（个人）或 **Business**（企业）—— 并填写所需信息。
3. 上传 KYC（个人）或 KYB（企业）所需的合规文件。
4. 提交表单并等待 VelaFi 合规团队审核通过。

审核通过后，VelaFi 会分配一个**商户 ID (MID)**，并自动为该商户开通加密货币托管钱包，初始每月提现限额为 USD 10,000,000,000。

> [!NOTE]
>
> 有关商户创建和文件要求的完整说明，请参见[创建商户](https://docs.velafi.com/cn/docs/guides/creating-merchant.md)指南。

**3. 生成 API key**

账户激活后，你就可以通过 VelaFi 控制台创建 API key。

1. 登录并打开 [API Management](https://www.velafi.com/security/interface)。
2. 点击 **Create API Key**。
3. 如果你的账户尚未启用双重认证 (2FA)，系统会提示你先进行设置。请完成 2FA 设置 —— 这是生成密钥的必要条件。
4. 输入备注（1–30 个字符）以标识该密钥（例如 `production-backend`）。
5. 点击 **Continue** 并输入你的 2FA 验证码。确认窗口会显示你的 API key 和 API secret。

> [!WARNING]
>
> 在关闭确认窗口之前，请复制 API secret 并安全保存。VelaFi 不会再次显示该 secret；API key 会一直显示在你的密钥列表中。如果丢失了 secret，请删除该密钥并创建新的密钥。

接下来，在新密钥上选择 **Whitelist**，并添加将要调用 API 的服务器的公网 IP 地址。最多可添加 5 个 IPv4 或 IPv6 地址；不支持 CIDR 网段。未配置白名单的密钥无法获取 token（错误码 `-1023`）。

每个 API 请求都通过在 `X-BH-TOKEN` 请求头中发送 token 进行认证，该 token 使用此 key 和 secret 从 `GET /v2/token/generate` 获取：

```http theme={null}
X-BH-TOKEN: YOUR_TOKEN
```

**4. 激活 API 访问**

生成 API key 并不会自动为你的账户开通 API 访问。你必须联系 VelaFi 支持团队完成激活。

请发送邮件至 [contact@velafi.com](mailto:contact@velafi.com)，附上你的账户 UID 以及预期使用场景的简要说明。API 访问开通后，团队会通过邮件确认。

> [!NOTE]
>
> 在 API 访问开通之前，token 请求会以错误码 `-5033` 失败。

**5. 发起第一个 API 调用**

账户激活后，获取 token 并调用账户详情接口以验证你的设置。

```bash cURL theme={null}
API_KEY="YOUR_API_KEY"
API_SECRET="YOUR_API_SECRET"
TIMESTAMP=$(( $(date +%s) * 1000 ))
SIGNATURE=$(printf 'timestamp=%s' "$TIMESTAMP" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.*= //')

# 1. Get a token
curl --request GET \
  --url "https://api.velafi.com/v2/token/generate?timestamp=${TIMESTAMP}&signature=${SIGNATURE}" \
  --header "X-BH-APIKEY: ${API_KEY}"

# 2. Call the API with the token from data.token
curl --request GET \
  --url https://api.velafi.com/v2/user/account \
  --header "X-BH-TOKEN: YOUR_TOKEN"
```

```python Python theme={null}
import hashlib
import hmac
import time

import requests

BASE_URL = "https://api.velafi.com"
API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"

# 1. Get a token
timestamp = str(int(time.time() * 1000))
signature = hmac.new(
    API_SECRET.encode("utf-8"),
    f"timestamp={timestamp}".encode("utf-8"),
    hashlib.sha256,
).hexdigest()
token_body = requests.get(
    f"{BASE_URL}/v2/token/generate",
    params={"timestamp": timestamp, "signature": signature},
    headers={"X-BH-APIKEY": API_KEY},
).json()
if token_body["code"] != 200:
    raise RuntimeError(f"Token request failed: {token_body}")

# 2. Call the API with the token
response = requests.get(
    f"{BASE_URL}/v2/user/account",
    headers={"X-BH-TOKEN": token_body["data"]["token"]},
)
print(response.json())
```

```javascript Node.js theme={null}
const crypto = require("crypto");

const BASE_URL = "https://api.velafi.com";
const API_KEY = "YOUR_API_KEY";
const API_SECRET = "YOUR_API_SECRET";

async function main() {
  // 1. Get a token
  const timestamp = Date.now().toString();
  const signature = crypto
    .createHmac("sha256", API_SECRET)
    .update(`timestamp=${timestamp}`)
    .digest("hex");
  const tokenResponse = await fetch(
    `${BASE_URL}/v2/token/generate?timestamp=${timestamp}&signature=${signature}`,
    { headers: { "X-BH-APIKEY": API_KEY } }
  );
  const tokenBody = await tokenResponse.json();
  if (tokenBody.code !== 200) {
    throw new Error(`Token request failed: ${JSON.stringify(tokenBody)}`);
  }

  // 2. Call the API with the token
  const response = await fetch(`${BASE_URL}/v2/user/account`, {
    headers: { "X-BH-TOKEN": tokenBody.data.token },
  });
  console.log(await response.json());
}

main();
```

成功的响应会返回 `"code": 200` 和 `"msg": "SUCCESS"`，账户详情位于 `data` 中。字段说明请参见[获取账户详情](https://docs.velafi.com/cn/api-reference/account/get-account-details.md)。

如果调用失败，请检查响应体中的负数 `code`：

* token 请求返回 `-5033`：你的账户尚未开通 API 访问。请联系 VelaFi。
* token 请求返回 `-1023`：该 API key 未配置 IP 白名单。
* token 请求返回 `-2015`：请求来自不在该密钥白名单中的 IP 地址，或密钥或你的账户已被禁用。
* `-1022`：签名错误或 API key 不存在（token 请求），或 token 无效或已过期（API 调用）。
* API 调用返回 `-2019`：请求来自不在该密钥白名单中的 IP 地址。

完整的认证错误列表请参见[认证](https://docs.velafi.com/cn/api-reference/authentication.md)。

**6. 试用沙盒环境**

在构建生产工作流之前，请使用 VelaFi 沙盒环境基于模拟数据测试你的集成，不会对真实资金造成任何风险。沙盒环境与生产 API 一致，但使用不同的 base URL，并需要由 VelaFi 团队提供的独立凭证。

* **沙盒环境 base URL：** `https://api-test.velafi.com`
* **凭证：** 联系 [contact@velafi.com](mailto:contact@velafi.com) 申请沙盒环境凭证 —— 无需完成 KYC 或创建 API key。

有关沙盒环境与生产环境行为的完整对比及请求示例，请参见[沙盒环境](https://docs.velafi.com/cn/docs/sandbox.md)页面。

***

## 后续步骤

> [card] [沙盒环境](https://docs.velafi.com/cn/docs/sandbox.md)
>
> 在接触生产环境之前，先基于模拟数据进行测试。

> [card] [入金：法币 → 加密货币](https://docs.velafi.com/cn/docs/guides/on-ramp.md)
>
> 端到端构建你的第一个法币兑加密货币订单流程。

> [card] [出金：加密货币 → 法币](https://docs.velafi.com/cn/docs/guides/off-ramp.md)
>
> 兑换加密货币余额并将法币发送到收款人账户。

> [card] [API 参考](https://docs.velafi.com/cn/api-reference/overview.md)
>
> 浏览包含参数和响应结构的完整接口目录。


## Related topics

- [VelaFi API 文档](https://docs.velafi.com/cn/index.md)
- [认证](https://docs.velafi.com/cn/api-reference/authentication.md)
- [沙盒环境](https://docs.velafi.com/cn/docs/sandbox.md)
- [简介](https://docs.velafi.com/cn/docs/introduction.md)
- [创建商户](https://docs.velafi.com/cn/api-reference/merchant/create-merchant.md)


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