Zad Top REST API — reference

An HTTPS JSON API for shops, resellers and automation that sell Free Fire diamonds, PUBG Mobile UC, Yalla Ludo Diamonds / Gold and Jawaker tokens: redeem vouchers you send in the request or vouchers stored in your own stock, resolve a player id to its in-game nickname before a card is spent, read stock counts, request allowance and redeem history, and render the shop's own order receipt as an image. It is the same service, wallet, stock and history as the Telegram bot — only the interface differs. Messages returned by this API are in English. The game field selects the shop; every other field stays the same.

Protocol HTTPS · JSON · UTF-8 Version /v1/* Base URL this host Auth X-API-Key Bot @ZadTopBot
Code samples

When this page is opened on the API host, ${BASE} and __ORIGIN__ in the samples are rewritten to that server's URL. In your own scripts use https://api.zadtop.com and the key you copied from the bot.

Introduction

There are two call patterns, and every integration uses both:

  • Synchronous calls — one request, final JSON: /health, account and allowance (/v1/me, /v1/quota), stock counts, redeem history, saved players, and player lookup (show the nickname on a checkout screen before a card is spent).
  • Asynchronous jobs — a redeem talks to the shop and needs seconds, so POST answers immediately with a job_id and the work runs in a server-side queue. Read GET /v1/jobs/{job_id}?wait=25 to get the answer the moment the job ends, instead of polling in a loop. This keeps slow upstream calls from timing out your HTTP client.

Keys are created inside the bot (@ZadTopBot) under Subscription → HTTP API → API key, and require an active plan plus the HTTP API add-on. Everything the API writes — jobs, redeem rows, players, receipts — shows up in the bot as well, and the other way round.

Check a card before you redeem it. POST /v1/codes/check reads whether a Free Fire, PUBG, Yalla Ludo Diamonds or iTunes card is unused, already used, or never existed — without spending it, and a good card stays good however often you ask. POST /v1/jobs/code-check does the same for a bulk batch. Ludo Gold and Jawaker have no code check.
Ludo check = Diamonds codes only. Never send a Ludo Gold code with game: "ludo": a Gold card can be redeemed and spent.
A valid card is credited on contact. Send each code once through /v1/jobs/instant-redeem and read its outcome from the job. The check route is the dry run; the redeem route is not. Used and invalid cards come back as ordinary failed rows (CODE_ALREADY_USED, INVALID_CODE).
Almost every country is supported, not only the Middle East. For Free Fire, the exceptions are the countries where Garena sells no vouchers (the United States, Argentina, Chile and Russia): player lookup answers 422 UNSUPPORTED_REGION, and a redeem for such a player returns UNSUPPORTED_REGION rows. The cards are not spent.

Quick start

Step 1: prove the host answers. Step 2: send a real key. Step 3: redeem a card and read the outcome. Replace pk_YOUR_KEY_HERE with the key from the bot.

1) Health — no key

Verify TLS + reachability
curl -sS -o /dev/null -w "%{http_code}\n" "${BASE}/health"
# expect: 200 and body {"ok":true}
import requests

BASE = "__ORIGIN__"
r = requests.get(f"{BASE}/health", timeout=30)
r.raise_for_status()
print(r.json())   # {"ok": True}
const BASE = "__ORIGIN__";
const r = await fetch(`${BASE}/health`);
console.log(r.status, await r.json());
<?php
$base = "__ORIGIN__";
echo file_get_contents($base . "/health");
resp, err := http.Get("__ORIGIN__/health")
if err != nil { log.Fatal(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(body))

2) Authenticated ping — GET /v1/quota

Confirm the key, the plan and the requests left
curl -sS "${BASE}/v1/quota" -H "X-API-Key: pk_YOUR_KEY_HERE"
import requests

BASE = "__ORIGIN__"
HEAD = {"X-API-Key": "pk_YOUR_KEY_HERE"}
print(requests.get(f"{BASE}/v1/quota", headers=HEAD, timeout=30).json())
const r = await fetch(`${BASE}/v1/quota`, { headers: { "X-API-Key": "pk_YOUR_KEY_HERE" } });
console.log(await r.json());
<?php
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: pk_YOUR_KEY_HERE\r\n"]]);
echo file_get_contents("__ORIGIN__/v1/quota", false, $ctx);
req, _ := http.NewRequest("GET", "__ORIGIN__/v1/quota", nil)
req.Header.Set("X-API-Key", "pk_YOUR_KEY_HERE")
resp, err := http.DefaultClient.Do(req)

401 means the header is missing or the key was replaced. 403 means the account has no active plan + API add-on. See Authentication.

3) First redeem — queue, then wait

POST /v1/jobs/instant-redeem → GET /v1/jobs/{id}?wait=25
JOB=$(curl -sS -X POST "${BASE}/v1/jobs/instant-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"123456789","codes":["4233939008625064"],"game":"freefire"}' \
  | sed -n 's/.*"job_id":"\([^"]*\)".*/\1/p')

curl -sS "${BASE}/v1/jobs/$JOB?wait=25" -H "X-API-Key: pk_YOUR_KEY_HERE"
import requests

BASE = "__ORIGIN__"
HEAD = {"X-API-Key": "pk_YOUR_KEY_HERE", "Content-Type": "application/json"}

job = requests.post(
    f"{BASE}/v1/jobs/instant-redeem",
    headers=HEAD,
    json={"player_id": "123456789", "codes": ["4233939008625064"], "game": "freefire"},
    timeout=30,
).json()

done = requests.get(f"{BASE}/v1/jobs/{job['job_id']}?wait=25", headers=HEAD, timeout=40).json()
for row in (done.get("result") or {}).get("results", []):
    print(row["code"], row["success"], row.get("err_code"), row.get("total"))
const HEAD = { "X-API-Key": "pk_YOUR_KEY_HERE", "Content-Type": "application/json" };

const job = await (await fetch(`${BASE}/v1/jobs/instant-redeem`, {
  method: "POST",
  headers: HEAD,
  body: JSON.stringify({ player_id: "123456789", codes: ["4233939008625064"], game: "freefire" }),
})).json();

const done = await (await fetch(`${BASE}/v1/jobs/${job.job_id}?wait=25`, { headers: HEAD })).json();
console.log(done.status, done.result?.ok_count, done.result?.results);
<?php
$base = "__ORIGIN__";
$head = "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n";
$body = json_encode(["player_id" => "123456789", "codes" => ["4233939008625064"], "game" => "freefire"]);

$ctx = stream_context_create(["http" => ["method" => "POST", "header" => $head, "content" => $body]]);
$job = json_decode(file_get_contents("$base/v1/jobs/instant-redeem", false, $ctx), true);

