Developer API Β· REST Β· Real-Time

Betloy Conversion API β€” Integrate Bet Code Conversion into Your Platform

A powerful, reliable API for businesses and developers to convert bet codes programmatically across 100+ bookmakers

# Convert a bet code from Bet9ja to Sportybet
curl -X POST https://test-dev.betloy.com/api/v1/convert \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "booking_code": "B3US96U",
    "from_bookie_id": 1,
    "to_bookie_id": 2
  }'
// Any HTTP client works; Node 18+ has fetch built in.
const res = await fetch('https://test-dev.betloy.com/api/v1/convert', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.BETLOY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    booking_code: 'B3US96U',
    from_bookie_id: 1,
    to_bookie_id: 2,
  }),
});

const { data } = await res.json();
console.log(data.status);          // β†’ "completed"
console.log(data.converted_code);  // β†’ "SP9KQM2"
# pip install requests
import os, requests

res = requests.post(
    'https://test-dev.betloy.com/api/v1/convert',
    headers={'X-API-Key': os.environ['BETLOY_API_KEY']},
    json={
        'booking_code': 'B3US96U',
        'from_bookie_id': 1,
        'to_bookie_id': 2,
    },
)

data = res.json()['data']
print(data['status'])          # β†’ "completed"
print(data['converted_code'])  # β†’ "SP9KQM2"
$ch = curl_init('https://test-dev.betloy.com/api/v1/convert');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'X-API-Key: ' . getenv('BETLOY_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'booking_code' => 'B3US96U',
    'from_bookie_id' => 1,
    'to_bookie_id' => 2,
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);

$data = json_decode(curl_exec($ch), true)['data'];
echo $data['converted_code'];  // β†’ "SP9KQM2"

Request body

{
  "booking_code": "B3US96U",
  "from_bookie_id": 1,
  "to_bookie_id": 2
}

Response (201 Created)

{
  "success": true,
  "data": {
    "id": 12345,
    "status": "completed",
    "booking_code": "B3US96U",
    "converted_code": "SP9KQM2",
    "error_message": null
  }
}

Reference

Endpoints

All endpoints are under https://test-dev.betloy.com/api/v1 and require an X-API-Key header. JSON in, JSON out. Read endpoints are free; chargeable calls only spend a credit when they succeed.

MethodEndpointPurposeCredits
GET/bookmakersList the live bookmaker catalogue. Use the returned id for conversions.Free
GET/bookmakers/{id}Get one bookmaker by its database id.Free
GET/toolsTool discovery: every tools endpoint with its credit cost.Free
GET/tools/bookmakersBookmakers the tools engine supports. Use the bookie_id from this list in every tools call.Free
POST/tools/decodeDecode a code into legs, markets, selections and odds (Bet Viewer).Free
POST/tools/rebuildApply leg edits and rebuild a code, optionally for another bookmaker (Bet Editor).1
POST/tools/trimDrop or soften legs until the slip fits the destination and stake (Bet Slip Saver).1
POST/tools/scanScan one code across destination bookmakers and rank the payouts (Odds Scanner).1
GET/tools/scan/{scan_id}Poll an asynchronous scan until it reports done.Free
POST/tools/leg-optionsList alternative markets and lines for one leg before editing it.Free
POST/convertConvert a booking code and return the new code, status and error message.1
GET/convert/{id}Get the status and result of one of your conversions.Free
GET/conversionsPaginated conversion history for your business, newest first.Free
GET/usageCurrent tier, credit balance, monthly requests and conversion totals.Free
GET/usage/summaryDaily request counts for the last 30 days.Free
GET/webhooksList your webhook subscriptions.Free
POST/webhooksSubscribe a URL to conversion.completed and conversion.failed events.Free
PUT/webhooks/{id}Update a webhook's URL, events or active status.Free
DELETE/webhooks/{id}Delete a webhook.Free
POST/webhooks/{id}/testDeliver a signed ping event to verify your endpoint.Free
GET/api-keysList your key metadata. Secret values are never returned.Free
POST/api-keysCreate a key and return the plain value once.Free
DELETE/api-keys/{id}Revoke a key.Free

Authentication

Send Your Key in the X-API-Key Header

