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

创建 VelaFi 账户

访问 velafi.com/signup 并填写注册表单。按照屏幕上的提示验证你的邮箱地址并完成账户创建。注册完成后,VelaFi 会为你分配一个唯一的用户 ID (UID)。该 UID 是与你账户关联的所有商户、API key 和交易的顶级标识符。请妥善保存 —— 你会在控制台和 API 响应中多处看到它。
注册后请立即登录 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。
有关商户创建和文件要求的完整说明,请参见创建商户指南。
3

生成 API key

账户激活后,你就可以通过 VelaFi 控制台创建 API key。
  1. 登录并打开 API Management。
  2. 点击 Create API Key。
  3. 如果你的账户尚未启用双重认证 (2FA),系统会提示你先进行设置。请完成 2FA 设置 —— 这是生成密钥的必要条件。
  4. 输入备注(1–30 个字符)以标识该密钥(例如 production-backend)。
  5. 点击 Continue 并输入你的 2FA 验证码。确认窗口会显示你的 API key 和 API secret。
在关闭确认窗口之前,请复制 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 获取:
4

激活 API 访问

生成 API key 并不会自动为你的账户开通 API 访问。你必须联系 VelaFi 支持团队完成激活。请发送邮件至 contact@velafi.com,附上你的账户 UID 以及预期使用场景的简要说明。API 访问开通后,团队会通过邮件确认。
在 API 访问开通之前,token 请求会以错误码 -5033 失败。
5

发起第一个 API 调用

账户激活后,获取 token 并调用账户详情接口以验证你的设置。
成功的响应会返回 "code": 200 和 "msg": "SUCCESS",账户详情位于 data 中。字段说明请参见获取账户详情。如果调用失败,请检查响应体中的负数 code:
  • token 请求返回 -5033:你的账户尚未开通 API 访问。请联系 VelaFi。
  • token 请求返回 -1023:该 API key 未配置 IP 白名单。
  • token 请求返回 -2015:请求来自不在该密钥白名单中的 IP 地址,或密钥或你的账户已被禁用。
  • -1022:签名错误或 API key 不存在(token 请求),或 token 无效或已过期(API 调用)。
  • API 调用返回 -2019:请求来自不在该密钥白名单中的 IP 地址。
完整的认证错误列表请参见认证。
6

试用沙盒环境

在构建生产工作流之前,请使用 VelaFi 沙盒环境基于模拟数据测试你的集成,不会对真实资金造成任何风险。沙盒环境与生产 API 一致,但使用不同的 base URL,并需要由 VelaFi 团队提供的独立凭证。
  • 沙盒环境 base URL: https://api-test.velafi.com
  • 凭证: 联系 contact@velafi.com 申请沙盒环境凭证 —— 无需完成 KYC 或创建 API key。
有关沙盒环境与生产环境行为的完整对比及请求示例,请参见沙盒环境页面。

后续步骤

沙盒环境

在接触生产环境之前,先基于模拟数据进行测试。

入金:法币 → 加密货币

端到端构建你的第一个法币兑加密货币订单流程。

出金:加密货币 → 法币

兑换加密货币余额并将法币发送到收款人账户。

API 参考

浏览包含参数和响应结构的完整接口目录。