$ctx2 = stream_context_create(["http" => ["header" => $head]]);
echo file_get_contents("$base/v1/jobs/{$job['job_id']}?wait=25", false, $ctx2);
payload := strings.NewReader(`{"player_id":"123456789","codes":["4233939008625064"],"game":"freefire"}`)
req, _ := http.NewRequest("POST", BASE+"/v1/jobs/instant-redeem", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
// decode {"job_id":"...","status":"pending"} then GET /v1/jobs/{id}?wait=25

Conventions

Codes & player idsSend them as strings, exactly as printed on the card or shown in the game. A code that is not valid for the chosen game is refused with 400 INVALID_CODE before anything is sent or charged.
FormatRequests and responses are application/json, UTF-8. The one exception is POST /v1/order/screenshot, which returns raw PNG bytes (image/png) on success.
TimestampsFields ending in _stamp are Unix seconds (UTC). time_created is a human-readable server string. Daily allowance resets on the UTC calendar day.
IDsjob_id, history_id and history id are 24-character strings. Store them as text.
OwnershipEvery route is scoped to the account behind the key. A job_id or history_id from another account answers 404, never someone else's data.
IdempotencyThere is none, by design: each POST to a job route creates a new job. Posting the same codes twice queues two redeems — deduplicate on your side before sending.
VersioningThe /v1/ prefix allows additive changes. A breaking change would ship under a new prefix.
OpenAPIMachine-readable schema: /openapi.json · interactive UI: /swagger · ReDoc: /redoc.

Authentication

Every route below except GET /health requires one header:

X-API-Key: pk_YOUR_KEY_HERE
Getting a keyIn @ZadTopBot: Subscription → HTTP API → API key → New key. The key is shown once; creating a new one revokes the old one immediately.
EligibilityAn active plan (p1…p6) and an active HTTP API add-on, or an API trial granted by support. Missing either one → 403 with the text explaining what to buy. A game your plans do not cover answers 403 GAME_NOT_IN_PLAN.
Check-only accessA Code checking subscription on its own opens the check routes: POST /v1/codes/check, POST /v1/jobs/code-check, GET /v1/jobs, GET /v1/jobs/{id}, /v1/me, /v1/quota and POST /v1/subscription/purchase-check-code. Every other route answers 403 CHECK_CODE_SUBSCRIPTION_ONLY. /v1/me tells which access the key has in api_access: "full" or "check_code".
Invalid key401 — Missing X-API-Key header or Invalid or revoked API key.
One key, one accountThe key maps to the Telegram account that owns the wallet, the stock and the history. Requests appear in that account's history and alerts.
SecurityKeep the key server-side. Never ship it in a browser bundle or a mobile app — anyone holding it can spend your stock and your allowance. If it leaks, create a new key in the bot; the old one dies at once.

Pricing & quota

Usage is counted in requests, the same unit the bot shows. One allowance serves the bot and the API. You are charged only for answers about your cards; a failure on our side is never charged.

What each call costs

Redeem1 request per code (instant-redeem) or per card taken from your stock (stock-redeem), charged when the job runs.
Code check1 request per card the shop gave a verdict on. A card that comes back unknown, error or maintenance is free. With a Code checking subscription the card is taken from its budget first.
Player lookup0.25 requests for a name (200), an unknown id (404) or an unsupported country (422). 400 and 502 are free. The response carries quota_requests_charged.
Refunded automaticallyA card that failed for a reason that is not the card's own — NETWORK, SESSION_EXPIRED, VERIFICATION, VERIFICATION_FAILED, RATE_LIMITED, SHOP_BLOCKED, SHOP_MAINTENANCE, REDEEM_FAILED — is credited back when the job finishes. CODE_ALREADY_USED, INVALID_CODE, REGION_MISMATCH, PLAYER_NOT_FOUND, ACCOUNT_RESTRICTED, PLAYER_BANNED and PLAYER_RISK_LIMITED stay charged.
Free routes/health, /v1/me, /v1/quota, /v1/stock/summary, /v1/history, /v1/players, /v1/jobs… reads and /v1/order/screenshot.
Spending orderFree-trial requests first, then the daily allowance of your plans, then an API trial if support granted one. A code check spends the Code checking budget before all of these.
Daily resetMidnight UTC.
Not enough leftA job finishes as failed with error: "quota_exhausted:…"; nothing is redeemed. player/lookup, codes/check and jobs/code-check answer 429 QUOTA_EXHAUSTED and do nothing. Check /v1/quota before large batches.

Plans

Every plan runs 30 days and is bought for the games you pick. The daily limit is shared by the plan's games. Picking three games or more is the same as all games.

plan_keyRequests / day1 game2 games (×1.3)All games (×1.5)
p1255 USDT6.5 USDT7.5 USDT
p220010 USDT13 USDT15 USDT
p31 00025 USDT32.5 USDT37.5 USDT
p42 50050 USDT65 USDT75 USDT
p55 00085 USDT110.5 USDT127.5 USDT
p610 000135 USDT175.5 USDT202.5 USDT
HTTP API add-onunlocks the API for all your plans — a fixed 15 USDT / 30 days, whatever the plan or games
Free trial10 free requests for every new account, valid for all games.
Adding gamesAdd a game to an active plan from the bot (Subscription → Add games to my plan). You pay only the price difference for the days left.
Several plansActive plans add up. Each one serves only the games it was bought for.
RenewingBuying the same plan for the same games extends it by 30 days.
DiscountA discount granted by support is applied automatically to your next plan purchase, in the bot or through the API, and is then used up.
PaymentFrom the wallet balance (top up in the bot). The bot's Subscription menu always shows the current prices.

Code checking subscription

For checking cards only: a budget of card reads for Free Fire, PUBG Mobile, Yalla Ludo Diamonds and iTunes, with no daily limit. It never pays for a redeem or a lookup.

plan_keyCard reads / 30 daysPrice
cc1150 000100 USDT
cc2250 000150 USDT
What it pays forcodes/check, jobs/code-check and the bot's own code check — 1 card from the budget per card the shop gave a verdict on.
OrderTaken first; what the budget cannot cover falls through to the trial / daily allowance of a plan, if there is one. Paid responses report both: check_code_charged (cards from the budget) and quota_requests_charged (requests from the allowance).
Buying againWhile one is running, the new codes are added to what is left and the 30 days restart from the purchase. Codes unused when it ends expire.
API accessOn its own it opens the check routes only — see Authentication.
Remainingcheck_code_subscription on /v1/me and /v1/quota.
BuyingIn the bot (Subscription → Code checking only) or POST /v1/subscription/purchase-check-code.

Rate limits & concurrency

Parallel jobsUp to 4 of your jobs run at a time, oldest first. Extra jobs wait in the queue instead of being rejected, so you can post a burst safely.
LookupWhen the server is busy, /v1/player/lookup answers 429 RATE_LIMIT. Retry after a moment.
Screenshot15 renders per minute per key → 429 SCREENSHOT_RATE_LIMIT with Retry-After: 60.
Too many requestsAny route may answer 429 RATE_LIMIT with Retry-After: 60. Wait that long, then retry.
PollingUse ?wait=25 rather than a tight loop. Without wait, poll no faster than once per second.
MaintenanceDuring a short restart, new jobs answer 503 SERVICE_DRAINING and nothing is queued. Running jobs are finished and reads keep working. Retry after a few seconds.

HTTP status reference

Errors are JSON with a detail field — either a string (auth) or an object {"error": "CODE", "message": "…"}. Log the status line together with the body.

CodeWhenWhat to do
200Parsed fine. For jobs this only means the document was read — branch on status inside the JSON. For the screenshot route the body is binary PNG, not JSON.Inspect the payload, not just the status.
400Validation: INVALID_PLAYER_ID, INVALID_CODE, TOO_MANY_CODES, UNKNOWN_GAME, MISSING_TIER, MISSING_PICKS, GAME_REDEEM_UNAVAILABLE, GAME_LOOKUP_UNAVAILABLE, screenshot selection errors, or a rejected purchase.Read detail.error in the table below.
401X-API-Key missing, misspelled, or revoked by creating a newer key.Re-copy the key from the bot.
403No active plan + API add-on, GAME_NOT_IN_PLAN — none of your plans covers this game, or CHECK_CODE_SUBSCRIPTION_ONLY — a check-only key called another route.Renew, or add the game to your plan in the bot, then retry after a few seconds.
404PLAYER_NOT_FOUND, unknown job_id, or HISTORY_NOT_FOUND — including ids that belong to another account.Verify the id; list jobs or history.
409JOB_NOT_READY — a screenshot was asked for while the job is still pending/running.Wait for the job, then retry.
422Body did not match the schema (wrong type, missing field, more than 10 codes).Read the FastAPI validation detail; fix the payload.
429RATE_LIMIT or SCREENSHOT_RATE_LIMIT (too many calls), or QUOTA_EXHAUSTED (no requests left today).Rate limits: honour Retry-After: 60. Quota: wait for midnight UTC or buy a plan.
500ORDER_SCREENSHOT_FAILED or an unexpected server error.Retry once; include the message when contacting support.
502LOOKUP_FAILED — the shop could not be reached for a lookup. Nothing charged.Retry later.
503SERVICE_DRAINING — short maintenance; new jobs are refused.Retry in a few seconds; nothing was queued.

Response catalog (status, job, per-code outcome)

Treat three layers separately. A call can return HTTP 200 with job status: "done" while individual cards failed.

HTTP layerStatus line + detail — auth, validation, throttles, ownership.
Job layerstatus and error on GET /v1/jobs/{id} — the queue lifecycle.
Outcome layerresult.ok_count, result.failed_count and each result.results[].success / err_code — the business result, per card.
Critical: status: "done" means the job finished, not that every card was credited. Partial batches are normal: always loop over result.results[].

Structured detail.error codes

errorHTTPRoutesMeaning
INVALID_PLAYER_ID400lookup, redeem jobsThe player id is not valid for the chosen game. Nothing was sent or charged.
INVALID_CODE400instant-redeem, codes/check, code-checkA code is not a valid code for the chosen game. Nothing was sent or charged.
TOO_MANY_CODES400codes/check, code-checkMore codes than the route takes — limit and sent are in the body.
UNKNOWN_GAME400all game routesgame is not freefire, pubg, ludo, ludogold or jawaker.
MISSING_TIER400instant-redeemYalla Ludo was posted without a resolvable tier (quantity or Diamonds USD price).
GAME_REDEEM_UNAVAILABLE400redeem / checkThis game cannot be redeemed, or a code check was asked for a game that has none (Yalla Ludo, Jawaker).
GAME_LOOKUP_UNAVAILABLE400player/lookupLookup is not offered for this game.
MISSING_PICKS400stock-redeempicks was empty.
PLAYER_NOT_FOUND404player/lookupNo account with that id for the chosen game.
UNSUPPORTED_REGION422player/lookupA Free Fire account in a country where Garena sells no vouchers. region and player_name are included. Charged 0.25.
ACCOUNT_RESTRICTED422player/lookupA Yalla Ludo account the game itself refuses to top up (an official or restricted account). player_name and a message are included. Charged 0.25.
PLAYER_BANNED422player/lookupA PUBG Mobile account that is banned or restricted in the game. UC cannot be sent to this Player ID. player_name and message are included. Charged 0.25.
PLAYER_RISK_LIMITED422player/lookupRedeem this PUBG Mobile player manually. The message is Please redeem this Player ID manually. player_name is included. Charged 0.25. No card is sent.
LOOKUP_FAILED502player/lookupThe shop could not be reached; nothing charged.
RATE_LIMIT429any routeToo many calls, or the server is busy. Retry-After: 60.
QUOTA_EXHAUSTED429player/lookup, codes/check, code-checkNot enough requests left today, so nothing was done. needed and remaining are in the body. Requests refill at midnight UTC, or when you buy a plan. Redeem jobs accept the job and fail it with quota_exhausted:… instead.
GAME_NOT_IN_PLAN403player/lookup, codes/check, every job routeNone of your active plans was bought for this game, and no trial is left to pay for it. Nothing was done. Add the game to a plan in the bot (you pay the price difference for the days left), or buy a plan that covers it.
CHECK_CODE_SUBSCRIPTION_ONLY403every route except the check onesThe key has a Code checking subscription and no plan with the API add-on, so it may only check codes. Buy a plan with the add-on in the bot for the other routes.
SCREENSHOT_RATE_LIMIT429order/screenshotMore than 15 renders in a minute for this key.
MISSING_JOB_OR_HISTORY_ID400order/screenshotNeither job_id nor history_id was sent.
JOB_NOT_FOUND404order/screenshotNo such job for this key.
HISTORY_NOT_FOUND404order/screenshotNo such history row for this key.
JOB_NOT_READY409order/screenshotJob still pending/running.
JOB_NOT_SUCCESSFUL400order/screenshotJob ended failed.
NO_ORDER_DETAILS400order/screenshotresult_index points at no row, or at a failed one.
ORDER_SCREENSHOT_FAILED500order/screenshotThe card could not be produced right now; message says so. Retry in a minute.
SERVICE_DRAINING503job routesShort maintenance; nothing queued. Retry in a few seconds.
INSUFFICIENT_BALANCE400subscription routesThe wallet balance does not cover the price; balance and price are in the body. Top up in the bot.
PRICE_CHANGED400subscription/purchaseThe price changed during the purchase (for example a discount was used in the bot at the same moment). Nothing was charged; retry.
NEED_PLAN400purchase-api-addonThe API add-on needs an active plan. Buy a plan first.
UNKNOWN_PLAN400subscription/purchaseplan_key is not one of p1…p6.

Auth failures use a plain string detail: Missing X-API-Key header, Invalid or revoked API key, or the subscription explanation.

Job lifecycle

A create call returns {"job_id":"…","status":"pending"}. Poll until a terminal state.

statuspending → running → done or failed
resultThe outcome, present when the job is done.
errorA short string when status is failed; null otherwise.
Timingcreated_at_stamp, started_at_stamp, finished_at_stamp (Unix seconds).
Job error (status failed)MeaningClient action
quota_exhausted:…Not enough requests left when the job ran. Nothing was redeemed; your stock is untouched.Read /v1/quota; wait for midnight UTC or buy a plan.
quota_exhausted:game_not_coveredNone of your plans covers this game, and no trial is left.Add the game to your plan in the bot.
invalid_player_idThe player id is not valid for this game.Check the id, or run lookup first.
no_codesNo valid code was sent, or your stock holds none of the requested packs.Check the codes, or /v1/stock/summary.
invalid_payloadpicks could not be read as pack → quantity.Send integers keyed by pack size.
unknown_game · game_redeem_unavailableGame slug unknown, or this game cannot be redeemed.Use freefire, pubg, ludo, ludogold or jawaker.
tier_requiredA Yalla Ludo job had no pack, or a pack of the other Yalla store.Send tier as a quantity or Diamonds USD price; Gold by quantity with game=ludogold.
interrupted:process_restartThe job was cut by a server restart. It is never retried automatically, because a card may already have been credited.Check /v1/history for those codes before resending.
anything elseAn unexpected error. Match it last rather than switching on it.Check /v1/history for the codes before resending, then contact support with the job_id.

Per-code err_code (job done)

Each row of result.results[] carries success and, on failure, an err_code.

err_codesuccessMeaningRecommended handling
nulltrueDiamonds credited. The row carries display_id, amount, bonus, total.Show the receipt; keep display_id as the order number.
CODE_ALREADY_USEDfalseThe card was already redeemed — by you earlier, or by whoever had it before.Retire the code. Never retry; it will never succeed.
INVALID_CODEfalseThe shop does not recognise the card (wrong or expired).Retire the code; verify how it was typed.
REGION_MISMATCHfalseThe card belongs to another region than the player.Use it for a player in the matching region.
UNSUPPORTED_REGIONfalseThis player's country cannot be served (for Free Fire: a country where Garena sells no vouchers). Every row of the batch carries it, and it is permanent for this player.Stop retrying this player. The cards are untouched; use them for someone else.
ACCOUNT_RESTRICTEDfalseYalla Ludo refuses top-ups to this account (an official or restricted account). Every row of the batch carries it, no card is sent, and it is permanent for this player.Stop retrying this player. The cards are untouched; use them for someone else.
PLAYER_BANNEDfalseThis PUBG Mobile account is restricted (banned) in the game. UC cannot be sent to this Player ID. Every row carries it, and no card is sent. The row's message says the same.Stop retrying this player. The cards are untouched; use them for someone else, or ask the player to contact PUBG Mobile support.
PLAYER_RISK_LIMITEDfalseThis Player ID has to be redeemed manually. Every row carries it, and no card is sent. The row's message is Please redeem this Player ID manually.Redeem this player manually. The cards are untouched.
PLAYER_NOT_FOUNDfalseThe shop has no account with this player id. Every card in the batch carries it, because the id is what failed, not any card.Run lookup before redeeming. The cards are untouched and can be resent to a correct id.
RATE_LIMITEDfalseThe shop throttled this attempt.Retry the same code later with backoff.
VERIFICATION · VERIFICATION_FAILEDfalseThe shop asked for a verification that did not pass.Retry later; the card was not spent. Refunded.
SHOP_BLOCKEDfalseThe shop temporarily refused the request.Retry later; contact support if it persists. Refunded.
NETWORK · SESSION_EXPIREDfalseA connection problem before a result was known.Retry the same code; check history first if you want certainty. Refunded.
SHOP_MAINTENANCEfalseYalla's own site has this code type under maintenance (seen on Yalla Ludo 16-character codes) — on Yalla's side, not ours. The card was refused before it was looked at and is not spent.Keep the card and retry later. Refunded.
REDEEM_FAILEDfalseThe shop refused for a reason with no specific mapping.Show the neutral message, retry once, then escalate.
In stock-redeem, a card that failed for a reason that is not the card's fault is returned to your stock. Used and invalid cards are marked failed so they are never picked again.

Example — done, with one card refused

{ "id": "67ff1a2b3c4d5e6f70819200", "type": "instant_redeem", "status": "done", "error": null, "result": { "game": "freefire", "player_id": "123456789", "success": false, "ok_count": 1, "failed_count": 1, "credited": 110, "point_name": "Diamonds", "nickname": "ZadTopPlayer", "history_id": "67ff1a2b3c4d5e6f70819270", "results": [ { "ok": true, "success": true, "code": "4233939008625064", "player_id": "123456789", "nickname": "ZadTopPlayer", "display_id": "FF2409091234567", "amount": 100, "bonus": 10, "total": 110, "point_name": "Diamonds", "currency": "USD", "price": 0.99, "receipt_time": "2026-09-12 13:31:04", "err_code": null, "outcome": "ok" }, { "ok": false, "success": false, "code": "4233939008625065", "player_id": "123456789", "err_code": "CODE_ALREADY_USED", "outcome": "used_card" } ] }, "created_at_stamp": 1789123840, "started_at_stamp": 1789123841, "finished_at_stamp": 1789123864 }

Example — failed on quota

{ "id": "67ff1a2b3c4d5e6f70819202", "type": "stock_redeem", "status": "failed", "result": null, "error": "quota_exhausted:quota_exhausted" }

GET /health

Liveness probe for load balancers and uptime monitors. No authentication, no quota, no shop contact.

Response200 · {"ok": true}
Use caseUptime checks, TLS verification, deployment smoke test.
HTTP/1.1 200 OK Content-Type: application/json {"ok": true}

GET /v1/me

The account behind the key: wallet balance, the plan in force, today's usage, and whether HTTP access is active. Free to call — a good startup check for a dashboard.

Querynone
Quotafree
subscription.plans[]Each active plan with its games (a list, or "all"), its daily_limit and ends_at (Unix seconds).
has_api_subscriptionfalse means the add-on lapsed; paid routes answer 403 within a few seconds.
api_access"full", or "check_code" for a key that may only check codes.
check_code_subscriptionThe Code checking budget — codes_left, codes_total, ends_at_stamp — or null.
{ "chat_id": 123456789, "balance_usdt": 42.5, "subscription": { "plan_key": "p2", "daily_limit": 200, "usage_today": 17, "trial_remaining": 0, "plans": [ { "plan_key": "p2", "games": ["freefire", "pubg"], "daily_limit": 200, "ends_at": 1791715864 } ] }, "has_api_subscription": true, "api_access": "full", "check_code_subscription": { "codes_left": 149200, "codes_total": 150000, "ends_at_stamp": 1791715864 } }
GET /v1/me
curl -sS "${BASE}/v1/me" -H "X-API-Key: pk_YOUR_KEY_HERE"
print(requests.get(f"{BASE}/v1/me", headers=HEAD, timeout=30).json())
console.log(await (await fetch(`${BASE}/v1/me`, { headers: HEAD })).json());
<?php
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: pk_YOUR_KEY_HERE\r\n"]]);
echo file_get_contents("__ORIGIN__/v1/me", false, $ctx);
req, _ := http.NewRequest("GET", BASE+"/v1/me", nil)
req.Header.Set("X-API-Key", apiKey)

GET /v1/quota

What you can still spend today. Call it before a large batch so you do not queue jobs that will fail on quota.

Querygame optional — freefire, pubg, ludo, ludogold or jawaker. With it, only the plans that cover that game are counted.
trial_remainingFree-trial requests left (spent first, any game).
daily_limit_combinedSum of the daily allowances of all active plans.
usage_todaySpent since the last UTC midnight.
daily_left_subscriptionWhat your plans still allow today.
api_trial_remainingAPI trial requests granted by support, if any.
total_requests_left_approxThe practical number to budget against.
check_code_subscriptionThe Code checking budget for card reads, or null. Not part of the total above: it pays for checks only.
{ "trial_remaining": 0, "daily_limit_combined": 200, "usage_today": 17, "daily_left_subscription": 183, "api_trial_remaining": 0, "total_requests_left_approx": 183, "check_code_subscription": null }

GET /v1/history

Redeem history, one row per code, newest first — and it covers everything the account did, whether the redeem came from this API or from inside Telegram. This is the audit trail to reconcile against your own orders, and the place to look before resending a code you are unsure about.

Querylimit 1–100 (default 20) · offset ≥ 0 · player_id substring · code substring · days 7, 30 or 90 (omit for all time)
Filtersplayer_id and code match on substrings, so the last four digits of a card are enough. They combine with days using AND.
Pagingtotal is the count after filtering — page with offset += limit.
statusok or failed. outcome carries the finer reason (used_card, invalid_card, network, …).
history_idThe batch this row belongs to — pass it to order/screenshot to draw the receipt.
Quotafree
GET /v1/history?player_id=123456789&code=5064&days=30&limit=50&offset=0 { "items": [ { "id": "67ff1a2b3c4d5e6f70819277", "history_id": "67ff1a2b3c4d5e6f70819270", "player_id": "123456789", "nickname": "ZadTopPlayer", "game": "freefire", "code": "4233939008625064", "status": "ok", "outcome": "ok", "amount": 100, "bonus": 10, "total": 110, "display_id": "FF2409091234567", "source": "api", "point_name": "Diamonds", "time_created": "2026-09-12 10:31:04", "time_stamp": 1789123864 } ], "limit": 50, "offset": 0, "total": 1, "filters": { "player_id": "123456789", "code": "5064", "days": 30 } }
Page through the last 30 days for one player
curl -sS "${BASE}/v1/history?player_id=123456789&days=30&limit=100&offset=0" \
  -H "X-API-Key: pk_YOUR_KEY_HERE"
offset, rows = 0, []
while True:
    page = requests.get(
        f"{BASE}/v1/history",
        headers=HEAD,
        params={"player_id": "123456789", "days": 30, "limit": 100, "offset": offset},
        timeout=30,
    ).json()
    rows += page["items"]
    offset += page["limit"]
    if offset >= page["total"]:
        break
print(len(rows), "codes")
const q = new URLSearchParams({ player_id: "123456789", days: "30", limit: "100", offset: "0" });
const page = await (await fetch(`${BASE}/v1/history?${q}`, { headers: HEAD })).json();
console.log(page.total, page.items.length);
<?php
$q = http_build_query(["player_id" => "123456789", "days" => 30, "limit" => 100]);
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: pk_YOUR_KEY_HERE\r\n"]]);
echo file_get_contents("__ORIGIN__/v1/history?$q", false, $ctx);
req, _ := http.NewRequest("GET", BASE+"/v1/history?player_id=123456789&days=30&limit=100", nil)
req.Header.Set("X-API-Key", apiKey)

GET /v1/players

Every player this account has looked up or redeemed to, newest first — a ready-made customer list for a shop front end. Written by both the bot and the API, so a nickname resolved in Telegram is available here too.

Querylimit 1–200 (default 50)
OrderMost recently seen first (last_seen_stamp).
Quotafree — cache this instead of repeating a paid lookup for a known player.
{ "items": [ { "player_id": "123456789", "nickname": "ZadTopPlayer", "game": "freefire", "region": "ME", "last_seen_stamp": 1789123864 } ] }

GET /v1/player/lookup

Resolves a player_id to the in-game nickname — Free Fire, PUBG Mobile, Yalla Ludo or Jawaker. Show it on the checkout screen so the buyer confirms the id before a card is spent.

Queryplayer_id required · game freefire (default), pubg, ludo, ludogold or jawaker.
Quota0.25 requests for 200, 404 or 422. Free on 400 and 502.
Side effectThe player is stored and appears in /v1/players and in the bot.
Errors400 INVALID_PLAYER_ID · 400 UNKNOWN_GAME · 404 PLAYER_NOT_FOUND · 422 UNSUPPORTED_REGION · 422 ACCOUNT_RESTRICTED · 422 PLAYER_BANNED · 422 PLAYER_RISK_LIMITED · 403 GAME_NOT_IN_PLAN · 429 RATE_LIMIT · 429 QUOTA_EXHAUSTED · 502 LOOKUP_FAILED

Success — HTTP 200

{ "ok": true, "player_id": "123456789", "player_name": "ZadTopPlayer", "region": "ME", "quota_requests_charged": 0.25 }

Unknown player — HTTP 404

No account has this id. Charged 0.25 like any other answer.

{ "detail": { "error": "PLAYER_NOT_FOUND", "message": "The shop has no account with this player ID.", "quota_requests_charged": 0.25 } }

A country where Garena sells no vouchers — HTTP 422

The account exists, but its country cannot be served. Tell the buyer before taking the order — this will not change for that account.

{ "detail": { "error": "UNSUPPORTED_REGION", "message": "Garena does not sell vouchers in this player's country.", "player_id": "2185663214", "player_name": "ZadTopPlayer", "region": "US", "quota_requests_charged": 0.25 } }
GET /v1/player/lookup?player_id=…
curl -sS "${BASE}/v1/player/lookup?player_id=123456789&game=freefire" \
  -H "X-API-Key: pk_YOUR_KEY_HERE"
r = requests.get(
    f"{BASE}/v1/player/lookup",
    headers=HEAD,
    params={"player_id": "123456789", "game": "freefire"},
    timeout=60,
)
if r.status_code == 200:
    print("nickname:", r.json()["player_name"])
elif r.status_code == 404:
    print("no such player")
else:
    print("lookup unavailable:", r.status_code, r.text)
const r = await fetch(`${BASE}/v1/player/lookup?player_id=123456789`, { headers: HEAD });
if (r.ok) console.log((await r.json()).player_name);
else console.log("lookup failed", r.status, await r.text());
<?php
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: pk_YOUR_KEY_HERE\r\n", "ignore_errors" => true]]);
echo file_get_contents("__ORIGIN__/v1/player/lookup?player_id=123456789", false, $ctx);
req, _ := http.NewRequest("GET", BASE+"/v1/player/lookup?player_id=123456789", nil)
req.Header.Set("X-API-Key", apiKey)
resp, err := http.DefaultClient.Do(req)

POST /v1/codes/check

Reads whether each card is unused, already used, or was never real — without redeeming anything. A valid card stays valid however often it is checked. Available for Free Fire and PUBG Mobile.

Bodycodes 1–20 · game freefire, pubg, ludo (Diamonds codes only — never Gold), itunes or razer · with_value true to get each card's value too (Ludo and Razer carry none; iTunes always returns its balance in value_label). razer costs 5 requests per PIN. Ludo Gold and Jawaker have no check (GAME_REDEEM_UNAVAILABLE).
Quota1 request per card that got a verdict. unknown, error and maintenance are free. A Code checking subscription pays first (check_code_charged), and on its own is enough to call this route.
Larger batchesUp to 10,000 cards through POST /v1/jobs/code-check, which is polled like a redeem job.
Side effectnone. Nothing is redeemed, no card is consumed, no stock row changes.
Errors400 INVALID_CODE · 400 TOO_MANY_CODES · 403 GAME_NOT_IN_PLAN · 429 RATE_LIMIT · 429 QUOTA_EXHAUSTED (nothing is read) · 503 SERVICE_DRAINING

What each status means

statusMeaningredeemable
validThe card exists and has not been used.true
usedAlready redeemed, by anyone.false
invalidNo such card — a typo or an invention.false
expired · inactive · blockedThe shop's own refusals for a card that exists but cannot be used.false
region_mismatchThe card belongs to another region.false
unknown · errorWe could not find out. Treat as not yet known, not as bad, and check again later. Free.false
maintenanceYalla's own site has this code type under maintenance (error: "error_maintenance"), so it would not read the card. The card is untouched — check again later. Free.false
A value is not a status. amount (the pack the card credits) is returned for used cards too, so a value coming back never means the card is live. Always read status.

Extra fields (PUBG Mobile)

value_labelThe card's value as text, e.g. "660 UC".
used_atWhen a used card was redeemed (Unix seconds).
used_by_name · used_by_idThe player a used card went to, when the shop tells.
expires_atExpiry of a valid or expired card (Unix seconds), when known.

Fields are present only when they have a value.

Success — HTTP 200

{ "ok": true, "checked": 3, "counts": { "valid": 1, "used": 1, "invalid": 1 }, "quota_requests_charged": 3, "check_code_charged": 0, "results": [ { "code": "7397062240255931", "status": "valid", "redeemable": true, "error": null, "shell_amount": 50, "amount": 100, "bonus": 0 }, { "code": "5539151276341494", "status": "used", "redeemable": false, "error": "error_used_card", "shell_amount": 50, "amount": 100, "bonus": 0 }, { "code": "0000000000000000", "status": "invalid", "redeemable": false, "error": "error_invalid_card", "shell_amount": null, "amount": null, "bonus": null } ] }
POST /v1/codes/check
curl -sS -X POST "${BASE}/v1/codes/check" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"codes":["7397062240255931","5539151276341494"],"game":"freefire"}'
r = requests.post(
    f"{BASE}/v1/codes/check",
    headers=HEAD,
    json={"codes": ["7397062240255931", "5539151276341494"]},
    timeout=60,
)
for row in r.json()["results"]:
    print(row["code"], row["status"], "-> redeem" if row["redeemable"] else "-> skip")