All endpoints expect an X-API-Key header containing your key. An Authorization: Bearer YOUR_API_KEY header is also accepted. Create and manage keys in the business API keys page β€” keys are scoped to your business and inherit its tier, credit balance and rate limits.

Never expose your key in client-side code (browser JavaScript, mobile app bundles). For public-facing apps, use the Conversion Widget or proxy requests through your own backend so the key stays server-side.

What To Expect

Rate Limits & Status Codes

PlanRequests/minMonthly requests
Free101,000
Individual6010,000
Business12050,000
EnterpriseCustomUnlimited
CodeMeaning
200OK β€” request succeeded.
201Created β€” conversion or API key created.
202Accepted β€” asynchronous scan started; poll its scan_id.
401Unauthorized β€” missing, invalid or expired API key.
402Payment required β€” not enough credits for a chargeable tool.
403Forbidden β€” the business account is suspended.
404Not found β€” resource missing or not owned by your business.
422Validation failed or an unknown bookmaker id was sent.
429Too many requests β€” rate limit or credit allowance exhausted.
500Server error β€” try again, then contact support.
502Tools engine unavailable or webhook delivery failed.
504Tools engine timed out; no credit is charged.

Get Your API Key β†’

When to Use the API

Six developer scenarios where direct API access beats the website or widget.

πŸ“°

You run a tipster site at volume

Posting 50+ codes a day across multiple bookmakers? The API converts in bulk via your CMS pipeline β€” no manual rework, no widget clicks.

For lower volume β€” use the widget
πŸ“±

You're building a mobile app

Native iOS/Android apps can't easily embed a web widget. Hit the API directly from your backend, render results in your own UI components.

Talk to us about your integration
πŸ€–

You're running a betting bot

Discord bots, Telegram bots, custom Slack integrations β€” the API is the right surface. Get JSON, render to your platform's message format.

Or use our Telegram bot
πŸ“Š

You're doing analytics on bet codes

Need to decode hundreds of codes? POST /tools/decode returns every leg, market and price as structured JSON, and GET /conversions returns your own conversion history β€” enough to build your own backtest tooling.

See our analyzer UI
🏒

You're an affiliate marketing platform

Use POST /tools/scan to programmatically surface the best-odds bookmaker per fixture for your affiliates β€” drive higher commissions on each conversion.

See affiliate offers
βš™οΈ

You need full UX control

The widget is fast but opinionated. The API is stateless β€” you decide everything: layout, branding, error handling, and what to do with legs the engine could not price.

Get an enterprise quote

Bookmakers Your API Calls Can Convert To

Recommended Bookmakers

Every bookmaker accessible via the API also has a Betloy affiliate offer your end users can claim.

1xBet
Nigeria Β· Ghana Β· Kenya Β· Global
Get up to ₦130,000 Welcome Package4 first-deposit bonuses + free spins for new customers.
Promo code:BETLOY130
Open 1xBet with Bonus β†’
Paripesa
Nigeria Β· Ghana Β· Kenya Β· Tanzania
Get up to ₦150,000 Welcome Bonus200% match on your first deposit for new customers.
Promo code:BETLOY150
Open Paripesa with Bonus β†’
22bet
Nigeria Β· Kenya Β· Tanzania Β· Global
Get up to ₦50,000 Welcome Bonus100% first-deposit bonus up to ₦50,000.
Promo code:BETLOY50
Open 22bet with Bonus β†’

Bookmaker availability changes; use GET /bookmakers for the live list. Find the full list of bonuses on our promo codes hub.

All 100+ Bookmakers the Betloy API Supports

The /convert endpoint supports every bookmaker on this list β€” pass from_bookie_id and to_bookie_id in the JSON body and we return a ready-to-stake code. Use GET /bookmakers for the live list and ids.

Don't see your bookmaker? Request it β†’

Why Build On The API

The Same Engine That Powers The Whole Site

Every Betloy product β€” the website converter, the Telegram bot, the conversion widget, the embeddable Bet Slip Saver and AI Analyzer β€” runs on the same backend. The API is that backend, exposed for direct access. When we improve the conversion accuracy or add a new bookmaker, every API consumer gets the upgrade automatically.

