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://www.betloy.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "booking_code": "B3US96U",
    "from_bookie_id": 1,
    "to_bookie_id": 2
  }'

// npm install @betloy/sdk
const { Betloy } = require('@betloy/sdk');
const betloy = new Betloy({ apiKey: process.env.BETLOY_API_KEY });

const result = await betloy.convert({
  booking_code: 'B3US96U',
  from_bookie_id: 1,
  to_bookie_id: 2,
});

console.log(result.data.converted_code);   // → "SP9KQM2"
console.log(result.legs);   // → 5
console.log(result.flagged); // → []

# pip install betloy
from betloy import Betloy

client = Betloy(api_key=os.environ['BETLOY_API_KEY'])

result = client.convert(
    booking_code='B3US96U',
    from_bookie_id=1,
    to_bookie_id=2,
)

print(result.data.converted_code)     # → "SP9KQM2"
print(result.legs)     # → 5
print(result.flagged)  # → []

// composer require betloy/sdk
use Betloy\Client;

$betloy = new Client(getenv('BETLOY_API_KEY'));

$result = $betloy->convert([
  'booking_code' => 'B3US96U',
  'from_bookie_id' => 1,
  'to_bookie_id'   => 2,
]);

echo $result->data->converted_code;  // → "SP9KQM2"

Request body

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

Response (200 OK)

{
  "success": true,
  "data": {
    "conversion_id": "conv_123456",
    "original_code": "B3US96U",
    "converted_code": "SP9KQM2",
    "from_bookie": "Bet9ja",
    "to_bookie": "Sportybet",
    "total_odds": 68.40,
    "number_of_events": 5,
    "status": "completed"
  },
  "message": "Conversion successful"
}

Reference

Endpoints

All endpoints are POST or GET against https://www.betloy.com/api/v1/. JSON in, JSON out.

Method	Endpoint	Purpose
POST	`/convert`	Convert a bet code from one bookmaker to another. Returns the new code, leg count, combined odds, and any flagged (unmatchable) legs.
POST	`/scan`	Scan a code across every supported bookmaker and return ranked best-odds matches. Same engine as the Odds Scanner UI.
POST	`/analyze`	Run a code through the AI Bet Analyzer. Returns Risk Score, Win Probability, Recommended Stake.
POST	`/trim`	Apply Risk Trimmer transformations (drop correct-score, soften 1X2, step over-goals down). Returns the trimmed code and the per-leg changelog.
POST	`/decode`	Decode a code into a structured leg list (read-only). Same engine as the Bet Viewer UI.
GET	`/bookmakers`	List every supported bookmaker with its key, region, and supported markets. Useful for populating dropdowns in your own UI.
GET	`/usage`	Return the current month's credit usage and remaining allowance for your API key.
GET	`/health`	Liveness check. Returns 200 if the API is up. No auth required.

Authentication

Bearer Token in the Authorization Header

All authenticated endpoints expect an Authorization header of the form Bearer YOUR_API_KEY. Generate a key in your account dashboard — keys are scoped to your account and inherit your plan's 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

Plan	Requests/min	Monthly requests
Free	10	1,000
Individual	60	10,000
Business	120	50,000
Enterprise	Custom	Unlimited

Code	Meaning
200	OK — request succeeded.
202	Accepted — async job queued (rare; only for batch endpoints).
400	Bad request — invalid params or unsupported bookmaker.
401	Unauthorized — missing or invalid API key.
402	Payment required — credit allowance exhausted.
429	Too many requests — rate limit hit.
500	Server error — try again, then contact support.

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 SDKs

🤖

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 and analyze hundreds of historical codes? The /decode endpoint plus /analyze in batch lets you build your own backtest tooling.

See our analyzer UI

🏢

You're an affiliate marketing platform

Use /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, what to do with flagged legs.

Get an enterprise quote

Don't stop here — try these too

🧩

Conversion Widget

Drop-in embed for non-developers — one line of HTML, no API key needed.

Embed Docs →

✈️

Telegram Bot

Same engine in chat. Add @BetloyBot to your group or channel.

Open Bot →

🔁

Try the converter live

Use the website converter to sanity-check what the API will return.

Open Converter →

🤝

Enterprise & SLAs

Custom rate limits, dedicated support, uptime SLAs, white-label options.

Get in touch →

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. Pass an affiliate ID in your conversion request to attribute signups.

1xBet

Nigeria · Ghana · Kenya · Global

Get up to ₦130,000 Welcome Package4 first-deposit bonuses + free spins for new customers.

Open 1xBet with Bonus →

Paripesa

Nigeria · Ghana · Kenya · Tanzania

Get up to ₦150,000 Welcome Bonus200% match on your first deposit for new customers.

Open Paripesa with Bonus →

22bet

Nigeria · Kenya · Tanzania · Global

Get up to ₦50,000 Welcome Bonus100% first-deposit bonus up to ₦50,000.

Open 22bet with Bonus →

As a Betloy API partner, you can pass an affiliate_id on conversion requests to attribute signups. 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 the source/destination as query params and we return a ready-to-stake code.

🇳🇬 Nigeria & West Africa

🇰🇪 East Africa

🇿🇦 South & Southern Africa

🌍 International & Global

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 Risk Trimmer 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, scan for the best odds, decode any code into structured legs, run a slip through the AI Analyzer, or apply Risk Trimmer transformations — all programmatically. Same engine as the website, accessible from any language that can make HTTP requests.

How do I get an API key?

Sign up for a Betloy account (free), then generate a key in your account dashboard. Keys inherit your plan's rate limits — see the pricing page for the limit per tier.

Which endpoints are available?

The main ones: POST /convert, POST /scan, POST /analyze, POST /trim, POST /decode, GET /bookmakers, GET /usage, GET /health. The documentation below lists each with its purpose.

Are there official client libraries?

Yes — official SDKs for Node.js, Python, and PHP. The SDKs handle auth, retries, and idiomatic typing for each language.

How does authentication work?

Bearer token in the Authorization header: Authorization: Bearer YOUR_API_KEY. Keys are scoped to your account. 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, 10 credits/month. Individual: 120 r/min, from 100 credits/month. Business: 1,200 r/min, from 2,000 credits/month. Enterprise: custom. Hit a limit and you get a 429 response with a Retry-After header.

Does each endpoint cost a credit?

Mostly yes — conversion (/convert), trim (/trim) and analyze (/analyze) each use one credit. Decode and scan are usually free or low-cost depending on plan. Lookup endpoints (/bookmakers, /usage, /health) are free. Your remaining credit balance is returned in the response.

What's the response format?

JSON. Successful responses return the requested data plus metadata (credits remaining, request ID). Error responses include a code, message and (where relevant) a hint about what to fix.

How do I handle flagged legs?

Conversions return a flagged array listing any legs we couldn't confidently match on the destination bookmaker. You decide what to do — fail the whole slip, present the partial conversion to the user with the flagged legs highlighted, or retry against a different destination. We never silently substitute.

Is there a sandbox / test mode?

Yes — append ?test=true to any request to use the test environment. Test calls don't consume credits and return deterministic mock data so you can build against the API without burning your allowance.

What about webhooks?

Webhooks are on the roadmap for usage alerts and async batch results. For now, all endpoints are synchronous — you get the result inline in the response.

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?

Individual and Business plans target 99.5% monthly uptime. Enterprise plans negotiate a custom SLA (typically 99.9%) with credit-back terms. Our status page and incident history are public.

Can I get historical data through the API?

The /decode endpoint works on any code, including expired ones — useful for historical analysis. The /usage endpoint returns your past usage. Bulk historical exports are available on the Enterprise plan.

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.