Convat API reference

Introduction

Convert a sportsbook booking code issued by one bookmaker into a live booking code on another.

The API covers 51 bookmakers as a source and 57 as a destination, 2,866 directions in all. Keys are issued after a short agreement: request access and we will send an evaluation key with free credits.

Quick start

Call the API from your server, never from an app or a browser. Every POST /convert needs an Idempotency-Key: a new value per conversion, and the same value on every retry of it.

curl -X POST https://eval-api.convat.io/v1/convert \
  -H "Authorization: Bearer $CONVAT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"source":"bet9ja","target":"sportybet","code":"5VV8VYM"}'

import { randomUUID } from 'node:crypto';

// One key per conversion you intend. Keep it, and send the SAME
// value again if you retry this conversion.
const idempotencyKey = randomUUID();

const res = await fetch('https://eval-api.convat.io/v1/convert', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CONVAT_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({"source":"bet9ja","target":"sportybet","code":"5VV8VYM"}),
  signal: AbortSignal.timeout(60_000),
});

const data = await res.json();
if (res.ok) {
  console.log(data.targetCode, `${data.matched} of ${data.total} legs`);
} else {
  console.log(res.status, data.error, data.message);
}

A real response from the evaluation service. This one is a partial: 6 of 8 legs were booked, and unmatched says why the rest were not. Long leg lists are shortened here.

{
  "success": true,
  "sourceBookie": "bet9ja",
  "sourceCode": "5VV8VYM",
  "targetBookie": "sportybet",
  "targetCode": "GTTDHC",
  "matched": 6,
  "total": 8,
  "slipOddsTotal": 42.48,
  "sourceOddsTotal": 22.84,
  "targetOddsTotal": 24.4,
  "matchedSelections": [
    {
      "eventName": "Olimpia Milano - Dubai Basketball",
      "competition": "Euroleague",
      "market": "WINNER",
      "selection": "HOME",
      "line": null,
      "startDate": "2026-10-15 18:30:00",
      "sourceOdds": "2.05",
      "targetOdds": "2.12",
      "lineAdjusted": false,
      "bookedLine": null,
      "inPlay": false
    },
    {
      "eventName": "AL Hazem - AL Fateh",
      "competition": "Saudi Professional League",
      "market": "MATCH_RESULT",
      "selection": "HOME",
      "line": null,
      "startDate": "2026-10-15 15:15:00",
      "sourceOdds": "2.52",
      "targetOdds": "2.6",
      "lineAdjusted": false,
      "bookedLine": null,
      "inPlay": false
    }
  ],
  "unmatched": [
    {
      "eventName": "Brisbane Bullets - SE Melbourne Phoenix",
      "market": "WINNER",
      "selection": "AWAY",
      "line": null,
      "startDate": "2026-10-15 08:30:00",
      "reason": "event_not_found",
      "reasonText": "We couldn't find this game on SportyBet."
    },
    {
      "eventName": "Kolodziej, Krystian - Jadczyk, Marcin",
      "market": "WINNER",
      "selection": "AWAY",
      "line": null,
      "startDate": "2026-10-15 03:45:00",
      "reason": "event_not_found",
      "reasonText": "We couldn't find this game on SportyBet."
    }
  ],
  "processingTimeMs": 733
}

Hosts and keys

• Production: https://api.convat.io/v1 (production keys, issued with a paid plan)
• Evaluation: https://eval-api.convat.io/v1 (evaluation keys)

Keys are issued after a short agreement. Request access at convat.io/api.

Send your key as Authorization: Bearer <key>. Keys are scoped per environment: an evaluation key works only on the evaluation host and a production key only on the production host. Call the API from your own backend. Never put a key in a mobile app, a browser or any other client.

What a conversion returns

A real coupon created in the target bookmaker's own system (targetCode), plus the odds read back after creation. Not a list of legs for you to book.

Partial conversions

Bookmakers do not all carry the same games and markets, so a conversion can succeed with fewer legs than the source slip. Every 2xx accounts for every leg: matchedSelections.length + unmatched.length == total, and every entry in unmatched carries a reason code and a reasonText sentence. Compare matched with total rather than assuming a full slip.

Lines on totals

When the destination does not list the exact line of an over/under total, the leg is booked on the nearest line it does list, never more than 0.5 away, and marked lineAdjusted: true with the bookedLine. Handicaps never move. Send "exactLines": true with /convert to refuse that: every total is booked on its own line or left out, listed in unmatched with reason selection_not_offered and a reasonText naming the closest line. We can also switch exact lines on for your whole key, so every conversion uses them without the field: ask support@convat.io.

