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
Set Up Webhooks
Get real-time notifications for transaction updates
Implement Off-Ramps
Learn how to convert crypto back to fiat
Manage Users
Handle KYC levels and user verification
Error Handling
Learn best practices for handling API errors
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.
