Connect your own scripts and apps to your KLS account
Getting Started
Every KLS user can generate a personal API Key and API Secret from
Settings → API Access. These two values authenticate every request
you make to the API — treat them like a password. Your secret is shown once at generation time and never again,
so save it somewhere safe immediately.
All endpoints are scoped to your own account only — you can check your own balance, list available items, view your
own purchase history, and buy items on your own behalf. You cannot access any other user's data.
import requests
res = requests.get(
"https://your-site.example.com/api/v1/listings",
params={"type": "tool"},
headers={
"X-API-Key": "your_api_key",
"X-API-Secret": "your_api_secret"
}
)
for tool in res.json():
print(tool["title"], tool["price"])
Example: Buy an item
💳 No platform fee — you're charged exactly the item's listed price via the API, same as buying it through the marketplace. The response includes itemPrice and totalCharged (always equal) so you can confirm this.
import requests
res = requests.post(
"https://your-site.example.com/api/v1/buy/LISTING_ID_HERE",
headers={
"X-API-Key": "your_api_key",
"X-API-Secret": "your_api_secret"
}
)
result = res.json()
print(result["message"], result["newBalance"])
Example: Buy a Number
📱 Numbers are used to receive a one-time verification code from the provider you choose (WhatsApp, Telegram, etc). Prices here are separate from the site's own Buy Numbers page — check /numbers/options for what's currently available and its price. Want to see this exact flow (browse → buy → poll → done) built into a full page? /buy-number on this site is that reference implementation — same four calls below, wired to a UI.
# 1. See what's available
curl https://your-site.example.com/api/v1/numbers/options \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_api_secret"
# 2. Rent a number
curl -X POST https://your-site.example.com/api/v1/buy-number \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_api_secret" \
-H "Content-Type: application/json" \
-d '{"provider":"WhatsApp","country":"United States"}'
# 3. Poll for the code (repeat every few seconds until status is "received")
curl "https://your-site.example.com/api/v1/get-sms?order_id=ORDER_ID_HERE" \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_api_secret"
# 4. If no code arrives, cancel for a refund
curl -X POST https://your-site.example.com/api/v1/cancel-number \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_api_secret" \
-H "Content-Type: application/json" \
-d '{"order_id":"ORDER_ID_HERE"}'
const headers = {
'X-API-Key': 'your_api_key',
'X-API-Secret': 'your_api_secret',
'Content-Type': 'application/json'
};
// 1. See what's available
const options = await (await fetch('https://your-site.example.com/api/v1/numbers/options', { headers })).json();
// 2. Rent a number
const order = await (await fetch('https://your-site.example.com/api/v1/buy-number', {
method: 'POST', headers, body: JSON.stringify({ provider: 'WhatsApp', country: 'United States' })
})).json();
// 3. Poll for the code
async function pollForCode(orderId) {
const r = await (await fetch(`https://your-site.example.com/api/v1/get-sms?order_id=${orderId}`, { headers })).json();
if (r.status === 'received') return r.sms;
await new Promise(res => setTimeout(res, 5000));
return pollForCode(orderId);
}
const code = await pollForCode(order.order_id);
import requests, time
headers = {"X-API-Key": "your_api_key", "X-API-Secret": "your_api_secret"}
# 1. See what's available
options = requests.get("https://your-site.example.com/api/v1/numbers/options", headers=headers).json()
# 2. Rent a number
order = requests.post(
"https://your-site.example.com/api/v1/buy-number",
headers=headers, json={"provider": "WhatsApp", "country": "United States"}
).json()
# 3. Poll for the code
while True:
r = requests.get(
"https://your-site.example.com/api/v1/get-sms",
headers=headers, params={"order_id": order["order_id"]}
).json()
if r["status"] == "received":
print(r["sms"])
break
time.sleep(5)
Errors
Status
Meaning
What to do
401
Missing or invalid API key/secret
Double-check the X-API-Key/X-API-Secret headers are set and match exactly what's shown in Settings → API Access. Regenerating your key there invalidates the old one immediately.
403
Account restricted
Your account has been limited — contact support, this isn't something a retry fixes.
404
Listing not found or no longer available
Re-fetch /listings or /numbers/options — the item may have sold out or been removed since you last checked.
400
Insufficient balance, sold out, or invalid request
Check the response body's error field for the specific reason — it's always a plain-English message, not just the code.
402
Insufficient balance (numbers endpoints)
Deposit funds before retrying — no partial/temporary state is created, so it's safe to just retry once the balance is topped up.
409
No numbers currently available for that provider/country
This is temporary stock, not a config issue — wait a few seconds and retry, or check /numbers/options again in case that provider/country is no longer listed at all.
📱 Numbers specifically: your money is only ever taken if a real number was actually issued — a failed /buy-number call never touches your balance, so it's always safe to just retry. Once you do have an order, it auto-refunds on its own if no code arrives in time — you don't have to call /cancel-number unless you want your balance back sooner than that.