Overview
This guide will walk you through creating your first crypto on-ramp transaction using the KillB API. You’ll learn how to:
- Set up authentication
- Create a user
- Create a crypto wallet account
- Get a quotation
- Execute a ramp transaction
This quickstart uses the Sandbox environment for testing. No real money will be transferred.
Prerequisites
Before you begin, make sure you have:
Sign up for a KillB account and obtain your:
- Email and password for authentication
You can get these from your KillB Portal.
- A terminal or command-line interface
- cURL, Postman, or your preferred API client
- Basic knowledge of REST APIs and JSON
Step 1: Authentication
First, obtain an access token by logging in with your credentials:
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..."
}
Save the accessToken - you’ll need it for all subsequent requests. The token expires after 1 hour (3600000 ms).
Step 2: Create a User
Create a user profile with KYC information:
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",
...
}
The user is created with access level L1 which allows basic transactions. Higher levels (L2-L4) require additional documentation.
Step 3: Create a Crypto Wallet Account
Add a destination wallet where the crypto will be sent:
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",
...
}
Step 4: Get a Quotation
Request a price quote for your conversion:
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"
}
Quotations expire after 30 seconds. You must create the ramp before expiration.
Step 5: Create a Ramp
Execute the transaction using the quotation:
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"
}],
...
}
Success! Your first ramp is created. The user can now pay via the PSE payment URL.
Step 6: Test Payment (Sandbox Only)
In sandbox mode, simulate the payment completion:
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"
}'
Step 7: Check Ramp Status
Monitor the ramp status:
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
Next Steps
Common Issues
Your access token may have expired. Call the /api/v2/auth/refresh endpoint with your refresh token to get a new access token.
Quotations expire after 30 seconds. Create a new quotation if the time has passed.
Make sure you’re using the correct userId from the user creation response.