const r = await fetch(`${BASE}/v1/codes/check`, {
  method: "POST",
  headers: { ...HEAD, "Content-Type": "application/json" },
  body: JSON.stringify({ codes: ["7397062240255931", "5539151276341494"] }),
});
const { results } = await r.json();
const good = results.filter((x) => x.redeemable).map((x) => x.code);
<?php
$body = json_encode(["codes" => ["7397062240255931", "5539151276341494"]]);
$ctx = stream_context_create(["http" => ["method" => "POST", "content" => $body,
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n", "ignore_errors" => true]]);
echo file_get_contents("__ORIGIN__/v1/codes/check", false, $ctx);
body := []byte(`{"codes":["7397062240255931","5539151276341494"]}`)
req, _ := http.NewRequest("POST", BASE+"/v1/codes/check", bytes.NewReader(body))
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

GET /v1/stock/summary

How many vouchers the account holds, per pack. Only available cards are counted — reserved, used and failed ones are left out — so this is exactly what stock-redeem can draw from right now.

Querynone
ShapeOne object per game slug, each with name, redeemable, by_denomination (pack size → count) and total.
GamesOne object per slug the account can hold: freefire, pubg, ludo, ludogold, jawaker. All five are redeemable: true.
Quotafree
{ "freefire": { "name": "Free Fire", "redeemable": true, "by_denomination": { "100": 12, "210": 4, "530": 0, "1080": 2, "2200": 0 }, "total": 18 }, "ludo": { "name": "Yalla Ludo Diamonds", "redeemable": true, "by_denomination": { "830": 5, "2320": 0, "5150": 0, "13580": 0, "27640": 0, "55800": 0, "168860": 0, "283460": 0 }, "total": 5 }, "ludogold": { "name": "Yalla Ludo Gold", "redeemable": true, "by_denomination": { "68500": 2, "223700": 0, "1463320": 0, "3666470": 0, "9973990": 0, "25236460": 0, "76000860": 0, "126910990": 0 }, "total": 2 }, "pubg": { "name": "PUBG Mobile", "redeemable": true, "by_denomination": { "60": 8, "325": 1, "660": 0, "1800": 0, "3850": 0, "8100": 0 }, "total": 9 }, "jawaker": { "name": "Jawaker", "redeemable": true, "by_denomination": { "4250": 6, "32500": 1, "70000": 0, "150000": 0, "230000": 0, "400000": 0, "525000": 0, "805000": 0, "825000": 0 }, "total": 7 } }

Asynchronous jobs

A redeem takes a few seconds, so it runs in a queue. POST checks the payload and returns a job_id at once; the result and the history rows are written when the job ends.

CreatePOST /v1/jobs/instant-redeem · POST /v1/jobs/stock-redeem · POST /v1/jobs/code-check
ReadGET /v1/jobs/{job_id} (optionally ?wait=) · GET /v1/jobs
Billing momentWhen the job runs — a queued job that never runs costs nothing.
OrderingOldest job first, up to 4 at a time per account.
Typical timeA single code usually settles in a few seconds; a batch takes longer in proportion.
Interrupted jobsA job cut by a server restart ends as failed with interrupted:process_restart and is never retried automatically — check history before resending those codes.

Immediate response after POST

{ "job_id": "67ff1a2b3c4d5e6f70819200", "status": "pending" }

Still working

{ "id": "67ff1a2b3c4d5e6f70819200", "type": "instant_redeem", "status": "running", "result": null, "error": null, "created_at_stamp": 1789123840, "started_at_stamp": 1789123841, "finished_at_stamp": null }

Wait for the result instead of polling

Long-poll pattern with a hard deadline
for i in $(seq 1 6); do
  OUT=$(curl -sS "${BASE}/v1/jobs/$JOB?wait=25" -H "X-API-Key: pk_YOUR_KEY_HERE")
  echo "$OUT" | grep -q '"status":"\(done\|failed\)"' && { echo "$OUT"; break; }
done
import time
import requests

def wait_job(base, head, job_id, deadline_sec=180):
    end = time.time() + deadline_sec
    while time.time() < end:
        doc = requests.get(f"{base}/v1/jobs/{job_id}?wait=25", headers=head, timeout=40).json()
        if doc.get("status") in ("done", "failed"):
            return doc
    raise TimeoutError(job_id)

doc = wait_job(BASE, HEAD, "67ff1a2b3c4d5e6f70819200")
res = doc.get("result") or {}
print(doc["status"], res.get("ok_count"), res.get("failed_count"))
async function waitJob(jobId, deadlineMs = 180000) {
  const end = Date.now() + deadlineMs;
  while (Date.now() < end) {
    const doc = await (await fetch(`${BASE}/v1/jobs/${jobId}?wait=25`, { headers: HEAD })).json();
    if (doc.status === "done" || doc.status === "failed") return doc;
  }
  throw new Error("timeout " + jobId);
}
<?php
function wait_job($base, $key, $jobId, $deadline = 180) {
  $end = time() + $deadline;
  $ctx = stream_context_create(["http" => ["header" => "X-API-Key: $key\r\n"]]);
  while (time() < $end) {
    $doc = json_decode(file_get_contents("$base/v1/jobs/$jobId?wait=25", false, $ctx), true);
    if (in_array($doc["status"], ["done", "failed"], true)) return $doc;
  }
  throw new RuntimeException("timeout");
}
for deadline := time.Now().Add(3 * time.Minute); time.Now().Before(deadline); {
    req, _ := http.NewRequest("GET", BASE+"/v1/jobs/"+jobID+"?wait=25", nil)
    req.Header.Set("X-API-Key", apiKey)
    resp, err := http.DefaultClient.Do(req)
    if err != nil { continue }
    // decode; break when status is done or failed
    resp.Body.Close()
}

Many orders at once

Do not put unrelated customers in one job: a job is one player_id. Post one job per order and poll them in parallel. Four of your jobs run at a time and the rest queue, so a burst of fifty orders is accepted immediately and drains in order. Keep the job_id next to your own order id, and reconcile later through /v1/history.

POST /v1/jobs/instant-redeem

Redeems the codes you send in the request onto one player. This is the route a shop uses when the customer (or your own supplier file) provides the card.

Bodyplayer_id · codes 1–10 · game freefire | pubg | ludo | ludogold | jawaker · tier required for Yalla Ludo (quantity or Diamonds USD price).
Quota1 request per code, charged when the job runs.
Errors at POST400 INVALID_PLAYER_ID / INVALID_CODE / UNKNOWN_GAME / MISSING_TIER / GAME_REDEEM_UNAVAILABLE · 403 GAME_NOT_IN_PLAN · 422 schema · 503 SERVICE_DRAINING
Resultok_count, failed_count, credited, nickname, history_id, and one results[] row per code in the order you sent them.
A valid card is credited on the first attempt, so send a code here only when you intend to spend it. Use /v1/codes/check when you only want to know what a card is. Use err_code to decide whether a failure may be retried (network, verification, rate limit → retry; used, invalid, region → retire).

Request — one card

{ "player_id": "123456789", "codes": ["4233939008625064"], "game": "freefire" }

Request — three cards for the same player in one job

{ "player_id": "123456789", "codes": ["4233939008625064", "4233939008625065", "4233939008625066"], "game": "freefire" }
POST /v1/jobs/instant-redeem
curl -sS -X POST "${BASE}/v1/jobs/instant-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"123456789","codes":["4233939008625064"],"game":"freefire"}'
job = requests.post(
    f"{BASE}/v1/jobs/instant-redeem",
    headers=HEAD,
    json={"player_id": "123456789", "codes": ["4233939008625064"], "game": "freefire"},
    timeout=30,
).json()
print(job["job_id"], job["status"])
const job = await (await fetch(`${BASE}/v1/jobs/instant-redeem`, {
  method: "POST",
  headers: HEAD,
  body: JSON.stringify({ player_id: "123456789", codes: ["4233939008625064"], game: "freefire" }),
})).json();
<?php
$body = json_encode(["player_id" => "123456789", "codes" => ["4233939008625064"], "game" => "freefire"]);
$ctx = stream_context_create(["http" => [
  "method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n",
  "content" => $body,
]]);
echo file_get_contents("__ORIGIN__/v1/jobs/instant-redeem", false, $ctx);
payload := strings.NewReader(`{"player_id":"123456789","codes":["4233939008625064"],"game":"freefire"}`)
req, _ := http.NewRequest("POST", BASE+"/v1/jobs/instant-redeem", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

POST /v1/jobs/stock-redeem

Redeems cards from your own stored stock, chosen by pack size. This is the route for selling a package ("1 080 diamonds") without your front end ever handling voucher codes.

Bodyplayer_id · picks object mapping pack size → how many cards · game freefire | pubg | ludo | ludogold | jawaker. Pack keys are that game's packs — see Games.
StockTwo jobs never take the same card. If your stock holds none of the requested packs, the job fails with no_codes.
Quota1 request per card taken from your stock.
Failed cardsA card refused for a temporary reason returns to stock; a used or invalid card is marked failed and never picked again.
Errors at POST400 INVALID_PLAYER_ID / MISSING_PICKS / GAME_REDEEM_UNAVAILABLE · 403 GAME_NOT_IN_PLAN · 503 SERVICE_DRAINING

Request — two small packs and one big one

{ "player_id": "123456789", "picks": { "100": 2, "1080": 1 }, "game": "freefire" }

Result — three cards, one refused

{ "status": "done", "type": "stock_redeem", "result": { "game": "freefire", "player_id": "123456789", "success": false, "ok_count": 2, "failed_count": 1, "credited": 1298, "point_name": "Diamonds", "history_id": "67ff1a2b3c4d5e6f70819271", "results": [ { "success": true, "code": "4233939008625064", "total": 110, "display_id": "FF2409091234567" }, { "success": true, "code": "4233939008625067", "total": 1188, "display_id": "FF2409091234570" }, { "success": false, "code": "4233939008625068", "err_code": "NETWORK", "outcome": "network" } ] } }

The NETWORK card above is back in stock — check /v1/stock/summary and retry the sale.

POST /v1/jobs/stock-redeem
curl -sS -X POST "${BASE}/v1/jobs/stock-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"123456789","picks":{"100":2,"1080":1},"game":"freefire"}'
job = requests.post(
    f"{BASE}/v1/jobs/stock-redeem",
    headers=HEAD,
    json={"player_id": "123456789", "picks": {"100": 2, "1080": 1}, "game": "freefire"},
    timeout=30,
).json()
const job = await (await fetch(`${BASE}/v1/jobs/stock-redeem`, {
  method: "POST",
  headers: HEAD,
  body: JSON.stringify({ player_id: "123456789", picks: { "100": 2, "1080": 1 }, game: "freefire" }),
})).json();
<?php
$body = json_encode(["player_id" => "123456789", "picks" => ["100" => 2, "1080" => 1], "game" => "freefire"]);
$ctx = stream_context_create(["http" => [
  "method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n",
  "content" => $body,
]]);
echo file_get_contents("__ORIGIN__/v1/jobs/stock-redeem", false, $ctx);
payload := strings.NewReader(`{"player_id":"123456789","picks":{"100":2,"1080":1},"game":"freefire"}`)
req, _ := http.NewRequest("POST", BASE+"/v1/jobs/stock-redeem", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

POST /v1/jobs/code-check

The batch form of /v1/codes/check: up to 10,000 cards in one job. Nothing is redeemed and no card is consumed. This is the route for auditing a supplier file or your own stock.

Bodycodes 1–10,000 · game freefire, pubg, ludo (Diamonds codes only — never Gold), itunes or razer · with_value default false. razer costs 5 requests per PIN. Ludo Gold and Jawaker have no check.
DuplicatesA code appears once in the result however often you sent it.
Quota1 request per card that got a verdict, charged when the job runs. A Code checking subscription pays first, and on its own is enough to queue this job.
with_valueOff by default here because it makes the batch slower. A batch may mix packs.
Telegram alertNone — nothing was redeemed.
Errors at POST400 INVALID_CODE / TOO_MANY_CODES / GAME_REDEEM_UNAVAILABLE · 403 GAME_NOT_IN_PLAN · 429 QUOTA_EXHAUSTED (the allowance does not cover every card; nothing is read) · 503 SERVICE_DRAINING

Result — read it back with GET /v1/jobs/{job_id}?wait=25

{ "id": "67ff1a2b3c4d5e6f70819202", "type": "code_check", "status": "done", "result": { "game": "freefire", "checked": 3, "counts": { "valid": 2, "used": 1 }, "quota_requests_charged": 0, "check_code_charged": 3, "results": [ { "code": "7397062240255931", "status": "valid", "redeemable": true, "error": null }, { "code": "0305768925042495", "status": "valid", "redeemable": true, "error": null }, { "code": "5539151276341494", "status": "used", "redeemable": false, "error": "error_used_card" } ] } }
POST /v1/jobs/code-check
curl -sS -X POST "${BASE}/v1/jobs/code-check" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"codes":["7397062240255931","0305768925042495","5539151276341494"]}'
job = requests.post(
    f"{BASE}/v1/jobs/code-check", headers=HEAD, json={"codes": batch}, timeout=30
).json()
done = requests.get(f"{BASE}/v1/jobs/{job['job_id']}?wait=25", headers=HEAD, timeout=40).json()
unused = [r["code"] for r in done["result"]["results"] if r["redeemable"]]
const { job_id } = await (await fetch(`${BASE}/v1/jobs/code-check`, {
  method: "POST",
  headers: { ...HEAD, "Content-Type": "application/json" },
  body: JSON.stringify({ codes: batch }),
})).json();
const done = await (await fetch(`${BASE}/v1/jobs/${job_id}?wait=25`, { headers: HEAD })).json();
<?php
$body = json_encode(["codes" => $batch]);
$ctx = stream_context_create(["http" => ["method" => "POST", "content" => $body,
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n", "ignore_errors" => true]]);
echo file_get_contents("__ORIGIN__/v1/jobs/code-check", false, $ctx);
payload := strings.NewReader(`{"codes":["7397062240255931","5539151276341494"]}`)
req, _ := http.NewRequest("POST", BASE+"/v1/jobs/code-check", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

GET /v1/jobs/{job_id}

Reads one job you own. With ?wait= the server holds the connection until the job reaches a terminal state, which is both faster and cheaper than a polling loop.

Pathjob_id — the id returned by a create call.
Querywait seconds, 0–60 (default 0 = answer immediately).
Terminal statesdone (finished — read the rows) · failed (read error).
Errors404 unknown id, or an id owned by another account.
Quotafree — poll as much as the rate limit allows.

A full done example with a mixed batch is in the response catalog.

GET /v1/jobs

Your recent jobs, newest first — useful to rebuild state after your own process restarted and lost the ids.

Querylimit 1–100 (default 20) · offset ≥ 0
Responsejobs[] in the same sanitised shape as the single-job route, plus limit, offset, total.
Quotafree
{ "jobs": [ { "id": "67ff1a2b3c4d5e6f70819200", "type": "instant_redeem", "status": "done", "error": null, "created_at_stamp": 1789123840, "finished_at_stamp": 1789123864 } ], "limit": 20, "offset": 0, "total": 1 }

POST /v1/order/screenshot

Returns the same order receipt the bot sends, for the game the card was redeemed in — the order number, the credited amount and the time. The response body is raw PNG bytes, not JSON. Hand it to the customer as proof of delivery.

BodyExactly one of job_id (an API job you own) or history_id (any redeem of yours, including from Telegram) · result_index integer ≥ 0 (default 0) · lang "en" or "ar"
result_indexWith history_id it indexes the successful rows of that batch. With job_id it indexes result.results[] as returned, and a failed row is rejected.
Per gameFree Fire: the shop's order card · PUBG Mobile: the shop's ORDER DETAILS card · Yalla Ludo: the Yalla Pay result page (Arabic) · Jawaker: the confirmation with the login and token amount.
Success200 · Content-Type: image/png · binary body.
Errors400 MISSING_JOB_OR_HISTORY_ID / NO_ORDER_DETAILS / JOB_NOT_SUCCESSFUL · 404 JOB_NOT_FOUND / HISTORY_NOT_FOUND · 409 JOB_NOT_READY · 429 SCREENSHOT_RATE_LIMIT · 500 ORDER_SCREENSHOT_FAILED
Time zoneThe time on the card follows the zone chosen in the bot (My account → Time zone). Accounts that never picked one get the shop's own region.
Quotafree, but capped at 15 renders per minute per key.
POST /v1/order/screenshot → receipt.png
curl -sS -X POST "${BASE}/v1/order/screenshot" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: image/png" \
  -d '{"history_id":"67ff1a2b3c4d5e6f70819270","result_index":0,"lang":"en"}' \
  -o receipt.png
import pathlib
import requests

r = requests.post(
    f"{BASE}/v1/order/screenshot",
    headers={"X-API-Key": "pk_YOUR_KEY_HERE", "Accept": "image/png"},
    json={"history_id": "67ff1a2b3c4d5e6f70819270", "result_index": 0, "lang": "en"},
    timeout=60,
)
if r.status_code == 200 and r.headers.get("Content-Type", "").startswith("image/png"):
    pathlib.Path("receipt.png").write_bytes(r.content)
    print("saved", len(r.content), "bytes")
else:
    print(r.status_code, r.text)
const r = await fetch(`${BASE}/v1/order/screenshot`, {
  method: "POST",
  headers: { ...HEAD, Accept: "image/png" },
  body: JSON.stringify({ history_id: "67ff1a2b3c4d5e6f70819270", lang: "en" }),
});
if (!r.ok) console.log(r.status, await r.text());
else console.log("png bytes", (await r.arrayBuffer()).byteLength);
<?php
$body = json_encode(["history_id" => "67ff1a2b3c4d5e6f70819270", "lang" => "en"]);
$ctx = stream_context_create(["http" => [
  "method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\nAccept: image/png\r\n",
  "content" => $body,
]]);
file_put_contents("receipt.png", file_get_contents("__ORIGIN__/v1/order/screenshot", false, $ctx));
payload := strings.NewReader(`{"history_id":"67ff1a2b3c4d5e6f70819270","lang":"en"}`)
req, _ := http.NewRequest("POST", BASE+"/v1/order/screenshot", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "image/png")
resp, err := http.DefaultClient.Do(req)
// defer resp.Body.Close(); io.Copy(outFile, resp.Body)

Only successful redeem rows have a receipt. A failed card has no order number, so it answers 400 NO_ORDER_DETAILS.

POST /v1/subscription/purchase · purchase-api-addon

Buy from the wallet balance without opening Telegram — handy for automation that watches its own allowance.

/v1/subscription/purchaseBody {"plan_key":"p2","games":["freefire","pubg"]}. Adds the plan's daily requests for 30 days, shared by the games picked.
gamesfreefire, pubg, ludo (Diamonds and Gold), jawaker, or ["all"]. Omitted = all games. All games includes games added in the future.
PriceOne game is the plan's price, two games ×1.3, three or more (all games) ×1.5 — see Plans. A discount from support is applied automatically.
RenewingBuying a plan you already hold for the same games extends it by 30 days.
/v1/subscription/purchase-api-addonNo body. Adds 30 days of HTTP access, a fixed 15 USDT, on top of an active plan.
Adding gamesDone in the bot: Subscription → Add games to my plan, paying only the difference for the days left.
Errors400 INSUFFICIENT_BALANCE · PRICE_CHANGED · NEED_PLAN (add-on without a plan) · UNKNOWN_GAME · UNKNOWN_PLAN.
Response{"ok": true, "result": { … }} with the resulting plan, the price paid and the expiry.
POST /v1/subscription/purchase
curl -sS -X POST "${BASE}/v1/subscription/purchase" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"plan_key":"p2","games":["freefire","pubg"]}'

curl -sS -X POST "${BASE}/v1/subscription/purchase-api-addon" \
  -H "X-API-Key: pk_YOUR_KEY_HERE"
print(requests.post(f"{BASE}/v1/subscription/purchase", headers=HEAD,
                    json={"plan_key": "p2", "games": ["freefire", "pubg"]}, timeout=30).json())
print(requests.post(f"{BASE}/v1/subscription/purchase-api-addon", headers=HEAD, timeout=30).json())
await fetch(`${BASE}/v1/subscription/purchase`, {
  method: "POST",
  headers: HEAD,
  body: JSON.stringify({ plan_key: "p2", games: ["freefire", "pubg"] }),
});
<?php
$ctx = stream_context_create(["http" => [
  "method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n",
  "content" => json_encode(["plan_key" => "p2", "games" => ["freefire", "pubg"]]),
]]);
echo file_get_contents("__ORIGIN__/v1/subscription/purchase", false, $ctx);
payload := strings.NewReader(`{"plan_key":"p2","games":["freefire","pubg"]}`)
req, _ := http.NewRequest("POST", BASE+"/v1/subscription/purchase", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

POST /v1/subscription/purchase-check-code

Buys the Code checking subscription from the wallet balance. Works with full access, or with a check-only key to renew it.

Body{"plan_key":"cc1"} — cc1 = 150 000 card reads for 100 USDT, cc2 = 250 000 for 150 USDT, 30 days.
Buying againWhile one is running, the new codes are added to what is left and the 30 days restart from now. mode is new or added.
Responseresult.codes_left is the whole budget after the purchase; ends_at_stamp / ends_at its new end.
Errors400 INSUFFICIENT_BALANCE · 422 a plan_key other than cc1 / cc2.
{ "ok": true, "result": { "plan_key": "cc1", "price": 100.0, "balance": 20.0, "mode": "new", "ends_at_stamp": 1791715864, "ends_at": "2026-10-11", "codes_left": 150000 } }
POST /v1/subscription/purchase-check-code
curl -sS -X POST "${BASE}/v1/subscription/purchase-check-code" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"plan_key":"cc1"}'
print(requests.post(f"{BASE}/v1/subscription/purchase-check-code", headers=HEAD,
                    json={"plan_key": "cc1"}, timeout=30).json())
await fetch(`${BASE}/v1/subscription/purchase-check-code`, {
  method: "POST",
  headers: { ...HEAD, "Content-Type": "application/json" },
  body: JSON.stringify({ plan_key: "cc1" }),
});
<?php
$ctx = stream_context_create(["http" => [
  "method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n",
  "content" => json_encode(["plan_key" => "cc1"]),
]]);
echo file_get_contents("__ORIGIN__/v1/subscription/purchase-check-code", false, $ctx);
payload := strings.NewReader(`{"plan_key":"cc1"}`)
req, _ := http.NewRequest("POST", BASE+"/v1/subscription/purchase-check-code", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

Games & packs

One subscription, one key, one set of routes. Set game on each call.

gameNameLookupCode checkRedeem
freefireFree Fire✅✅✅ Diamonds
pubgPUBG Mobile✅✅✅ UC
ludoYalla Ludo Diamonds✅✅ Diamonds codes only✅ Diamonds + tier
ludogoldYalla Ludo Gold✅No check✅ Gold + tier
jawakerJawaker✅No check✅ Tokens
itunesiTunes (Apple Gift Card)—✅ balance in USD— (check only)
razerRazer Gold (PIN)—✅ 5 requests per PIN— (check only)

A job is one player and one game. In plans, ludo covers both Yalla Ludo stores. itunes and razer are checked, never redeemed, and have no player id; a Razer read costs 5 requests.

Free Fire

gamefreefire
Packs100 · 210 · 530 · 1,080 · 2,200 diamonds. These are the keys of picks on stock-redeem.
CheckPOST /v1/codes/check and POST /v1/jobs/code-check.
ReceiptThe shop's order confirmation, as PNG from POST /v1/order/screenshot.
RegionAlmost every country is served. United States, Argentina, Chile and Russia: lookup answers 422 UNSUPPORTED_REGION. A card from another region is REGION_MISMATCH and is not spent.
Free Fire — lookup, check, redeem
curl -sS "${BASE}/v1/player/lookup?player_id=123456789&game=freefire" \
  -H "X-API-Key: pk_YOUR_KEY_HERE"

curl -sS -X POST "${BASE}/v1/codes/check" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"codes":["4233939008625064"],"game":"freefire","with_value":true}'

curl -sS -X POST "${BASE}/v1/jobs/instant-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"player_id":"123456789","codes":["4233939008625064"],"game":"freefire"}'
requests.get(f"{BASE}/v1/player/lookup", headers=HEAD,
             params={"player_id": "123456789", "game": "freefire"}, timeout=60)
requests.post(f"{BASE}/v1/codes/check", headers=HEAD,
              json={"codes": ["4233939008625064"], "game": "freefire", "with_value": True}, timeout=60)
requests.post(f"{BASE}/v1/jobs/instant-redeem", headers=HEAD,
              json={"player_id": "123456789", "codes": ["4233939008625064"], "game": "freefire"}, timeout=30)
await fetch(`${BASE}/v1/player/lookup?player_id=123456789&game=freefire`, { headers: HEAD });
await fetch(`${BASE}/v1/jobs/instant-redeem`, {
  method: "POST", headers: HEAD,
  body: JSON.stringify({ player_id: "123456789", codes: ["4233939008625064"], game: "freefire" }),
});
<?php
echo file_get_contents("__ORIGIN__/v1/player/lookup?player_id=123456789&game=freefire", false,
  stream_context_create(["http" => ["header" => "X-API-Key: pk_YOUR_KEY_HERE\r\n"]]));
req, _ := http.NewRequest("GET", BASE+"/v1/player/lookup?player_id=123456789&game=freefire", nil)
req.Header.Set("X-API-Key", apiKey)

PUBG Mobile

UC vouchers redeemed onto a character id: lookup, code check, instant, stock, history and the shop receipt.

gamepubg
Packs60 · 325 · 660 · 1,800 · 3,850 · 8,100 UC. These are the keys of picks.
CheckSame routes as Free Fire. A used card also returns when it was used and the player it went to — see extra fields.
ReceiptThe shop's own ORDER DETAILS card, returned as PNG from /v1/order/screenshot.
Banned accountA character banned or restricted in the game comes back as 422 PLAYER_BANNED on lookup and as PLAYER_BANNED rows on redeem. The message is: this account is restricted (banned); UC cannot be sent to this Player ID. Cards are not spent.
Do it manuallySome characters come back as 422 PLAYER_RISK_LIMITED on lookup and as PLAYER_RISK_LIMITED rows on redeem. The message is Please redeem this Player ID manually. Cards are not spent.
{ "player_id": "5123456789", "codes": ["AB12CD34EF56GH78IJ"], "game": "pubg" }
PUBG — lookup, check, redeem, stock
curl -sS "${BASE}/v1/player/lookup?player_id=5123456789&game=pubg" \
  -H "X-API-Key: pk_YOUR_KEY_HERE"

curl -sS -X POST "${BASE}/v1/codes/check" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"codes":["AB12CD34EF56GH78IJ"],"game":"pubg","with_value":true}'

curl -sS -X POST "${BASE}/v1/jobs/instant-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"player_id":"5123456789","codes":["AB12CD34EF56GH78IJ"],"game":"pubg"}'

curl -sS -X POST "${BASE}/v1/jobs/stock-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"player_id":"5123456789","picks":{"60":2,"325":1},"game":"pubg"}'
requests.get(f"{BASE}/v1/player/lookup", headers=HEAD,
             params={"player_id": "5123456789", "game": "pubg"}, timeout=60)
requests.post(f"{BASE}/v1/codes/check", headers=HEAD,
              json={"codes": ["AB12CD34EF56GH78IJ"], "game": "pubg"}, timeout=60)
requests.post(f"{BASE}/v1/jobs/instant-redeem", headers=HEAD,
              json={"player_id": "5123456789", "codes": ["AB12CD34EF56GH78IJ"], "game": "pubg"}, timeout=30)
requests.post(f"{BASE}/v1/jobs/stock-redeem", headers=HEAD,
              json={"player_id": "5123456789", "picks": {"60": 2, "325": 1}, "game": "pubg"}, timeout=30)
await fetch(`${BASE}/v1/player/lookup?player_id=5123456789&game=pubg`, { headers: HEAD });
await fetch(`${BASE}/v1/jobs/instant-redeem`, {
  method: "POST", headers: HEAD,
  body: JSON.stringify({ player_id: "5123456789", codes: ["AB12CD34EF56GH78IJ"], game: "pubg" }),
});
<?php
$body = json_encode(["player_id" => "5123456789", "codes" => ["AB12CD34EF56GH78IJ"], "game" => "pubg"]);
$ctx = stream_context_create(["http" => ["method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n", "content" => $body]]);
echo file_get_contents("__ORIGIN__/v1/jobs/instant-redeem", false, $ctx);
payload := strings.NewReader(`{"player_id":"5123456789","codes":["AB12CD34EF56GH78IJ"],"game":"pubg"}`)
req, _ := http.NewRequest("POST", BASE+"/v1/jobs/instant-redeem", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

Yalla Ludo

Two stores, Diamonds and Gold. Send the pack of the card as tier. Diamonds codes can be checked; Gold codes cannot.

gameludo (Diamonds) · ludogold (Gold)
player_idThe Yalla Ludo user id: 4 to 16 digits (older accounts have 4 or 5).
Refused accountYalla does not allow top-ups to its official and restricted accounts (its customer-service ids, for example). Lookup answers 422 ACCOUNT_RESTRICTED with the name and a message saying so; a redeem returns ACCOUNT_RESTRICTED rows and sends no card. The country Yalla shows for an account is only where it connects from — it does not limit top-ups.
Diamonds packs830 · 2,320 · 5,150 · 13,580 · 27,640 · 55,800 · 168,860 · 283,460 — USD 2 · 5 · 10 · 25 · 50 · 100 · 300 · 500
Gold packs68,500 · 223,700 · 1,463,320 · 3,666,470 · 9,973,990 · 25,236,460 · 76,000,860 · 126,910,990
tierRequired on instant-redeem. An in-game quantity (830, 68500, …) or a Diamonds USD price (2, 5, …). A USD price always means Diamonds; Gold is sent as its quantity.
Stockpicks keys are the quantities above, under the matching game. No tier field — the pack is the key.
Checkgame: "ludo" on codes/check and jobs/code-check — Diamonds codes only; the answer carries no value. Never send a Gold code there: a Gold code can be redeemed and spent. Gold has no check; in a redeem, a used or wrong card comes back as INVALID_CODE.
ReceiptThe Yalla Pay result page, as PNG (Arabic).
{ "player_id": "123456789", "codes": ["H216355GQQRB"], "game": "ludo", "tier": "2" }
{ "player_id": "123456789", "codes": ["H42LR46R1QJ8"], "game": "ludogold", "tier": "68500" }
Yalla Ludo — lookup, Diamonds $2, Gold stock
curl -sS "${BASE}/v1/player/lookup?player_id=123456789&game=ludo" \
  -H "X-API-Key: pk_YOUR_KEY_HERE"

curl -sS -X POST "${BASE}/v1/jobs/instant-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"player_id":"123456789","codes":["H216355GQQRB"],"game":"ludo","tier":"2"}'

curl -sS -X POST "${BASE}/v1/jobs/instant-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"player_id":"123456789","codes":["H42LR46R1QJ8"],"game":"ludogold","tier":"68500"}'

curl -sS -X POST "${BASE}/v1/jobs/stock-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"player_id":"123456789","picks":{"830":1},"game":"ludo"}'
requests.get(f"{BASE}/v1/player/lookup", headers=HEAD,
             params={"player_id": "123456789", "game": "ludo"}, timeout=60)
requests.post(f"{BASE}/v1/jobs/instant-redeem", headers=HEAD,
              json={"player_id": "123456789", "codes": ["H216355GQQRB"], "game": "ludo", "tier": "2"}, timeout=30)
requests.post(f"{BASE}/v1/jobs/instant-redeem", headers=HEAD,
              json={"player_id": "123456789", "codes": ["H42LR46R1QJ8"], "game": "ludogold", "tier": "68500"}, timeout=30)
requests.post(f"{BASE}/v1/jobs/stock-redeem", headers=HEAD,
              json={"player_id": "123456789", "picks": {"830": 1}, "game": "ludo"}, timeout=30)
await fetch(`${BASE}/v1/jobs/instant-redeem`, {
  method: "POST", headers: HEAD,
  body: JSON.stringify({ player_id: "123456789", codes: ["H216355GQQRB"], game: "ludo", tier: "2" }),
});
<?php
$body = json_encode(["player_id" => "123456789", "codes" => ["H216355GQQRB"],
  "game" => "ludo", "tier" => "2"]);
$ctx = stream_context_create(["http" => ["method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n", "content" => $body]]);
echo file_get_contents("__ORIGIN__/v1/jobs/instant-redeem", false, $ctx);
payload := strings.NewReader(`{"player_id":"123456789","codes":["H216355GQQRB"],"game":"ludo","tier":"2"}`)
req, _ := http.NewRequest("POST", BASE+"/v1/jobs/instant-redeem", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

Jawaker

Jawaker tokens redeemed onto a player number: lookup, instant, stock, history and the receipt. No tier is needed — the card carries its own amount. Jawaker has no code check.

gamejawaker
LookupReturns the player's login as player_name.
Packs4,250 · 32,500 · 70,000 · 150,000 · 230,000 · 400,000 · 525,000 · 805,000 · 825,000 tokens. These are the keys of picks.
CheckNo check. A used or wrong card comes back as INVALID_CODE.
NETWORK rowThe answer was lost and the card may have gone through. It is not billed — check the player's balance before you retry that card.
ReceiptJawaker's confirmation with the login and token amount, as PNG from /v1/order/screenshot.
{ "player_id": "1850890235", "codes": ["9W726P9AE7"], "game": "jawaker" }
Jawaker — lookup, redeem, stock
curl -sS "${BASE}/v1/player/lookup?player_id=1850890235&game=jawaker" \
  -H "X-API-Key: pk_YOUR_KEY_HERE"

curl -sS -X POST "${BASE}/v1/jobs/instant-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"player_id":"1850890235","codes":["9W726P9AE7"],"game":"jawaker"}'

curl -sS -X POST "${BASE}/v1/jobs/stock-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"player_id":"1850890235","picks":{"4250":2},"game":"jawaker"}'
requests.get(f"{BASE}/v1/player/lookup", headers=HEAD,
             params={"player_id": "1850890235", "game": "jawaker"}, timeout=60)
requests.post(f"{BASE}/v1/jobs/instant-redeem", headers=HEAD,
              json={"player_id": "1850890235", "codes": ["9W726P9AE7"], "game": "jawaker"}, timeout=30)
requests.post(f"{BASE}/v1/jobs/stock-redeem", headers=HEAD,
              json={"player_id": "1850890235", "picks": {"4250": 2}, "game": "jawaker"}, timeout=30)
await fetch(`${BASE}/v1/player/lookup?player_id=1850890235&game=jawaker`, { headers: HEAD });
await fetch(`${BASE}/v1/jobs/instant-redeem`, {
  method: "POST", headers: HEAD,
  body: JSON.stringify({ player_id: "1850890235", codes: ["9W726P9AE7"], game: "jawaker" }),
});
<?php
$body = json_encode(["player_id" => "1850890235", "codes" => ["9W726P9AE7"], "game" => "jawaker"]);
$ctx = stream_context_create(["http" => ["method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n", "content" => $body]]);
echo file_get_contents("__ORIGIN__/v1/jobs/instant-redeem", false, $ctx);
payload := strings.NewReader(`{"player_id":"1850890235","codes":["9W726P9AE7"],"game":"jawaker"}`)
req, _ := http.NewRequest("POST", BASE+"/v1/jobs/instant-redeem", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

iTunes (Apple Gift Card)

An Apple Gift Card's balance, read at Apple's US store without redeeming it. iTunes is check only: no player id, no packs, never redeemed. A card is 16 letters and digits starting with X, and may be sent grouped (XXXX XXXX XXXX XXXX) or plain.

gameitunes
RoutesPOST /v1/codes/check (up to 20) and POST /v1/jobs/code-check (bulk). No lookup, redeem or stock.
Resultsvalid — a live card; its dollar balance is in value_label (e.g. "$25.00"). used — a zero-balance card (error: "error_zero_balance_card", value_label: "$0.00"). invalid — an invalid or already-redeemed card: Apple does not tell the two apart (error: "error_invalid_or_used_card", never "never existed"). unknown/error — not read (never billed).
ValueAlways returned in value_label; shell_amount and amount stay null. with_value changes nothing.
SpeedThe first read after a quiet spell can take up to a minute; reads are quick after that.
Billing1 request per card that got a verdict, like every check. A Code checking subscription pays first.
{ "codes": ["XP3PCYC5G4ZKRL73", "XJF6RM5XG8HFMHM7"], "game": "itunes" }
iTunes — check balances
curl -sS -X POST "${BASE}/v1/codes/check" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"codes":["XP3PCYC5G4ZKRL73","XJF6RM5XG8HFMHM7"],"game":"itunes"}'
requests.post(f"{BASE}/v1/codes/check", headers=HEAD,
              json={"codes": ["XP3PCYC5G4ZKRL73", "XJF6RM5XG8HFMHM7"], "game": "itunes"}, timeout=120)
await fetch(`${BASE}/v1/codes/check`, {
  method: "POST", headers: HEAD,
  body: JSON.stringify({ codes: ["XP3PCYC5G4ZKRL73", "XJF6RM5XG8HFMHM7"], game: "itunes" }),
});
<?php
$body = json_encode(["codes" => ["XP3PCYC5G4ZKRL73", "XJF6RM5XG8HFMHM7"], "game" => "itunes"]);
$ctx = stream_context_create(["http" => ["method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n", "content" => $body]]);
echo file_get_contents("__ORIGIN__/v1/codes/check", false, $ctx);
payload := strings.NewReader(`{"codes":["XP3PCYC5G4ZKRL73","XJF6RM5XG8HFMHM7"],"game":"itunes"}`)
req, _ := http.NewRequest("POST", BASE+"/v1/codes/check", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

Razer Gold

A Razer Gold PIN check. A live PIN comes back valid and is not spent. Razer is check only: no player id, no packs, never redeemed. A PIN is 14 digits (02666801250212) or 14 or 16 letters and digits (MPBWMQLFR77YCR, BX8HURXKDKQRYGBQ).

Razer recharge (game=razer_recharge) sends that same PIN to your wallet, so a live PIN is credited. Include email and password. The password signs the account in and is not stored. A failed sign-in, a banned wallet that cannot be recharged, a wallet that is not activated yet, or a wallet already at its limit sends no PIN and is not charged. A credited PIN comes back recharged; a spent one used; a wrong one invalid. 5 requests per PIN that got a verdict. region and balance_after name the wallet.

gamerazer
RoutesPOST /v1/codes/check (up to 20) and POST /v1/jobs/code-check (bulk). No lookup, redeem or stock.
Resultsvalid — a live, unused PIN. used — already redeemed (error: "error_used_card"). invalid — no such PIN (error: "error_invalid_card"). error — not read (never billed).
ValueNone. A Razer read carries no value; with_value changes nothing.
Billing5 requests per PIN that got a verdict, not 1. A Code checking subscription pays first, drawing 5 from the budget per PIN.
{ "codes": ["MPBWMQLFR77YCR", "02666801250212"], "game": "razer" }
Razer Gold — check PINs
curl -sS -X POST "${BASE}/v1/codes/check" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d '{"codes":["MPBWMQLFR77YCR","02666801250212"],"game":"razer"}'
requests.post(f"{BASE}/v1/codes/check", headers=HEAD,
              json={"codes": ["MPBWMQLFR77YCR", "02666801250212"], "game": "razer"}, timeout=120)
await fetch(`${BASE}/v1/codes/check`, {
  method: "POST", headers: HEAD,
  body: JSON.stringify({ codes: ["MPBWMQLFR77YCR", "02666801250212"], game: "razer" }),
});
<?php
$body = json_encode(["codes" => ["MPBWMQLFR77YCR", "02666801250212"], "game" => "razer"]);
$ctx = stream_context_create(["http" => ["method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n", "content" => $body]]);
echo file_get_contents("__ORIGIN__/v1/codes/check", false, $ctx);
payload := strings.NewReader(`{"codes":["MPBWMQLFR77YCR","02666801250212"],"game":"razer"}`)
req, _ := http.NewRequest("POST", BASE+"/v1/codes/check", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

Telegram alerts for API jobs

The bot can message you when an API redeem finishes, which is the fastest way to watch an integration in production without building your own dashboard. In @ZadTopBot: Subscription → HTTP API → Settings.

Success alertsOne message per finished job with at least one credited card, including the amount and a button that renders the receipt.
Failure alertsSent when a job fails outright (quota, validation, interruption) or when every card in it was refused.
IndependentAlerts are a convenience, not a delivery guarantee: your integration should still read the job result.

Full integration recipe

A complete order: confirm the player, redeem, read every row, save the receipt, log what to retry.

One order, end to end
# 1) confirm the player
curl -sS "${BASE}/v1/player/lookup?player_id=123456789" -H "X-API-Key: $KEY"

# 2) queue the redeem
JOB=$(curl -sS -X POST "${BASE}/v1/jobs/instant-redeem" -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"123456789","codes":["4233939008625064"]}' \
  | sed -n 's/.*"job_id":"\([^"]*\)".*/\1/p')

# 3) wait for the outcome
DOC=$(curl -sS "${BASE}/v1/jobs/$JOB?wait=25" -H "X-API-Key: $KEY")
echo "$DOC"

# 4) receipt for the first successful row
HID=$(echo "$DOC" | sed -n 's/.*"history_id":"\([^"]*\)".*/\1/p')
curl -sS -X POST "${BASE}/v1/order/screenshot" -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" -d "{\"history_id\":\"$HID\"}" -o receipt.png
import pathlib
import time

import requests

BASE = "__ORIGIN__"
KEY = "pk_YOUR_KEY_HERE"
HEAD = {"X-API-Key": KEY, "Content-Type": "application/json"}

RETRYABLE = {"NETWORK", "SESSION_EXPIRED", "RATE_LIMITED", "VERIFICATION", "VERIFICATION_FAILED", "SHOP_BLOCKED"}


def sell(player_id: str, codes: list[str]) -> dict:
    look = requests.get(f"{BASE}/v1/player/lookup", headers=HEAD, params={"player_id": player_id}, timeout=60)
    if look.status_code == 404:
        raise ValueError("player id does not exist")
    nickname = look.json().get("player_name", "") if look.ok else ""

    job = requests.post(
        f"{BASE}/v1/jobs/instant-redeem",
        headers=HEAD,
        json={"player_id": player_id, "codes": codes, "game": "freefire"},
        timeout=30,
    ).json()

    end = time.time() + 300
    doc = {}
    while time.time() < end:
        doc = requests.get(f"{BASE}/v1/jobs/{job['job_id']}?wait=25", headers=HEAD, timeout=40).json()
        if doc.get("status") in ("done", "failed"):
            break

    if doc.get("status") != "done":
        raise RuntimeError(doc.get("error") or "job did not finish")

    res = doc["result"]
    retry, dead = [], []
    for row in res["results"]:
        if row["success"]:
            continue
        (retry if row.get("err_code") in RETRYABLE else dead).append(row["code"])

    if res["ok_count"]:
        png = requests.post(
            f"{BASE}/v1/order/screenshot",
            headers=HEAD,
            json={"history_id": res["history_id"], "result_index": 0, "lang": "en"},
            timeout=60,
        )
        if png.status_code == 200:
            pathlib.Path(f"receipt_{res['history_id']}.png").write_bytes(png.content)

    return {"nickname": nickname, "credited": res["credited"], "retry": retry, "dead": dead}


print(sell("123456789", ["4233939008625064"]))
const BASE = "__ORIGIN__";
const HEAD = { "X-API-Key": "pk_YOUR_KEY_HERE", "Content-Type": "application/json" };
const RETRYABLE = new Set(["NETWORK", "SESSION_EXPIRED", "RATE_LIMITED", "VERIFICATION", "VERIFICATION_FAILED", "SHOP_BLOCKED"]);

export async function sell(playerId, codes) {
  const look = await fetch(`${BASE}/v1/player/lookup?player_id=${playerId}`, { headers: HEAD });
  if (look.status === 404) throw new Error("player id does not exist");

  const job = await (await fetch(`${BASE}/v1/jobs/instant-redeem`, {
    method: "POST",
    headers: HEAD,
    body: JSON.stringify({ player_id: playerId, codes, game: "freefire" }),
  })).json();

  let doc;
  const end = Date.now() + 300000;
  while (Date.now() < end) {
    doc = await (await fetch(`${BASE}/v1/jobs/${job.job_id}?wait=25`, { headers: HEAD })).json();
    if (doc.status === "done" || doc.status === "failed") break;
  }
  if (doc.status !== "done") throw new Error(doc.error || "job did not finish");

  const retry = [], dead = [];
  for (const row of doc.result.results) {
    if (row.success) continue;
    (RETRYABLE.has(row.err_code) ? retry : dead).push(row.code);
  }
  return { credited: doc.result.credited, historyId: doc.result.history_id, retry, dead };
}
<?php
// 1) lookup  2) POST instant-redeem  3) poll /v1/jobs/{id}?wait=25
// 4) for each result row: success -> deliver, err_code in
//    [NETWORK, SESSION_EXPIRED, RATE_LIMITED, VERIFICATION, VERIFICATION_FAILED, SHOP_BLOCKED] -> retry later,
//    otherwise -> retire the code
// 5) POST /v1/order/screenshot with result.history_id to store the receipt PNG
// 1) GET  /v1/player/lookup?player_id=…
// 2) POST /v1/jobs/instant-redeem  -> job_id
// 3) GET  /v1/jobs/{job_id}?wait=25 until status is done or failed
// 4) range over result.results: success, else switch on err_code (retry vs retire)
// 5) POST /v1/order/screenshot with result.history_id -> receipt.png
Checklist for production: keep the key server-side · store job_id next to your own order id · never auto-resend a code after interrupted:process_restart without checking history · retry 503 SERVICE_DRAINING and 429 with backoff · reconcile daily through /v1/history.

Swagger — interactive testing

Authorise with X-API-Key, then call any endpoint straight from the browser. The embedded frame below is convenient, but a full tab is easier to read.

Open Swagger in new tab Same origin · full window

OpenAPI 3 · embedded preview ReDoc openapi.json