跳转到主要内容

​
概述

本指南将引导您使用 KillB API 创建第一个加密货币 on-ramp 交易。您将学习如何：
  • 设置身份验证
  • 创建用户
  • 创建加密货币钱包账户
  • 获取报价
  • 执行 ramp 交易
此快速开始使用沙盒环境进行测试。不会转移真实资金。

​
先决条件

在开始之前，请确保您拥有：
注册 KillB 账户并获取您的：
  • 用于身份验证的电子邮件和密码
您可以从 KillB 门户 获取这些信息。
  • 终端或命令行界面
  • cURL、Postman 或您首选的 API 客户端
  • REST API 和 JSON 的基础知识

​
步骤 1：身份验证

首先，通过使用您的凭证登录来获取访问令牌： 
curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "password": "your-password"
  }'
响应： 
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600000,
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
保存 accessToken - 您将在所有后续请求中需要它。令牌在 1 小时后（3600000 毫秒）过期。

​
步骤 2：创建用户

创建带有 KYC 信息的用户配置文件： 
curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/users \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "PERSON",
    "externalId": "user-12345",
    "data": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+573001234567",
      "dateOfBirth": "1990-01-01",
      "address": {
        "street1": "Calle 123",
        "city": "Bogotá",
        "state": "Cundinamarca",
        "zipCode": "110111",
        "countryCode": "CO"
      },
      "document": {
        "type": "PASSPORT",
        "number": "AB123456",
        "issuedCountryCode": "CO"
      }
    }
  }'
响应： 
{
  "id": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "status": "ACTIVE",
  "type": "PERSON",
  "accessLevel": "L1",
  "externalId": "user-12345",
  "complianceUrl": "https://kyc.example.com",
  ...
}
用户以访问级别 L1 创建，允许基本交易。更高级别（L2-L4）需要额外的文档。

​
步骤 3：创建加密货币钱包账户

添加将发送加密货币的目标钱包： 
curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/accounts \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "WALLET",
    "externalId": "wallet-12345",
    "data": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+573001234567",
      "currency": "USDC",
      "network": "POLYGON",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "countryCode": "CO",
      "document": {
        "type": "PASSPORT",
        "number": "AB123456",
        "issuedCountryCode": "CO"
      }
    }
  }'
响应： 
{
  "id": "7c8b9a3d-2f1e-4b5c-9d8e-1a2b3c4d5e6f",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "type": "WALLET",
  "status": "ACTIVE",
  "externalId": "wallet-12345",
  ...
}

​
步骤 4：获取报价

请求转换的价格报价： 
curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/quotations \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "fromCurrency": "COP",
    "toCurrency": "USDC",
    "amount": 100000,
    "amountIsToCurrency": false,
    "cashInMethod": "PSE",
    "cashOutMethod": "POLYGON"
  }'
响应： 
{
  "id": "quot-9f8e7d6c-5b4a-3c2d-1e0f",
  "fromCurrency": "COP",
  "toCurrency": "USDC",
  "fromAmount": 100000,
  "toAmount": 23.81,
  "rate": 4200,
  "spotPrice": 4180,
  "expiresAt": 1704657600000,
  "cashInMethod": "PSE",
  "cashOutMethod": "POLYGON"
}
报价在 30 秒后过期。您必须在过期前创建 ramp。

​
步骤 5：创建 Ramp

使用报价执行交易： 
curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/ramps \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "quotationId": "quot-9f8e7d6c-5b4a-3c2d-1e0f",
    "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
    "accountId": "7c8b9a3d-2f1e-4b5c-9d8e-1a2b3c4d5e6f"
  }'
响应： 
{
  "id": "ramp-1a2b3c4d-5e6f-7g8h-9i0j",
  "status": "CREATED",
  "type": "ON",
  "fromCurrency": "COP",
  "toCurrency": "USDC",
  "fromAmount": 100000,
  "toAmount": 23.81,
  "paymentInfo": [{
    "url": "https://checkout.pse.com.co/payment/123456"
  }],
  ...
}
成功！ 您的第一个 ramp 已创建。用户现在可以通过 PSE 支付 URL 进行支付。

​
步骤 6：测试支付（仅沙盒）

在沙盒模式下，模拟支付完成： 
curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/faker/cash-in \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "rampId": "ramp-1a2b3c4d-5e6f-7g8h-9i0j"
  }'
这将模拟用户完成支付并触发转换过程。

​
步骤 7：检查 Ramp 状态

监控 ramp 状态： 
curl --request GET \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/ramps/ramp-1a2b3c4d-5e6f-7g8h-9i0j \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
状态流程：
  • CREATED → CASH_IN_PROCESSING → CASH_IN_COMPLETED → CONVERSION_PROCESSING → CONVERSION_COMPLETED → CASH_OUT_PROCESSING → COMPLETED

​
下一步

设置 Webhooks

获取交易更新的实时通知

实现 Off-Ramps

了解如何将加密货币转换回法币

管理用户

处理 KYC 级别和用户验证

错误处理

了解处理 API 错误的最佳实践

​
常见问题

您的访问令牌可能已过期。使用您的刷新令牌调用 /api/v2/auth/refresh 端点以获取新的访问令牌。
报价在 30 秒后过期。如果时间已过，请创建新报价。
确保您使用的是用户创建响应中的正确 userId。
需要帮助？ 加入我们的 Discord 社区 或通过 [email protected] 联系支持