That includes the 88.72% conversion success rate across supported bookmaker pairs, the multi-sport accumulator handling, the leg-flagging behaviour (when a market can't be matched, we tell you instead of silently substituting), and the per-bookmaker market mapping that we update whenever a supported book changes its code format.

If you're building anything that touches African bet codes β€” tipster sites, mobile apps, analytics pipelines, custom bots, affiliate platforms β€” the API is the most direct path. The widget wraps it for no-code embeds; the Telegram bot wraps it for chat. The API itself gives you everything else.

API FAQs

Everything we get asked about the Betloy REST API. If your question isn't here, drop us a line.

What does the Betloy API do?
It exposes the Betloy bet code engine as a REST API. Convert codes between bookmakers, decode a slip into legs and markets, rebuild it with edits, trim it to fit a stake, or scan it across bookmakers. The same engine powers the website, the Telegram bot and the widget.
How do I get an API key?
Create a business account and generate a key at /business/api-keys. Keys are scoped to your business and inherit its tier, credit balance and rate limits.
Which endpoints are available?
GET /bookmakers, GET /bookmakers/{id}, GET /tools, GET /tools/bookmakers, POST /tools/decode, POST /tools/rebuild, POST /tools/trim, POST /tools/scan, GET /tools/scan/{scan_id}, POST /tools/leg-options, POST /convert, GET /convert/{id}, GET /conversions, GET /usage, GET /usage/summary, plus webhook and API key management. The table above lists every route with its credit cost.
Are there official client libraries?
There are no official SDKs. The API is plain JSON over HTTPS, so any HTTP client works; the examples above show cURL, Node.js, Python and PHP.
How does authentication work?
Send X-API-Key: YOUR_API_KEY. An Authorization: Bearer YOUR_API_KEY header is also accepted. Keys are scoped to your business. Never embed a key in client-side code (browser JS, mobile app bundles) β€” proxy through your own backend if you need to call the API from public-facing code.
What are the rate limits?
Free: 10 requests/minute and 1,000 requests/month. Individual: 60/minute and 10,000/month. Business: 120/minute and 50,000/month. Enterprise: custom. Requests and credits are separate limits. A 429 response includes Retry-After.
Does each endpoint cost a credit?
Reads are free: bookmakers, decode, scan status, leg options, usage, webhooks and API key management. POST /convert, POST /tools/rebuild, POST /tools/trim and POST /tools/scan cost one credit, charged only after a successful result. Failed calls are never charged, and every chargeable response reports credits_charged and credits_remaining.
What's the response format?
JSON. Successful business responses use {success, data, meta}, where meta carries credits_charged and credits_remaining. Errors use {success:false, error:{code,message,stage,details}}, except validation errors on /convert, webhooks and API keys, which use Laravel's {message, errors} shape.
How do I handle flagged legs?
A conversion that fails returns 201 with data.status = failed, data.converted_code = null and an error_message; it does not consume a credit. Tools responses include warnings for legs the engine could not price. Nothing is silently substituted.
Is there a sandbox / test mode?
There is no separate sandbox. Free read endpoints (bookmakers, decode, scan status, leg options) let you build without spending credits, and chargeable calls only deduct on success. Use a separate key for development so you can rotate it independently.
What about webhooks?
Webhooks are available now: create them under /api/v1/webhooks, subscribe to conversion.completed and conversion.failed, and use the test endpoint to send a signed ping. Deliveries include an X-Betloy-Signature HMAC-SHA256 header.
Can I use the API from a browser?
Technically yes β€” we serve appropriate CORS headers β€” but you should never expose your API key in browser code. For browser-side use, run the call through your own backend and forward the result. Or use the Conversion Widget, which does this safely without you needing a key.
What's the SLA for paid plans?
Paid plans include an uptime commitment; enterprise plans can negotiate a custom SLA with credit-back terms. Contact support for the current terms covering your plan.
Can I get historical data through the API?
GET /conversions returns your business's conversion history, newest first, 20 per page. GET /usage and GET /usage/summary cover credit balance and daily request counts. Contact us for bulk exports.
How does the API differ from the Widget?
The Widget is a drop-in HTML embed β€” your visitors interact with our UI inside your page, no API key required. The API is programmatic β€” you call from your server, you control the UI entirely. Use the widget when you want fast no-code embedding; use the API when you want full UX control or higher request volume.

Your First Conversion in Under 60 Seconds

Sign up free. 10 conversions per month, every month, permanently. No card required.

Create Free Account