> ## Documentation Index
> Fetch the complete documentation index at: https://docs.killb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始指南

> 在 10 分钟内开始使用 KillB API

## 概述

本指南将引导您使用 KillB API 创建第一个加密货币 on-ramp 交易。您将学习如何：

* 设置身份验证
* 创建用户
* 创建加密货币钱包账户
* 获取报价
* 执行 ramp 交易

<Note>
  此快速开始使用**沙盒环境**进行测试。不会转移真实资金。
</Note>

## 先决条件

在开始之前，请确保您拥有：

<AccordionGroup>
  <Accordion title="API 凭证" icon="key">
    注册 KillB 账户并获取您的：

    * 用于身份验证的电子邮件和密码

    您可以从 [KillB 门户](https://otc.killb.com) 获取这些信息。
  </Accordion>

  <Accordion title="开发环境" icon="laptop-code">
    * 终端或命令行界面
    * cURL、Postman 或您首选的 API 客户端
    * REST API 和 JSON 的基础知识
  </Accordion>
</AccordionGroup>

## 步骤 1：身份验证

首先，通过使用您的凭证登录来获取访问令牌：

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/api/v2/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'
```

**响应：**

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600000,
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

<Tip>
  保存 `accessToken` - 您将在所有后续请求中需要它。令牌在 1 小时后（3600000 毫秒）过期。
</Tip>

## 步骤 2：创建用户

创建带有 KYC 信息的用户配置文件：

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/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": "john.doe@example.com",
      "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"
      }
    }
  }'
```

**响应：**

```json theme={null}
{
  "id": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "status": "ACTIVE",
  "type": "PERSON",
  "accessLevel": "L1",
  "externalId": "user-12345",
  "complianceUrl": "https://kyc.example.com",
  ...
}
```

<Info>
  用户以访问级别 **L1** 创建，允许基本交易。更高级别（L2-L4）需要额外的文档。
</Info>

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

添加将发送加密货币的目标钱包：

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/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": "john.doe@example.com",
      "phone": "+573001234567",
      "currency": "USDC",
      "network": "POLYGON",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "countryCode": "CO",
      "document": {
        "type": "PASSPORT",
        "number": "AB123456",
        "issuedCountryCode": "CO"
      }
    }
  }'
```

**响应：**

```json theme={null}
{
  "id": "7c8b9a3d-2f1e-4b5c-9d8e-1a2b3c4d5e6f",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "type": "WALLET",
  "status": "ACTIVE",
  "externalId": "wallet-12345",
  ...
}
```

## 步骤 4：获取报价

请求转换的价格报价：

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/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"
  }'
```

**响应：**

```json theme={null}
{
  "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"
}
```

<Warning>
  报价在 30 秒后过期。您必须在过期前创建 ramp。
</Warning>

## 步骤 5：创建 Ramp

使用报价执行交易：

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/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"
  }'
```

**响应：**

```json theme={null}
{
  "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"
  }],
  ...
}
```

<Check>
  **成功！** 您的第一个 ramp 已创建。用户现在可以通过 PSE 支付 URL 进行支付。
</Check>

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

在沙盒模式下，模拟支付完成：

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/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 状态：

```bash theme={null}
curl --request GET \
  --url https://sandbox.killb.app/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`

## 下一步

<CardGroup cols={2}>
  <Card title="设置 Webhooks" icon="bell" href="/zh/guides/webhooks/setup">
    获取交易更新的实时通知
  </Card>

  <Card title="实现 Off-Ramps" icon="arrow-down" href="/zh/guides/ramps/off-ramp">
    了解如何将加密货币转换回法币
  </Card>

  <Card title="管理用户" icon="users" href="/zh/guides/users/manage-users">
    处理 KYC 级别和用户验证
  </Card>

  <Card title="错误处理" icon="triangle-exclamation" href="/zh/resources/error-handling">
    了解处理 API 错误的最佳实践
  </Card>
</CardGroup>

## 常见问题

<AccordionGroup>
  <Accordion title="401 未授权">
    您的访问令牌可能已过期。使用您的刷新令牌调用 `/api/v2/auth/refresh` 端点以获取新的访问令牌。
  </Accordion>

  <Accordion title="报价已过期">
    报价在 30 秒后过期。如果时间已过，请创建新报价。
  </Accordion>

  <Accordion title="用户未找到">
    确保您使用的是用户创建响应中的正确 `userId`。
  </Accordion>
</AccordionGroup>

<Info>
  **需要帮助？** 通过 [tech@killb.com](mailto:tech@killb.com) 联系支持
</Info>