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

Choose which account pays API orders: open its page and press “Use for API orders”. Garena needs one for each region. Garena · SmileOne
Ask for the item codes a game sells now, with the item list request below.
Send your first order with the request below.

Authentication

Send your API key in the Authorization header of every request.

Authorization
Authorization: Bearer YOUR_API_KEY

Keep 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.

FieldNotes
gamequery · RequiredThe game: freefire, mobilelegends, magicchessgogo or bloodstrike.
regionquery · OptionalFree Fire only, and required there: KH, MY, SG, PH, VN or TW.
GameNotes
freefireFree Fire. Its item code carries the shop region: freefire-KH-100.
mobilelegendsMobile Legends. Send serverId (the Zone ID) with the order.
magicchessgogoMagic Chess: Go Go. Send serverId with the order.
bloodstrikeBlood Strike. No serverId and no region.
Example request
curl "https://topupkit.com/api/items?game=freefire&region=KH" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example response
{
  "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

FieldNotes
Authorizationheader · RequiredBearer, then your API key.
Idempotency-Keyheader · OptionalYour own unique name for this order, up to 255 characters. Strongly recommended.
itemstring · RequiredThe 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 · RequiredThe player who receives the item. Digits only, up to 20.
serverIdstring · OptionalOnly for games that ask for it: the Mobile Legends Zone ID or the Magic Chess: Go Go Server ID. Leave it out otherwise.
accountIdstring · OptionalOptional. The supplier account that pays. Without it, your default account for that supplier (and region, for Free Fire) pays.
Example request
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"
  }'
Example body for Mobile Legends
{
  "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.

Example response
{
  "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

FieldNotes
idstringThe order’s ID, for reading it later.
supplierstringWho filled the order: garena or smileone.
gamestringThe game: freefire, mobilelegends, magicchessgogo or bloodstrike.
itemstringThe 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 | nullFree Fire's shop region. Null for other games.
serverIdstring | nullThe server ID sent with the order. Null when the game has none.
playerIdstringThe player who receives the item. Digits only, up to 20.
statusstringSee Order statuses.
playerNicknamestring | nullThe player's name, once the supplier gave it.
itemNamestring | nullThe supplier's own name for the item. Null for Free Fire.
pricestring | nullWhat Garena charged or would charge, as text, such as 13 Shell. Null for other games.
providerReferencestring | nullThe supplier's transaction ID, whenever it gave one.
supplierMessagestring | nullThe supplier's own words when it refused the order.
failureReasonstring | nullWhy the order failed. Set only when status is failed.
createdAtstringWhen the order was created (ISO date).
settledAtstring | nullWhen the supplier's answer was saved (ISO date). Null while pending.

Order statuses

StatusMeaning
successThe supplier accepted the order and took the Shell or Smile Coin.
failedThe supplier took nothing. failureReason says why.
unknownThe answer was lost, so the Shell or Smile Coin may or may not have been spent. Check your account's history before ordering again.
pendingAccepted 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.

CodeMeaning
player_not_foundGarena does not know this player ID. No Shell was taken.
player_region_not_allowedThis shop can't sell to this player's region. No Shell was taken.
item_not_availableThis item isn't available for this player right now. No Shell was taken.
insufficient_shellThis Garena account doesn't have enough Shell. No Shell was taken.
otp_rejectedGarena did not accept the authenticator code. Check the account's authenticator secret. No Shell was taken.
garena_refusedGarena refused this order. No Shell was taken.
garena_unavailableCould not reach Garena. Try again in a moment. No Shell was taken.
smileone_account_expiredThe account's cookie stopped working. Paste a new one. Nothing was paid.
smileone_refusedSmileOne refused this order. Nothing was paid.
smileone_unavailableSmileOne 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.

What your server receives
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.

Node.js
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.

error
{
  "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.

CodeMeaning
400INVALID_JSONSomething went wrong sending this. Refresh the page and try again.
400VALIDATION_ERRORA field is missing or wrong. error.message names the problem.
401UNAUTHORIZEDThe API key is missing, wrong or removed.
404NOT_FOUNDThis order does not exist, or is not yours.
409NO_DEFAULT_ACCOUNTNo 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_ORDERSThis Garena account isn't set up for orders yet. Enter its UID and authenticator secret first.
413PAYLOAD_TOO_LARGEThis is too large to send. Shorten the note or other long fields and try again.
500INTERNAL_ERRORSomething went wrong on our side. Try again in a moment.