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

# Guía de Inicio Rápido

> Comienza con la API de KillB en menos de 10 minutos

## Descripción General

Esta guía te llevará paso a paso para crear tu primera transacción de on-ramp cripto usando la API de KillB. Aprenderás cómo:

* Configurar la autenticación
* Crear un usuario
* Crear una cuenta de billetera cripto
* Obtener una cotización
* Ejecutar una transacción ramp

<Note>
  Este inicio rápido usa el **ambiente Sandbox** para pruebas. No se transferirá dinero real.
</Note>

## Requisitos Previos

Antes de comenzar, asegúrate de tener:

<AccordionGroup>
  <Accordion title="Credenciales API" icon="key">
    Regístrate en KillB y obtén:

    * Email y contraseña para autenticación

    Puedes obtenerlos de tu [Dashboard KillB](https://otc.killb.com).
  </Accordion>

  <Accordion title="Entorno de Desarrollo" icon="laptop-code">
    * Una terminal o interfaz de línea de comandos
    * cURL, Postman, o tu cliente API preferido
    * Conocimiento básico de APIs REST y JSON
  </Accordion>
</AccordionGroup>

## Paso 1: Autenticación

Primero, obtén un token de acceso iniciando sesión con tus credenciales:

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

**Respuesta:**

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

<Tip>
  Guarda el `accessToken` - lo necesitarás para todas las solicitudes subsiguientes. El token expira después de 1 hora (3600000 ms).
</Tip>

## Paso 2: Crear un Usuario

Crea un perfil de usuario con información KYC:

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/api/v2/users \
  --header 'Authorization: Bearer TU_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "PERSON",
    "externalId": "usuario-12345",
    "data": {
      "firstName": "Juan",
      "lastName": "García",
      "email": "juan.garcia@ejemplo.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"
      }
    }
  }'
```

**Respuesta:**

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

<Info>
  El usuario se crea con nivel de acceso **L1** que permite transacciones básicas. Niveles más altos (L2-L4) requieren documentación adicional.
</Info>

## Paso 3: Crear una Cuenta de Billetera

Agrega una billetera de destino donde se enviará la cripto:

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/api/v2/accounts \
  --header 'Authorization: Bearer TU_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "WALLET",
    "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
    "externalId": "billetera-12345",
    "data": {
      "firstName": "Juan",
      "lastName": "García",
      "email": "juan.garcia@ejemplo.com",
      "phone": "+573001234567",
      "currency": "USDC",
      "network": "POLYGON",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "countryCode": "CO",
      "document": {
        "type": "PASSPORT",
        "number": "AB123456",
        "issuedCountryCode": "CO"
      }
    }
  }'
```

**Respuesta:**

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

## Paso 4: Obtener una Cotización

Solicita una cotización de precio para tu conversión:

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/api/v2/quotations \
  --header 'Authorization: Bearer TU_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "fromCurrency": "COP",
    "toCurrency": "USDC",
    "amount": 100000,
    "amountIsToCurrency": false,
    "cashInMethod": "PSE",
    "cashOutMethod": "POLYGON"
  }'
```

**Respuesta:**

```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>
  Las cotizaciones expiran después de 30 segundos. Debes crear el ramp antes de la expiración.
</Warning>

## Paso 5: Crear un Ramp

Ejecuta la transacción usando la cotización:

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

**Respuesta:**

```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>
  **¡Éxito!** Tu primer ramp está creado. El usuario ahora puede pagar via la URL de pago PSE.
</Check>

## Paso 6: Probar Pago (Solo Sandbox)

En modo sandbox, simula la finalización del pago:

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/api/v2/faker/cash-in \
  --header 'Authorization: Bearer TU_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "rampId": "ramp-1a2b3c4d-5e6f-7g8h-9i0j"
  }'
```

Esto simulará que el usuario completa el pago y activará el proceso de conversión.

## Paso 7: Verificar Estado del Ramp

Monitorea el estado del ramp:

```bash theme={null}
curl --request GET \
  --url https://sandbox.killb.app/api/v2/ramps/ramp-1a2b3c4d-5e6f-7g8h-9i0j \
  --header 'Authorization: Bearer TU_ACCESS_TOKEN'
```

**Flujo de Estados:**

* `CREATED` → `CASH_IN_PROCESSING` → `CASH_IN_COMPLETED` → `CONVERSION_PROCESSING` → `CONVERSION_COMPLETED` → `CASH_OUT_PROCESSING` → `COMPLETED`

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Configurar Webhooks" icon="bell" href="/es/guides/webhooks/setup">
    Recibe notificaciones en tiempo real de actualizaciones de transacciones
  </Card>

  <Card title="Implementar Off-Ramps" icon="arrow-down" href="/es/guides/ramps/off-ramp">
    Aprende cómo convertir cripto de vuelta a fiat
  </Card>

  <Card title="Gestionar Usuarios" icon="users" href="/es/guides/users/manage-users">
    Maneja niveles KYC y verificación de usuarios
  </Card>

  <Card title="Manejo de Errores" icon="triangle-exclamation" href="/es/resources/error-handling">
    Aprende mejores prácticas para manejar errores de API
  </Card>
</CardGroup>

## Problemas Comunes

<AccordionGroup>
  <Accordion title="401 No Autorizado">
    Tu token de acceso puede haber expirado. Llama al endpoint `/api/v2/auth/refresh` con tu refresh token para obtener un nuevo token de acceso.
  </Accordion>

  <Accordion title="Cotización Expirada">
    Las cotizaciones expiran después de 30 segundos. Crea una nueva cotización si el tiempo ha pasado.
  </Accordion>

  <Accordion title="Usuario No Encontrado">
    Asegúrate de estar usando el `userId` correcto de la respuesta de creación de usuario.
  </Accordion>
</AccordionGroup>

<Info>
  **¿Necesitas Ayuda?** Contacta soporte en [tech@killb.com](mailto:tech@killb.com)
</Info>