API documentation
Place Free Fire, Mobile Legends, Magic Chess: Go Go and Blood Strike orders from your own software. Each order is paid by your own supplier account.
Get started
Authentication
Send your API key in the Authorization header of every request.
Authorization: Bearer YOUR_API_KEYKeep the key on your server. Anyone who has it can spend the Shell and Smile Coin on your accounts, so never put it in a website or a phone app.
An API key works only on the order and item endpoints on this page.
List item codes
GET/api/items
Returns what one game sells now, read live through your default account, with the item code to send in an order.
| Field | Notes |
|---|---|
gamequery · Required | The game: freefire, mobilelegends, magicchessgogo or bloodstrike. |
regionquery · Optional | Free Fire only, and required there: KH, MY, SG, PH, VN or TW. |
| Game | Notes |
|---|---|
freefire | Free Fire. Its item code carries the shop region: freefire-KH-100. |
mobilelegends | Mobile Legends. Send serverId (the Zone ID) with the order. |
magicchessgogo | Magic Chess: Go Go. Send serverId with the order. |
bloodstrike | Blood Strike. No serverId and no region. |
curl "https://topupkit.com/api/items?game=freefire®ion=KH" \
-H "Authorization: Bearer YOUR_API_KEY"{
"ok": true,
"data": [
{
"item": "freefire-KH-100",
"name": "100 Diamonds",
"price": "86 Shell",
"costMinorUnits": 15652
},
{
"item": "freefire-KH-weekly_membership",
"name": "Weekly Membership",
"price": "160 Shell",
"costMinorUnits": null
}
]
}Place an order
POST/api/orders
Accepts the order and answers straight away with status pending. The payment then runs in the background, usually in under a minute and at most about three minutes. Get the result by reading the order, or from a callback. A refused order is still an order, with its reason on it.
Request
| Field | Notes |
|---|---|
Authorizationheader · Required | Bearer, then your API key. |
Idempotency-Keyheader · Optional | Your own unique name for this order, up to 255 characters. Strongly recommended. |
itemstring · Required | The item code from the item list: freefire-KH-100 for Free Fire, which carries the shop region, or mobilelegends-22590. It says which game the order is for. |
playerIdstring · Required | The player who receives the item. Digits only, up to 20. |
serverIdstring · Optional | Only for games that ask for it: the Mobile Legends Zone ID or the Magic Chess: Go Go Server ID. Leave it out otherwise. |
accountIdstring · Optional | Optional. The supplier account that pays. Without it, your default account for that supplier (and region, for Free Fire) pays. |
curl -X POST "https://topupkit.com/api/orders" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: my-order-1001" \
-d '{
"item": "freefire-KH-100",
"playerId": "123456789"
}'{
"item": "mobilelegends-22590",
"playerId": "123456789",
"serverId": "2001"
}201 for a new order. 200 when this Idempotency-Key was already used: you get the first order back and nothing is paid again.
{
"ok": true,
"data": {
"id": "0b6f6c1e-8a57-4f0a-9d3e-1f2a7c4b9e10",
"supplier": "garena",
"game": "freefire",
"item": "freefire-KH-100",
"region": "KH",
"serverId": null,
"playerId": "123456789",
"status": "pending",
"playerNickname": null,
"itemName": null,
"price": null,
"providerReference": null,
"supplierMessage": null,
"failureReason": null,
"createdAt": "2026-01-15T08:30:00.000Z",
"settledAt": null
}
}The order object
| Field | Notes |
|---|---|
idstring | The order’s ID, for reading it later. |
supplierstring | Who filled the order: garena or smileone. |
gamestring | The game: freefire, mobilelegends, magicchessgogo or bloodstrike. |
itemstring | The item code from the item list: freefire-KH-100 for Free Fire, which carries the shop region, or mobilelegends-22590. It says which game the order is for. |
regionstring | null | Free Fire's shop region. Null for other games. |
serverIdstring | null | The server ID sent with the order. Null when the game has none. |
playerIdstring | The player who receives the item. Digits only, up to 20. |
statusstring | See Order statuses. |
playerNicknamestring | null | The player's name, once the supplier gave it. |
itemNamestring | null | The supplier's own name for the item. Null for Free Fire. |
pricestring | null | What Garena charged or would charge, as text, such as 13 Shell. Null for other games. |
providerReferencestring | null | The supplier's transaction ID, whenever it gave one. |
supplierMessagestring | null | The supplier's own words when it refused the order. |
failureReasonstring | null | Why the order failed. Set only when status is failed. |
createdAtstring | When the order was created (ISO date). |
settledAtstring | null | When the supplier's answer was saved (ISO date). Null while pending. |
Order statuses
| Status | Meaning |
|---|---|
success | The supplier accepted the order and took the Shell or Smile Coin. |
failed | The supplier took nothing. failureReason says why. |
unknown | The answer was lost, so the Shell or Smile Coin may or may not have been spent. Check your account's history before ordering again. |
pending | Accepted and still being paid. Read the order again, or wait for the callback. After 10 minutes it becomes unknown. |
Failure reasons
Set on a failed order. In every case the supplier took nothing.
| Code | Meaning |
|---|---|
player_not_found | Garena does not know this player ID. No Shell was taken. |
player_region_not_allowed | This shop can't sell to this player's region. No Shell was taken. |
item_not_available | This item isn't available for this player right now. No Shell was taken. |
insufficient_shell | This Garena account doesn't have enough Shell. No Shell was taken. |
otp_rejected | Garena did not accept the authenticator code. Check the account's authenticator secret. No Shell was taken. |
garena_refused | Garena refused this order. No Shell was taken. |
garena_unavailable | Could not reach Garena. Try again in a moment. No Shell was taken. |
smileone_account_expired | The account's cookie stopped working. Paste a new one. Nothing was paid. |
smileone_refused | SmileOne refused this order. Nothing was paid. |
smileone_unavailable | SmileOne could not be reached. Nothing was paid. |
Read one order
GET/api/orders/{id}
Returns the order with this ID. Ask every few seconds until status is no longer pending.
List orders
GET/api/orders
Returns your orders, newest first, 20 to a page. Add ?supplier=garena or ?supplier=smileone for one supplier, ?search= to match an order id, a player id or a reference, and ?page= to read further back.
Callbacks
A callback (also called a webhook) is a request we send to your server when an order placed with your API key finishes, so you do not need to keep asking. It uses the same order object, and only comes once status is success, failed or unknown. Reading the order always works too.
On the API keys page, press Callback on your key and enter an https:// address. You get a signing secret once. Press Send a test to check your server: the test has the header X-Callback-Event: test, and a made-up order.
POST /your-callback-url
Content-Type: application/json
X-Callback-Event: order.settled
X-Callback-Timestamp: 1768465804
X-Callback-Signature: sha256=5f8d0c…
{
"id": "0b6f6c1e-8a57-4f0a-9d3e-1f2a7c4b9e10",
"supplier": "garena",
"game": "freefire",
"item": "freefire-KH-100",
"region": "KH",
"serverId": null,
"playerId": "123456789",
"status": "success",
"playerNickname": "FF_Player",
"itemName": null,
"price": "86 Shell",
"providerReference": "GARENA_TRANSACTION_ID",
"supplierMessage": null,
"failureReason": null,
"createdAt": "2026-01-15T08:30:00.000Z",
"settledAt": "2026-01-15T08:30:04.000Z"
}Check the signature before you trust a callback. It is the HMAC-SHA256 of the timestamp, a dot, and the exact body, using your signing secret.
import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody: the request body exactly as received, before JSON.parse.
const expected = Buffer.from(
"sha256=" +
createHmac("sha256", SIGNING_SECRET)
.update(`${headers["x-callback-timestamp"]}.${rawBody}`)
.digest("hex"),
);
const received = Buffer.from(headers["x-callback-signature"] ?? "");
const age = Date.now() / 1000 - Number(headers["x-callback-timestamp"]);
const genuine =
received.length === expected.length &&
timingSafeEqual(received, expected) &&
Math.abs(age) < 300;Anyone who finds your address can send it a fake “success”. Without this check they could get items for free.
Answer with a 2xx status within 10 seconds. Any other answer is tried again, up to five more times over about six hours. You may receive the same order twice, so use the order’s id to ignore repeats. We do not follow redirects, and addresses on private networks are refused.
Retrying safely
If a request times out, you cannot tell whether it was paid. Send it again with the same Idempotency-Key: the first order comes back and nothing is paid twice. Without that header, every request is a new order and can pay again.
Response format
Every response is JSON with an ok field. When ok is true, the result is in data. When it is false, branch on error.code: error.message can change.
{
"ok": false,
"error": {
"code": "UNAUTHORIZED",
"message": "…"
}
}Errors
A refused order is not an error: it comes back with status failed. These codes mean the request itself could not be handled.
| Code | Meaning |
|---|---|
400INVALID_JSON | Something went wrong sending this. Refresh the page and try again. |
400VALIDATION_ERROR | A field is missing or wrong. error.message names the problem. |
401UNAUTHORIZED | The API key is missing, wrong or removed. |
404NOT_FOUND | This order does not exist, or is not yours. |
409NO_DEFAULT_ACCOUNT | No account is chosen to pay API orders for this game. Open the Garena or SmileOne page and press “Use for API orders” on one account. |
409GARENA_ACCOUNT_NOT_READY_FOR_ORDERS | This Garena account isn't set up for orders yet. Enter its UID and authenticator secret first. |
413PAYLOAD_TOO_LARGE | This is too large to send. Shorten the note or other long fields and try again. |
500INTERNAL_ERROR | Something went wrong on our side. Try again in a moment. |