Odds

• slipOddsTotal: the whole source slip at the source bookmaker's prices.
• sourceOddsTotal and targetOddsTotal: the legs that were BOOKED, at the source and target prices. Compare these two with each other.
• targetOddsTotal is null when the target returns no price.
• /preview returns source odds only. It contacts no target bookmaker.

Odds are read back from the created coupon, and odds move. Show them to your users before they stake.

Credits

One credit per conversion that returns a target code (a 2xx with targetCode). Failed conversions, refusals, unsupported directions, /preview, /health and replays cost nothing. At the cap every conversion is refused with 402 quota_exhausted and nothing is booked.

Idempotency-Key (required on POST /convert)

Generate a new value (a UUID) for every conversion you intend, and send the SAME value on every retry of it.

• Completed: sending the key again within 24 hours of the result returns the original status and body, byte for byte, with Idempotency-Replayed: true. Nothing is booked and no credit is used.
• Still running: 409 request_in_progress. Nothing new is started. Wait for Retry-After and retry with the same key to receive the result.
• Different payload: the same key with a different source, target, code or exactLines is refused with 422 idempotency_key_reused. Nothing is booked.
• Only a 2xx is final. After any error the key is released, so a retry with the same key runs the conversion again, and the failed attempt cost nothing.
• A conversion keeps running if your client times out or disconnects. Retry with the same key: you receive its result when it has finished, or 409 while it is still running.
• After 24 hours a key is forgotten and the same value starts a new conversion.
• If our service restarts while your request is running, the key stays in progress for up to about two and a half minutes and then a retry runs the conversion again. In that rare case a coupon may have been created at the bookmaker that was never returned to you and was never charged.

Request ids

Every response, including every error, carries:

• X-Request-Id: new for every HTTP request.
• X-Correlation-Id: the same for every attempt and every replay that uses one Idempotency-Key, so one intended conversion can be traced end to end.

Timeouts, retries and unknown outcomes

Most conversions answer in a few seconds. A slow bookmaker can stretch one to about a minute, and a few destinations occasionally take longer. Set your client timeout to 60 seconds; if it fires, retry with the same Idempotency-Key and you receive the result once the conversion has finished.

Retry only 429, 502 and 503, with backoff and always with the SAME Idempotency-Key. On 409, wait and retry with the same key. Never retry a 2xx. Other 4xx responses are final for that request.

A 429, 502, 503 or a timeout alone does not prove that no coupon was created. Retrying with the same key is always safe. If you still need help, email support@convat.io with the X-Request-Id, X-Correlation-Id, Idempotency-Key, source, target, source code and the time in WAT.

Limits

Per key: a number of requests per minute (/convert and /preview together) and a number of conversions in flight at once. /preview has its own in-flight allowance of the same size. Over a limit: 429 with Retry-After. The limits on your key are confirmed when it is issued.

Markets, selections and dates

market and selection are universal codes, the same for every bookmaker (for example MATCH_RESULT with HOME, or OVER_UNDER with OVER and a line). On /preview, sourceMarket is the bookmaker's own name for the market. startDate is YYYY-MM-DD HH:MM:SS in UTC, as the source bookmaker reports it, or null.

ConvertRequest

ConvertResponse

MatchedSelection

UnmatchedSelection

PreviewRequest

PreviewResponse

PreviewLeg

Error

Leg reasons

Every entry in unmatched carries one of these codes in reason, plus a plain reasonText sentence that is safe to show to your users. Branch on the code.

Errors

Branch on error, never on message. message is a plain sentence that is safe to show to your users and never names us.

Bookmakers

Keys cover every bookmaker the service supports: 51 can be read as a source and 57 can be written as a destination, 2,866 directions in all. Every one of them is listed below.

betano, goka, ngbet, stake restrict access from many locations, so reading their slips is occasionally unavailable. When it is, /convert and /preview answer 502 upstream_error with sourceUnavailable: true. Nothing is booked and nothing is charged.

A request for a direction your key does not cover is refused with 422 unsupported_direction, and that response lists every direction your key can use, so you never need to hardcode the list. New bookmakers are added to keys that cover every bookmaker as soon as the service supports them.

Source and destination

Source only (codes can be read from them)

Destination only (country stores; send the id as the target)