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
Este inicio rápido usa el ambiente Sandbox para pruebas. No se transferirá dinero real.
Requisitos Previos
Antes de comenzar, asegúrate de tener:
Regístrate en KillB y obtén:
- Email y contraseña para autenticación
Puedes obtenerlos de tu Dashboard KillB.
- Una terminal o interfaz de línea de comandos
- cURL, Postman, o tu cliente API preferido
- Conocimiento básico de APIs REST y JSON
Paso 1: Autenticación
Primero, obtén un token de acceso iniciando sesión con tus credenciales:
curl --request POST \
--url https://teste-94u93qnn.uc.gateway.dev/api/v2/auth/login \
--header 'Content-Type: application/json' \
--data '{
"email": "[email protected]",
"password": "tu-contraseña"
}'
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600000,
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Guarda el accessToken - lo necesitarás para todas las solicitudes subsiguientes. El token expira después de 1 hora (3600000 ms).
Paso 2: Crear un Usuario
Crea un perfil de usuario con información KYC:
curl --request POST \
--url https://teste-94u93qnn.uc.gateway.dev/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": "[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": "usuario-12345",
"complianceUrl": "https://kyc.example.com",
...
}
El usuario se crea con nivel de acceso L1 que permite transacciones básicas. Niveles más altos (L2-L4) requieren documentación adicional.
Paso 3: Crear una Cuenta de Billetera
Agrega una billetera de destino donde se enviará la cripto:
curl --request POST \
--url https://teste-94u93qnn.uc.gateway.dev/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": "[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": "billetera-12345",
...
}
Paso 4: Obtener una Cotización
Solicita una cotización de precio para tu conversión:
curl --request POST \
--url https://teste-94u93qnn.uc.gateway.dev/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"
}'
{
"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"
}
Las cotizaciones expiran después de 30 segundos. Debes crear el ramp antes de la expiración.
Paso 5: Crear un Ramp
Ejecuta la transacción usando la cotización:
curl --request POST \
--url https://teste-94u93qnn.uc.gateway.dev/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"
}'
{
"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"
}],
...
}
¡Éxito! Tu primer ramp está creado. El usuario ahora puede pagar via la URL de pago PSE.
Paso 6: Probar Pago (Solo Sandbox)
En modo sandbox, simula la finalización del pago:
curl --request POST \
--url https://teste-94u93qnn.uc.gateway.dev/api/v2/faker/cash-in \
--header 'Authorization: Bearer TU_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"rampId": "ramp-1a2b3c4d-5e6f-7g8h-9i0j"
}'
Paso 7: Verificar Estado del Ramp
Monitorea el estado del ramp:
curl --request GET \
--url https://teste-94u93qnn.uc.gateway.dev/api/v2/ramps/ramp-1a2b3c4d-5e6f-7g8h-9i0j \
--header 'Authorization: Bearer TU_ACCESS_TOKEN'
CREATED → CASH_IN_PROCESSING → CASH_IN_COMPLETED → CONVERSION_PROCESSING → CONVERSION_COMPLETED → CASH_OUT_PROCESSING → COMPLETED
Próximos Pasos
Problemas Comunes
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.
Las cotizaciones expiran después de 30 segundos. Crea una nueva cotización si el tiempo ha pasado.
Asegúrate de estar usando el userId correcto de la respuesta de creación de usuario.
